Discord Bot API セットアップガイド

開発しているボットを Discord に接続しようとして、セッション管理や Gateway の設定に苦労したことはありませんか？複数のチャンネルや DM を整理し、メッセージを正しくルーティングするのは意外と手間がかかるものです。

このガイドでは、公式の Discord Gateway を介して DM やギルドチャンネルでボットを稼働させる最短ルートを紹介します。

必要なもの

セットアップを始める前に、以下の 2 点を準備してください。

Discord Bot Token: Discord Developer Portal で作成したアプリケーションのボット用トークン。
特権 Intent の有効化: Developer Portal の「Bot」セクションで、Message Content Intent と Server Members Intent（名前から ID への変換や許可リストの照合に推奨）をオンにする必要があります。

クイックスタート

5 分で Discord 接続を完了させる手順です。

1. Discord ボットの作成と Intent の設定

Discord Developer Portal でアプリケーションを作成し、ボットを追加します。その後、以下の Intent を有効にしてください。

Message Content Intent
Server Members Intent

2. トークンの設定

設定ファイル（JSON5）にトークンを記述します。

{
  channels: {
    discord: {
      enabled: true,
      token: "YOUR_BOT_TOKEN",
    },
  },
}

デフォルトアカウントを使用する場合は、環境変数での設定も可能です。

DISCORD_BOT_TOKEN=...

注：設定ファイルのトークンは環境変数よりも優先されます。DISCORD_BOT_TOKEN はデフォルトアカウントのみで使用されます。

3. ボットの招待と Gateway の起動

メッセージ権限を付与した状態で、ボットをサーバーに招待します。その後、以下のコマンドで Gateway を起動してください。

openclaw gateway

4. 初回の DM ペアリングを承認

DM での利用にはペアリングが必要です。以下のコマンドで承認を行います。

openclaw pairing list discord
openclaw pairing approve discord <CODE>

Runtime model

動作の仕組みについて、重要なポイントをまとめました。

接続管理: Gateway が Discord との接続を維持します。
ルーティング: Discord からの入力に対する返信は、自動的に同じ Discord チャンネルへ戻ります。
セッションの分離: ギルドチャンネル（サーバー）はチャンネルごとに独立したセッションキー（agent:<agentId>:discord:channel:<channelId>）を持ちますが、DM はデフォルトでメインセッションを共有します。
Slash commands: ネイティブの Slash commands は独立したセッション（agent:<agentId>:discord:slash:<userId>）で実行されますが、会話セッションへ CommandTargetSessionKey を引き継ぎます。

また、グループ DM はデフォルトで無視される設定（channels.discord.dm.groupEnabled=false）になっています。

トラブルシューティング

よくある問題と解決策です。

ペアリングコードが機能しない: ペアリングコードの有効期限は 1 時間です。期限が切れた場合は、再度リストを確認して新しいコードを取得してください。
メッセージが届かない: チャンネル固有の診断や修復フローが必要な場合があります。公式の診断ツールを実行してください。

セットアップで困ったことがあれば、AI Setup Assistant に相談してください。

次のステップ

Discordボットを運用していると、誰がどこでボットを使えるようにするか、その設定に迷うことがありますよね。セキュリティをガチガチに固めすぎて動かなかったり、逆にオープンすぎて予期せぬ場所でボットが反応したりするのは避けたいものです。適切なアクセス制御を行うことは、ユーザーのプライバシーを守り、ボットの動作を安定させるために非常に重要です。

ここでは、OpenClawを使用してDiscordのDMやサーバー（Guild）での挙動を管理する方法を解説します。

## 必要なもの

設定を始める前に、以下の準備ができているか確認してください。

- Discord Developer Portalへのアクセス権限
- Discord Bot Token
- ターゲットとなるサーバーID、チャンネルID、ユーザーID（Discordの「デベロッパーモード」を有効にしてコピーしてください）

## クイックスタート

まずは最小限の構成でボットを動かしてみましょう。

1.  **Discord Developer Portal** で **New Application** を作成し、**Bot** セクションからボットを追加してトークンをコピーします。
2.  **Privileged Gateway Intents** セクションで、`Message Content Intent` と `Server Members Intent` を有効にします。
3.  **OAuth URL Generator** で、scopesに `bot` と `applications.commands` を選択します。
4.  必要な権限（View Channels, Send Messages, Read Message History, Embed Links, Attach Files）を選択してボットをサーバーに招待します。
5.  設定ファイルに `channels.discord` ブロックを追加します。IDは信頼性を高めるために数値形式を使用してください。

## DM（ダイレクトメッセージ）の制御

`channels.discord.dm.policy` を使用して、DMへのアクセスを管理できます。

- `pairing` (デフォルト): ペアリング済みのユーザーのみ許可。
- `allowlist`: 許可リストに登録されたユーザーのみ。
- `open`: 全員に開放（`channels.discord.dm.allowFrom` に `"*"` を含める必要があります）。
- `disabled`: DMを無効化。

DMポリシーが `open` ではない場合、不明なユーザーからのメッセージはブロックされるか、`pairing` モードであればペアリングを促すプロンプトが表示されます。宛先の指定には `user:<id>` または `<@id>` 形式を使用してください。数値だけのIDは曖昧なため拒否される場合があります。

## サーバー（Guild）のポリシー設定

サーバー内での挙動は `channels.discord.groupPolicy` で制御します。

- `open`
- `allowlist`
- `disabled`

`channels.discord` ブロックが存在する場合、セキュリティの観点から推奨されるベースラインは `allowlist` です。

`allowlist` の挙動は以下の通りです。
- サーバーID（推奨）またはスラグが `channels.discord.guilds` に一致する必要があります。
- サーバー内に `channels` が設定されている場合、リストにないチャンネルは拒否されます。
- サーバー内に `channels` ブロックがない場合は、そのサーバー内のすべてのチャンネルが許可されます。

以下は、特定のサーバーとチャンネルを許可する設定例です。

```json
{
  channels: {
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        "123456789012345678": {
          requireMention: true,
          users: ["987654321098765432"],
          channels: {
            general: { allow: true },
            help: { allow: true, requireMention: true },
          },
        },
      },
    },
  },
}

もし DISCORD_BOT_TOKEN のみを設定し、channels.discord ブロックを作成しなかった場合、ランタイムのフォールバックとして groupPolicy="open" が適用されます（ログに警告が表示されます）。

メンションとグループDM

サーバー内でのメッセージは、デフォルトでメンションが必要です。

メンションの検知には以下のパターンが含まれます。

ボットへの直接のメンション
設定されたメンションパターン（agents.list[].groupChat.mentionPatterns、またはフォールバックの messages.groupChat.mentionPatterns）
サポートされているケースでの、ボットへの返信（implicit reply）

requireMention は、サーバーごと、またはチャンネルごとに設定可能です。

グループDMについては、デフォルトでは無視されます（dm.groupEnabled=false）。必要に応じて dm.groupChannels にチャンネルIDまたはスラグを指定することで、許可リストを作成できます。

ネイティブコマンドと認証

commands.native はデフォルトで "auto" に設定されており、Discordで有効になります。
チャンネルごとに channels.discord.commands.native で上書き設定が可能です。
commands.native=false に設定すると、登録済みのDiscordネイティブコマンドが明示的に削除されます。
ネイティブコマンドの実行権限は、通常のメッセージ処理と同じ許可リストやポリシーが適用されます。
権限のないユーザーに対してもDiscord UI上でコマンドが表示されることがありますが、実行時に OpenClaw の認証が行われ、「not authorized」が返されます。

トラブルシューティング

不明なユーザーがブロックされる: DMポリシーが pairing または allowlist になっていないか確認してください。
IDが拒否される: 数値のみのIDを指定していませんか？ user:<id> などのプレフィックスを付けるか、設定ブロック内で適切なコンテキスト（guilds や users のキーなど）に配置してください。
ボットが反応しない: Message Content Intent が有効になっているか、または requireMention の設定でメンションが必要になっていないか確認してください。
権限エラー: Administrator 権限は避け、必要な権限（View Channels, Send Messages等）のみを付与することをお勧めします。

設定で迷ったことがあれば、AI Setup Assistant も活用してみてください。

次のステップ

Slash commands: コマンドのカタログと挙動の詳細
Agent configuration: エージェントごとのメンションパターンの設定

Discord ボットを運用していると、メッセージのやり取りが複雑になり、エージェントがどのメッセージに対して返信すべきか迷ってしまうことがあります。また、スレッドの文脈を正しく理解させたり、特定のユーザーからのリアクションをトリガーにしたりといった細かい制御が必要になる場面も多いでしょう。

Discord 連携の機能を詳しく知ることで、エージェントの振る舞いをより細かくカスタマイズできます。

必要なもの

設定を始める前に、以下の準備ができているか確認してください。

Discord チャンネルの設定権限
channels.discord の基本設定
PluralKit 連携を使用する場合は、PluralKit の API トークン（任意）

クイックスタート

まずは、エージェントの応答性と文脈の理解を向上させるための最小限の設定から始めましょう。

履歴制限の設定: エージェントが参照する過去のメッセージ数を channels.discord.historyLimit で設定します（デフォルトは 20）。
返信モードの有効化: channels.discord.replyToMode を first または all に設定して、Discord のネイティブな返信機能を使えるようにします。

機能の詳細解説

返信タグとネイティブ返信

Discord では、エージェントの出力に返信タグを含めることができます。

[[reply_to_current]]
[[reply_to:<id>]]

これらは channels.discord.replyToMode で制御されます。

off (デフォルト)
first
all

メッセージ ID はコンテキストや履歴に表示されるため、エージェントは特定のメッセージをターゲットに設定できます。

履歴、コンテキスト、スレッドの挙動

サーバー（Guild）内での履歴コンテキストの設定は以下の通りです。

channels.discord.historyLimit: デフォルトは 20 です。
フォールバックとして messages.groupChat.historyLimit が参照されます。
0 に設定すると無効になります。

DM（ダイレクトメッセージ）の履歴は、以下のパスで制御できます。

channels.discord.dmHistoryLimit
channels.discord.dms["<user_id>"].historyLimit

スレッドの挙動については、Discord のスレッドはチャンネルセッションとしてルーティングされます。親スレッドのメタデータを使用して親セッションと紐付けることができ、スレッド固有の設定がない限り、スレッドの設定は親チャンネルの設定を継承します。

なお、チャンネルのトピック（Channel topics）は、システムプロンプトとしてではなく、信頼できない（untrusted） コンテキストとして注入されます。

リアクション通知

サーバーごとのリアクション通知モードは以下の通りです。

off
own (デフォルト)
all
allowlist (guilds.<id>.users を使用)

リアクションイベントはシステムイベントに変換され、ルーティングされた Discord セッションに付加されます。

設定の書き込み（Config writes）

チャンネルから開始される設定の書き込みは、デフォルトで有効です。これは、コマンド機能が有効な場合の /config set|unset フローに影響します。

無効にする場合は、以下の設定を記述してください。

{
  channels: {
    discord: {
      configWrites: false,
    },
  },
}

PluralKit のサポート

プロキシされたメッセージをシステムのメンバー ID にマッピングするために、PluralKit の解決を有効にできます。

{
  channels: {
    discord: {
      pluralkit: {
        enabled: true,
        token: "pk_live_...", // 任意：プライベートシステムに必要
      },
    },
  },
}

注意点：

許可リスト（allowlists）には pk:<memberId> を使用できます。
メンバーの表示名は名前またはスラッグで照合されます。
照合には元のメッセージ ID が使用され、時間枠の制限があります。
照合に失敗した場合、プロキシされたメッセージはボットメッセージとして扱われ、allowBots=true でない限り破棄されます。

Discord での実行承認（Exec approvals）

Discord では、DM 内でボタンベースの実行承認（exec approvals）を行えます。

設定パス：

channels.discord.execApprovals.enabled
channels.discord.execApprovals.approvers
agentFilter, sessionFilter, cleanupAfterResolve

トラブルシューティング

設定中に問題が発生した場合は、以下を確認してください。

承認 ID が不明（unknown approval IDs）で失敗する場合: 承認者リスト（approver list）が正しく設定されているか、および機能自体が有効になっているかを確認してください。

最後に

設定についてさらに詳しく知りたい場合や、具体的な構成の相談が必要な場合は、AI Setup Assistant を活用してください。

次のステップ

Discord ボットを開発していると、権限管理の難しさに直面することがあります。特定のチャンネルではメッセージを送りたいけれど、勝手にメンバーをキックされるのは困る、といった細かな制御が必要です。API が実行できる操作を正しく制限することは、安全な運用に欠かせません。

必要なもの

Discord 連携の設定権限
channels.discord.actions.* へのアクセス

クイックスタート

Discord のメッセージ操作には、メッセージ送信、チャンネル管理、モデレーション、プレゼンス、メタデータに関する操作が含まれます。

主な例は以下の通りです：

messaging: sendMessage, readMessages, editMessage, deleteMessage, threadReply
reactions: react, reactions, emojiList
moderation: timeout, kick, ban
presence: setPresence

これらの操作を制御する Action Gates は channels.discord.actions.* の下に配置されています。

デフォルトの設定を確認しましょう。多くの操作は最初から有効ですが、セキュリティに関わる重要な操作は無効化されています。

Action group	Default
reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions	enabled
roles	disabled
moderation	disabled
presence	disabled

トラブルシューティング

「モデレーション操作が実行できない」という場合は、Action Gates の設定を確認してください。moderation や roles などのグループは、デフォルトで disabled に設定されています。これらを使用するには、設定を明示的に変更する必要があります。

また、presence の変更（setPresence）についても、デフォルトでは disabled になっている点に注意してください。

困ったときは AI Setup Assistant に質問してください。

次のステップ

Discord Botを開発していると、コードは正しいはずなのにメッセージが全く届かない、といった状況によく直面します。Gatewayの設定や権限の微調整に時間を取られて、肝心の機能開発が止まってしまうのはストレスが溜まりますよね。

設定ミスは誰にでもあることですが、原因を特定するためのポイントを押さえておけば、デバッグの時間を大幅に短縮できます。

必要なもの

作業を始める前に、以下の準備ができているか確認してください。

Discord Bot Token
OpenClaw CLI
Discord Developer Portalへのアクセス権限

クイックスタート

まずは、最短で問題を診断するための手順です。

環境変数に DISCORD_BOT_TOKEN を設定します。
以下のコマンドを実行して、基本的な接続と設定を確認します。

openclaw doctor
openclaw channels status --probe
openclaw logs --follow

トラブルシューティング

よくある問題と、その解決策をまとめました。

インテントの設定エラー、またはメッセージが表示されない

Message Content Intent を有効にしてください。
ユーザーやメンバーの解決が必要な場合は、Server Members Intent を有効にします。
インテントの設定を変更した後は、必ず Gateway を再起動してください。

ギルドメッセージが予期せずブロックされる

groupPolicy の設定が正しいか確認してください。
channels.discord.guilds の下にあるギルドの allowlist を確認します。
ギルドの channels マップが存在する場合、リストされているチャンネルのみが許可されます。
requireMention の挙動と、メンションのパターンが正しいか確認してください。

診断に役立つコマンド：

openclaw doctor
openclaw channels status --probe
openclaw logs --follow

requireMention が false なのにブロックされる

主な原因は以下の通りです：

ギルドやチャンネルの allowlist が一致していないのに、groupPolicy="allowlist" が設定されている。
requireMention の設定場所が間違っている（channels.discord.guilds または各チャンネルのエントリの下に配置する必要があります）。
送信者がギルドやチャンネルの users allowlist によってブロックされている。

権限監査の不一致

channels status --probe による権限チェックは、数値のチャンネル ID に対してのみ機能します。スラグ（slug）キーを使用している場合、実行時のマッチングは動作しますが、probe コマンドで権限を完全に検証することはできません。

DM とペアリングの問題

DM が無効になっていないか確認してください： channels.discord.dm.enabled=false
DM ポリシーが無効になっていないか確認してください： channels.discord.dm.policy="disabled"
pairing モードを使用している場合、ペアリングの承認待ち状態でないか確認してください。

Bot 同士のループ

デフォルトでは、Bot が作成したメッセージは無視されます。 channels.discord.allowBots=true を設定する場合は、ループを避けるために厳格なメンションルールと allowlist を適用してください。

Configuration reference pointers

設定の詳細については、以下のリファレンスを参照してください。

Configuration reference - Discord

特に重要な Discord 関連フィールド：

起動・認証: enabled, token, accounts.*, allowBots
ポリシー: groupPolicy, dm.*, guilds.*, guilds.*.channels.*
コマンド: commands.native, commands.useAccessGroups, configWrites
返信・履歴: replyToMode, historyLimit, dmHistoryLimit, dms.*.historyLimit
配信: textChunkLimit, chunkMode, maxLinesPerMessage
メディア・リトライ: mediaMaxMb, retry
アクション: actions.*
機能: pluralkit, execApprovals, intents, agentComponents, heartbeat, responsePrefix

Safety and operations

Bot の運用を安全に行うためのベストプラクティスです。

Bot Token は機密情報として扱ってください。管理された環境では DISCORD_BOT_TOKEN 環境変数の使用を推奨します。
Discord の権限は、必要最小限の範囲（Least-privilege）で付与してください。
コマンドのデプロイや状態が古いと感じる場合は、Gateway を再起動し、openclaw channels status --probe で再度確認してください。

解決しない問題がある場合は、AI Setup Assistant に質問してみてください。

次のステップ

OpenClaw Expert

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。