Discord

OpenClaw は、公式の Discord gateway を介してボットとして Discord に接続します。DM とギルドチャンネルに対応しています。

クイックセットアップ

ボットを含む Discord アプリケーションを作成し、ボットをサーバーに追加して、OpenClaw とペアリングします。可能であればプライベートサーバーを使用してください。必要な場合は、先にサーバーを作成します（Create My Own > For me and my friends）。

export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"cat > discord.patch.json5 <<'JSON5'{channels: {discord: {  enabled: true,  token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" },},},}JSON5openclaw config patch --file ./discord.patch.json5 --dry-runopenclaw config patch --file ./discord.patch.json5openclaw gateway

{channels: {discord: {enabled: true,token: {source: "env",provider: "default",id: "DISCORD_BOT_TOKEN",},},},}

DISCORD_BOT_TOKEN=...

{channels: {discord: {enabled: true,accounts: {personal: {  token: { source: "env", provider: "default", id: "DISCORD_PERSONAL_TOKEN" },  applicationId: "111111111111111111",},work: {  token: { source: "env", provider: "default", id: "DISCORD_WORK_TOKEN" },  applicationId: "222222222222222222",},},},},}

openclaw pairing list discordopenclaw pairing approve discord <CODE>

推奨：ギルドワークスペースをセットアップする

DM が機能したら、サーバーを完全なワークスペースにできます。各チャンネルには、それぞれ独自のコンテキストを持つエージェントセッションが割り当てられます。自分とボットだけが参加するプライベートサーバーに推奨します。

{channels: {discord: {groupPolicy: "allowlist",guilds: {YOUR_SERVER_ID: {  requireMention: true,  users: ["YOUR_USER_ID"],},},},},}

{channels: {discord: {guilds: {YOUR_SERVER_ID: {  requireMention: false,},},},},}

これでチャンネルを作成してチャットを開始できます。エージェントはチャンネル名を認識し、各チャンネルは分離されたセッションになります。ワークフローに合わせて #coding、#home、#research などをセットアップしてください。

ランタイムモデル

• Gateway が Discord 接続を管理します。
• 返信のルーティングは決定的です。Discord から受信したメッセージへの返信は Discord に返されます。
• Discord のギルド／チャンネルメタデータは、ユーザーに表示される返信プレフィックスではなく、信頼できないコンテキストとしてモデルプロンプトに追加されます。モデルがそのエンベロープを返信にコピーした場合、OpenClaw は送信返信と今後の再生コンテキストから、コピーされたメタデータを削除します。
• デフォルト（session.dmScope=main）では、ダイレクトチャットはエージェントのメインセッション（agent:main:main）を共有します。
• ギルドチャンネルには分離されたセッションキー（agent:<agentId>:discord:channel:<channelId>）が割り当てられます。
• グループ DM はデフォルトで無視されます（channels.discord.dm.groupEnabled=false）。
• ネイティブのスラッシュコマンドは分離されたコマンドセッション（agent:<agentId>:discord:slash:<userId>）で実行されますが、ルーティング先の会話セッションへの CommandTargetSessionKey は引き続き保持されます。
• Discord へのテキストのみの Cron／Heartbeat 通知配信は、アシスタントに表示される最終回答にまとめられ、1 回だけ送信されます。エージェントが配信可能な複数のペイロードを出力した場合、メディアおよび構造化コンポーネントのペイロードは複数メッセージのまま維持されます。

フォーラムチャンネル

Discord のフォーラムチャンネルとメディアチャンネルでは、スレッド投稿のみ受け付けられます。OpenClaw では、次の 2 つの方法でスレッド投稿を作成できます。

• フォーラムの親 (channel:<forumId>) にメッセージを送信すると、スレッドが自動作成されます。スレッドのタイトルには、メッセージの最初の空でない行が使用されます（Discord のスレッド名の上限である100文字に切り詰められます）。
• スレッドを直接作成するには、openclaw message thread create を使用します。フォーラムチャンネルでは --message-id を渡さないでください。

フォーラムの親に送信してスレッドを作成します。

openclaw message send --channel discord --target channel:<forumId> \  --message "Topic title\nBody of the post"

フォーラムスレッドを明示的に作成します。

openclaw message thread create --channel discord --target channel:<forumId> \  --thread-name "Topic title" --message "Body of the post"

フォーラムの親は Discord コンポーネントを受け付けません。コンポーネントが必要な場合は、スレッド自体 (channel:<threadId>) に送信してください。

インタラクティブコンポーネント

OpenClaw は、エージェントメッセージ用に Discord コンポーネント v2 コンテナをサポートしています。components ペイロードを指定してメッセージツールを使用します。インタラクションの結果は通常の受信メッセージとしてエージェントにルーティングされ、既存の Discord replyToMode 設定に従います。

サポートされているブロック:

• text、section、separator、actions、media-gallery、file
• アクション行には、最大5個のボタンまたは単一の選択メニューを配置できます
• 選択タイプ: string、user、role、mentionable、channel

デフォルトでは、コンポーネントは1回だけ使用できます。ボタン、選択項目、フォームを期限切れまで複数回使用できるようにするには、components.reusable=true を設定します。

ボタンをクリックできるユーザーを制限するには、そのボタンに allowedUsers（Discord ユーザー ID、タグ、または *）を設定します。一致しないユーザーには、本人だけに見える拒否メッセージが表示されます。

コンポーネントのコールバックは、デフォルトで30分後に期限切れになります。デフォルトアカウントのコールバックレジストリの有効期間を変更するには channels.discord.agentComponents.ttlMs を設定し、アカウントごとに変更するには channels.discord.accounts.<accountId>.agentComponents.ttlMs を設定します。値の単位はミリ秒で、正の整数である必要があり、上限は 86400000（24時間）です。長い TTL は、ボタンを継続して使用可能にする必要があるレビューや承認のワークフローに適していますが、古い Discord メッセージから引き続きアクションを実行できる期間も長くなります。要件を満たす最短の TTL を選び、古いコールバックが意外な動作につながる場合はデフォルトのままにしてください。

/model および /models スラッシュコマンドは、プロバイダー、モデル、互換性のあるランタイムのドロップダウンと Submit ステップを備えたインタラクティブなモデル選択画面を開きます。/models add は非推奨であり、チャットからモデルを登録する代わりに非推奨メッセージを返します。選択画面の応答は本人だけに表示され、呼び出したユーザーのみが使用できます。Discord の選択メニューは25個の選択肢に制限されているため、openai や vllm など、選択したプロバイダーについてのみ動的に検出されたモデルを選択画面に表示する場合は、agents.defaults.models に provider/* エントリを追加します。

ファイル添付:

• file ブロックは添付ファイル参照 (attachment://<filename>) を指す必要があります
• 添付ファイルは media/path/filePath（単一ファイル）で指定します。複数ファイルには media-gallery を使用します
• アップロード名を添付ファイル参照と一致させる必要がある場合は、filename を使用して上書きします

モーダルフォーム:

• 最大5個のフィールドを持つ components.modal を追加します
• フィールドタイプ: text、checkbox、radio、select、role-select、user-select
• OpenClaw はトリガーボタンを自動的に追加します

例:

{  channel: "discord",  action: "send",  to: "channel:123456789012345678",  message: "Optional fallback text",  components: {    reusable: true,    text: "Choose a path",    blocks: [      {        type: "actions",        buttons: [          {            label: "Approve",            style: "success",            allowedUsers: ["123456789012345678"],          },          { label: "Decline", style: "danger" },        ],      },      {        type: "actions",        select: {          type: "string",          placeholder: "Pick an option",          options: [            { label: "Option A", value: "a" },            { label: "Option B", value: "b" },          ],        },      },    ],    modal: {      title: "Details",      triggerLabel: "Open form",      fields: [        { type: "text", label: "Requester" },        {          type: "select",          label: "Priority",          options: [            { label: "Low", value: "low" },            { label: "High", value: "high" },          ],        },      ],    },  },}

アクセス制御とルーティング

{accessGroups: {operators: {  type: "message.senders",  members: {    "*": ["global-owner-id"],    discord: ["discord:123456789012345678"],    telegram: ["987654321"],  },},},channels: {discord: {  dmPolicy: "allowlist",  allowFrom: ["accessGroup:operators"],},},}

{accessGroups: {maintainers: {  type: "discord.channelAudience",  guildId: "1456350064065904867",  channelId: "1456744319972282449",  membership: "canViewChannel",},},channels: {discord: {  dmPolicy: "allowlist",  allowFrom: ["accessGroup:maintainers"],},},}

{accessGroups: {maintainers: {  type: "discord.channelAudience",  guildId: "1456350064065904867",  channelId: "1456744319972282449",},},channels: {discord: {  dmPolicy: "allowlist",  allowFrom: ["accessGroup:maintainers", "discord:123456789012345678"],},},}

{channels: {discord: {  groupPolicy: "allowlist",  guilds: {    "123456789012345678": {      requireMention: true,      ignoreOtherMentions: true,      users: ["987654321098765432"],      roles: ["123456789012345678"],      channels: {        general: { enabled: true },        help: { enabled: true, requireMention: true },      },    },  },},},}

ロールベースのエージェントルーティング

Discord ギルドメンバーをロール ID に基づいて別のエージェントへルーティングするには、bindings[].match.roles を使用します。ロールベースのバインディングはロール ID のみを受け付け、ピアまたは親ピアのバインディングの後、ギルドのみのバインディングの前に評価されます。バインディングに他の一致フィールド（例: peer + guildId + roles）も設定されている場合、設定されたすべてのフィールドが一致する必要があります。

{  bindings: [    {      agentId: "opus",      match: {        channel: "discord",        guildId: "123456789012345678",        roles: ["111111111111111111"],      },    },    {      agentId: "sonnet",      match: {        channel: "discord",        guildId: "123456789012345678",      },    },  ],}

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

• commands.native のデフォルトは "auto" で、Discord では有効です。
• チャンネルごとの上書き: channels.discord.commands.native。
• commands.native=false にすると、起動時の Discord スラッシュコマンドの登録とクリーンアップをスキップします。以前に登録されたコマンドは、Discord アプリから削除するまで Discord に表示され続ける場合があります。
• ネイティブコマンドの認可には、通常のメッセージ処理と同じ Discord の許可リストとポリシーが使用されます。
• 認可されていないユーザーにも Discord UI 上でコマンドが表示される場合がありますが、実行時には OpenClaw の認可が適用され、「認可されていません」と応答します。
• スラッシュコマンドのデフォルト設定: ephemeral: true（channels.discord.slashCommand.ephemeral）。

コマンド一覧と動作については、スラッシュコマンドを参照してください。

機能の詳細

{channels: {discord: {  suppressEmbeds: false,},},}

{channels: {discord: {  streaming: {    mode: "progress",    progress: {      label: "auto",      maxLines: 8,      maxLineChars: 120,      toolProgress: true,      commentary: false,    },  },},},}

{  "channels": {    "discord": {      "streaming": {        "mode": "progress",        "progress": {          "toolProgress": true,          "commandText": "status"        }      }    }  }}

{session: {threadBindings: {  enabled: true,  idleHours: 24,  maxAgeHours: 0,},},channels: {discord: {  threadBindings: {    enabled: true,    idleHours: 24,    maxAgeHours: 0,    spawnSessions: true,    defaultSpawnContext: "fork",  },},},}

{agents: {list: [  {    id: "codex",    runtime: {      type: "acp",      acp: {        agent: "codex",        backend: "acpx",        mode: "persistent",        cwd: "/workspace/openclaw",      },    },  },],},bindings: [{  type: "acp",  agentId: "codex",  match: {    channel: "discord",    accountId: "default",    peer: { kind: "channel", id: "222222222222222222" },  },  acp: { label: "codex-main" },},],channels: {discord: {  guilds: {    "111111111111111111": {      channels: {        "222222222222222222": {          requireMention: false,        },      },    },  },},},}

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

{channels: {discord: {  proxy: "http://proxy.example:8080",},},}

{channels: {discord: {  accounts: {    primary: {      proxy: "http://proxy.example:8080",    },  },},},}

{channels: {discord: {  pluralkit: {    enabled: true,    token: "pk_live_...", // 任意。非公開システムには必要  },},},}

{channels: {discord: {  mentionAliases: {    SupportLead: "123456789012345678",  },  accounts: {    ops: {      mentionAliases: {        OpsLead: "234567890123456789",      },    },  },},},}

{channels: {discord: {  status: "idle",},},}

{channels: {discord: {  activity: "Focus time",  activityType: 4,},},}

{channels: {discord: {  activity: "Live coding",  activityType: 1,  activityUrl: "https://twitch.tv/openclaw",},},}

{channels: {discord: {  autoPresence: {    enabled: true,    intervalMs: 30000,    minUpdateIntervalMs: 15000,    exhaustedText: "token exhausted",  },},},}

ツールとアクションゲート

Discord のメッセージアクションは、メッセージング、チャンネル管理、モデレーション、プレゼンス、メタデータを対象とします。

主な例:

• メッセージング: sendMessage、readMessages、editMessage、deleteMessage、threadReply
• リアクション: react、reactions、emojiList
• モデレーション: timeout、kick、ban
• プレゼンス: setPresence

event-create アクションは、スケジュールされたイベントのカバー画像を設定するための任意の image パラメーター（URL またはローカルファイルパス）を受け付けます。

アクションゲートは channels.discord.actions.* 配下にあります。

ゲートの既定動作:

コンポーネント v2 UI

OpenClaw は、実行承認とコンテキスト間マーカーに Discord コンポーネント v2 を使用します。Discord のメッセージアクションは、カスタム UI 用の components も受け付けます（高度な機能。discord ツールを使用してコンポーネントのペイロードを構築する必要があります）。従来の embeds も引き続き使用できますが、推奨されません。

• channels.discord.ui.components.accentColor は、Discord のコンポーネントコンテナーで使用されるアクセントカラー（16 進数）を設定します。アカウントごとの設定: channels.discord.accounts.<id>.ui.components.accentColor。
• channels.discord.agentComponents.ttlMs は、送信済み Discord コンポーネントのコールバックが登録されたままになる期間を制御します（既定値 1800000、最大値 86400000）。アカウントごとの設定: channels.discord.accounts.<id>.agentComponents.ttlMs。
• コンポーネント v2 が存在する場合、embeds は無視されます。
• プレーン URL のプレビューは既定で抑制されます。単一の送信リンクを展開する必要がある場合は、メッセージアクションに suppressEmbeds: false を設定します。

例:

{  channels: {    discord: {      ui: {        components: {          accentColor: "#5865F2",        },      },    },  },}

音声

Discord には、リアルタイムのボイスチャンネル（継続的な会話）と、ボイスメッセージの添付ファイル（波形プレビュー形式）という 2 つの異なる音声機能があります。Gateway は両方をサポートします。

ボイスチャンネル

セットアップチェックリスト:

1. Discord Developer Portal で Message Content Intent を有効にします。
2. ロールまたはユーザーの許可リストを使用する場合は、Server Members Intent を有効にします。
3. bot および applications.commands スコープを指定してボットを招待します。
4. 対象のボイスチャンネルで Connect、Speak、Send Messages、Read Message History を許可します。
5. ネイティブコマンド（commands.native または channels.discord.commands.native）を有効にします。
6. channels.discord.voice を設定します。

セッションを制御するには /vc join|leave|status を使用します。このコマンドはアカウントの既定エージェントを使用し、他の Discord コマンドと同じ許可リストおよびグループポリシーのルールに従います。

/vc join channel:<voice-channel-id>/vc status/vc leave

参加前にボットの実効権限を確認するには、次を実行します。

openclaw channels capabilities --channel discord --target channel:<voice-channel-id>

自動参加の例:

{  channels: {    discord: {      voice: {        enabled: true,        model: "openai/gpt-5.6-sol",        autoJoin: [          {            guildId: "123456789012345678",            channelId: "234567890123456789",          },        ],        allowedChannels: [          {            guildId: "123456789012345678",            channelId: "234567890123456789",          },        ],        daveEncryption: true,        decryptionFailureTolerance: 24,        connectTimeoutMs: 30000,        reconnectGraceMs: 15000,        realtime: {          provider: "openai",          model: "gpt-realtime-2.1",          speakerVoice: "cedar",        },      },    },  },}

注記:

• Discord音声はテキスト専用設定ではオプトインです。channels.discord.voice.enabled=true を設定（または既存の channels.discord.voice ブロックを維持）すると、/vc コマンド、音声ランタイム、GuildVoiceStates Gatewayインテントが有効になります。channels.discord.intents.voiceStates でインテントのサブスクリプションを明示的に上書きできます。未設定のままにすると、実際の音声有効化状態に従います。
• voice.mode は会話経路を制御します。デフォルトは agent-proxy です。リアルタイム音声フロントエンドがターンのタイミング、中断、再生を処理し、実質的な作業を openclaw_agent_consult を介してルーティング先のOpenClawエージェントに委任し、その結果をその話者が入力したDiscordプロンプトと同様に扱います。stt-tts は従来のバッチSTTとTTSを組み合わせたフローを維持します。bidi では、OpenClawの頭脳として openclaw_agent_consult を公開しながら、リアルタイムモデルが直接会話できます。
• voice.agentSession は、どのOpenClaw会話が音声ターンを受け取るかを制御します。音声チャンネル自身のセッションを使用する場合は未設定のままにします。または { mode: "target", target: "channel:<text-channel-id>" } を設定すると、音声チャンネルを #maintainers などの既存Discordテキストチャンネルセッションのマイク／スピーカー拡張として機能させられます。
• voice.model は、Discord音声応答とリアルタイム相談で使用するOpenClawエージェントの頭脳を上書きします。ルーティング先エージェントのモデルを継承する場合は未設定のままにします。これは voice.realtime.model とは別です。
• voice.followUsers を使用すると、選択したユーザーに合わせてボットがDiscord音声へ参加、移動、退出できます。音声でユーザーを追従するを参照してください。
• agent-proxy は音声を discord-voice 経由でルーティングします。これにより、話者と対象セッションに対する通常の所有者／ツール認可を維持しつつ、Discord音声が再生を担当するため、エージェントの tts ツールは非表示になります。デフォルトでは、agent-proxy は所有者である話者からの相談に、所有者と同等の完全なツールアクセスを付与し（voice.realtime.toolPolicy: "owner"）、実質的な回答の前にOpenClawエージェントへ相談することを強く優先します（voice.realtime.consultPolicy: "always"）。このデフォルトの always モードでは、リアルタイム層は相談回答の前に場つなぎの発話を自動再生しません。音声を取得して文字起こしし、その後ルーティング先OpenClawの回答を読み上げます。Discordが最初の回答を再生している間に、強制相談による回答が複数完了した場合、後続の逐語発話回答は文の途中で音声を置き換えず、再生がアイドル状態になるまでキューに入ります。
• stt-tts モードでは、STTは tools.media.audio を使用します。voice.model は文字起こしには影響しません。
• リアルタイムモードでは、voice.realtime.provider、voice.realtime.model、voice.realtime.speakerVoice がリアルタイム音声セッションを設定します。OpenAI Realtime 2.1とCodexの頭脳を組み合わせる場合は、voice.realtime.model: "gpt-realtime-2.1" と voice.model: "openai/gpt-5.6-sol" を使用します。
• リアルタイム音声モードでは、デフォルトで小さな IDENTITY.md、USER.md、SOUL.md プロファイルファイルをリアルタイムプロバイダーの指示に含めるため、高速な直接ターンでも、ルーティング先OpenClawエージェントと同じアイデンティティ、ユーザーに関する基礎情報、ペルソナが維持されます。これをカスタマイズするには voice.realtime.bootstrapContextFiles にサブセットを設定し、無効にするには [] を設定します。サポートされるのはこれらのプロファイルファイルのみです。AGENTS.md は通常のエージェントコンテキストに残ります。注入されたプロファイルコンテキストは、ワークスペース作業、最新情報、メモリ検索、ツールに裏付けられた操作において openclaw_agent_consult を置き換えるものではありません。
• OpenAIの agent-proxy リアルタイムモードでは、voice.realtime.requireWakeName: true を設定すると、文字起こしがウェイク名で始まるか終わるまで、Discordリアルタイム音声を無音に保てます。設定するウェイク名は1語または2語でなければなりません。voice.realtime.wakeNames が未設定の場合、OpenClawはルーティング先エージェントの name と OpenClaw を使用し、フォールバックとしてエージェントIDと OpenClaw を使用します。ウェイク名ゲーティングは、リアルタイムプロバイダーの自動応答を無効化し、受け付けたターンをOpenClawエージェントの相談経路にルーティングします。また、最終的な文字起こしが届く前に、部分的な文字起こしから先頭のウェイク名を認識すると、短い音声確認を返します。
• OpenAIリアルタイムプロバイダーは、出力音声および文字起こしイベントについて、現在のRealtime 2イベント名と従来のCodex互換エイリアスを受け付けます。そのため、互換性のあるプロバイダースナップショットに差異が生じても、アシスタント音声が失われません。
• voice.realtime.bargeIn は、Discordの話者開始イベントによって、再生中のリアルタイム音声を中断するかどうかを制御します。未設定の場合、リアルタイムプロバイダーの入力音声中断設定に従います。
• voice.realtime.minBargeInAudioEndMs は、OpenAIリアルタイムの割り込みによって音声が打ち切られるまでに必要な、アシスタント再生の最小継続時間を制御します。デフォルトは 250 です。エコーが少ない部屋で即時中断するには 0 を設定し、スピーカーのエコーが強い環境では値を増やします。
• voice.tts は、stt-tts の音声再生に限って messages.tts を上書きします。リアルタイムモードでは代わりに voice.realtime.speakerVoice を使用します。Discord再生でOpenAI音声を使用するには、voice.tts.provider: "openai" を設定し、voice.tts.providers.openai.speakerVoice でテキスト読み上げ音声を選択します。現在のOpenAI TTSモデルでは、cedar が男性的な声として適しています。
• チャンネルごとのDiscord systemPrompt 上書きは、その音声チャンネルの音声文字起こしターンにも適用されます。
• 音声文字起こしターンは、所有者限定コマンドとチャンネル操作に使用する所有者ステータスを、Discordの allowFrom（または dm.allowFrom）から取得します。エージェントツールの可視性は、ルーティング先セッションに設定されたツールポリシーに従います。
• voice.autoJoin に同じギルドのエントリが複数ある場合、OpenClawはそのギルドについて最後に設定されたチャンネルへ参加します。
• voice.allowedChannels は、滞在を許可する任意の許可リストです。未設定のままにすると、認可された任意のDiscord音声チャンネルに /vc join で参加できます。設定すると、/vc join、起動時の自動参加、ボットの音声状態移動は、列挙された { guildId, channelId } エントリに制限されます。空の配列に設定すると、Discord音声への参加をすべて拒否します。Discordによってボットが許可リスト外へ移動された場合、OpenClawはそのチャンネルから退出し、設定済みの自動参加先があれば再参加します。
• voice.daveEncryption と voice.decryptionFailureTolerance は、@discordjs/voice の参加オプションにそのまま渡されます。アップストリームのデフォルトは daveEncryption=true と decryptionFailureTolerance=24 です。
• OpenClawは、Discord音声の受信とリアルタイム生PCM再生に、同梱の libopus-wasm コーデックを使用します。固定バージョンのlibopus WebAssemblyビルドが同梱されており、ネイティブopusアドオンは不要です。
• voice.connectTimeoutMs は、/vc join と自動参加の試行時に、最初の @discordjs/voice Readyを待つ時間を制御します。デフォルトは 30000 です。
• voice.reconnectGraceMs は、切断された音声セッションを破棄する前に、OpenClawが再接続の開始を待つ時間を制御します。デフォルトは 15000 です。
• stt-tts モードでは、別のユーザーが話し始めただけでは音声再生は停止しません。フィードバックループを避けるため、OpenClawはTTS再生中の新しい音声取得を無視します。次のターンでは、再生が終了してから話してください。リアルタイムモードでは、話者開始を割り込みシグナルとしてリアルタイムプロバイダーへ転送します。
• リアルタイムモードでは、スピーカーから開放状態のマイクへ入るエコーが割り込みと見なされ、再生が中断されることがあります。エコーが強いDiscordルームでは、voice.realtime.providers.openai.interruptResponseOnInputAudio: false を設定し、入力音声によるOpenAIの自動中断を防ぎます。Discordの話者開始イベントでは再生中の音声を引き続き中断したい場合、voice.realtime.bargeIn: true を追加します。OpenAIリアルタイムブリッジは、voice.realtime.minBargeInAudioEndMs より短い再生打ち切りをエコー／ノイズの可能性が高いものとして無視し、Discord再生をクリアせずにスキップとしてログに記録します。
• voice.captureSilenceGraceMs は、Discordが話者の発話停止を報告してから、その音声区間をSTT用に確定するまでOpenClawが待つ時間を制御します。デフォルトは 2000 です。Discordが通常の間を細切れの部分文字起こしに分割する場合は、値を増やしてください。
• ElevenLabsが選択されたTTSプロバイダーの場合、Discord音声再生はストリーミングTTSを使用し、プロバイダーの応答ストリームから再生を開始します。ストリーミングをサポートしないプロバイダーでは、合成済み一時ファイルを使用する経路にフォールバックします。
• OpenClawは受信時の復号失敗を監視し、短時間に繰り返し失敗した場合は、音声チャンネルから退出して再参加することで自動復旧します。
• 更新後、受信ログに DecryptionFailed(UnencryptedWhenPassthroughDisabled) が繰り返し表示される場合は、依存関係レポートとログを収集してください。同梱の @discordjs/voice 系列には、discord.jsのPR #11449に含まれるアップストリームのパディング修正が組み込まれており、この修正によってdiscord.jsのissue #11419はクローズされました。
• OpenClawが取得した話者区間を確定する際に発生する The operation was aborted 受信イベントは想定内です。これは詳細な診断情報であり、警告ではありません。
• Discord音声の詳細ログには、受け付けた話者区間ごとに、長さを制限した1行のSTT文字起こしプレビューが含まれます。これにより、無制限の文字起こしテキストを出力することなく、デバッグ時にユーザー側とエージェント応答側の両方を確認できます。
• agent-proxy モードでは、強制相談のフォールバックは、... で終わるテキストや「and」のような接続語で終わるテキストなど、未完了の可能性が高い文字起こし断片に加え、「be right back」や「bye」のような明らかに操作を必要としない締めの発話をスキップします。これにより古いキュー済み回答が防止された場合、ログには forced agent consult skipped reason=... と表示されます。

音声でユーザーを追従する

起動時に固定チャンネルへ参加したり、/vc join を待機したりする代わりに、Discord音声ボットを既知の1人以上のDiscordユーザーと同じ場所に滞在させたい場合は、voice.followUsers を使用します。

{  channels: {    discord: {      voice: {        enabled: true,        followUsersEnabled: true,        followUsers: ["discord:123456789012345678"],        allowedChannels: [          {            guildId: "123456789012345678",            channelId: "234567890123456789",          },        ],      },    },  },}

動作:

• followUsers は、生のDiscordユーザーIDと discord:<id> 値を受け付けます。OpenClawは音声状態イベントとの照合前に、両方の形式を正規化します。
• followUsers が設定されている場合、followUsersEnabled のデフォルトは true です。保存済みリストを維持しながら音声の自動追従を停止するには、false に設定します。
• 追従対象ユーザーが許可された音声チャンネルに参加すると、OpenClawもそのチャンネルに参加します。ユーザーが移動すると、OpenClawも一緒に移動します。現在追従中のユーザーが切断すると、OpenClawは退出します。
• 同じギルドに複数の追従対象ユーザーがいて、現在追従中のユーザーが退出した場合、OpenClawはギルドから退出する前に、追跡中の別の追従対象ユーザーのチャンネルへ移動します。複数の追従対象ユーザーが同時に移動した場合は、最後に観測された音声状態イベントが優先されます。
• allowedChannels は引き続き適用されます。許可されていないチャンネルにいる追従対象ユーザーは無視され、追従によって所有されているセッションは、別の追従対象ユーザーへ移動するか退出します。
• OpenClawは、起動時および上限が設定された間隔ごとに、見逃した音声状態イベントを整合させます。整合処理では設定済みギルドをサンプリングし、1回の実行あたりのREST検索数に上限を設けます。そのため、非常に大きな followUsers リストでは、収束に複数回の間隔が必要になる場合があります。
• ユーザーを追従中にDiscordまたは管理者がボットを移動した場合、移動先が許可されていれば、OpenClawは音声セッションを再構築し、追従所有権を維持します。ボットが allowedChannels の外へ移動された場合、OpenClawは退出し、設定済みの対象があれば再参加します。
• DAVE受信復旧では、復号失敗が繰り返された後、同じチャンネルから退出して再参加することがあります。追従によって所有されているセッションは、その復旧経路でも追従所有権を維持するため、その後に追従対象ユーザーが切断した場合もチャンネルから退出します。

参加モードの選択:

• 自分が音声に参加しているとき、ボットも自動的に音声へ参加させたい個人用または運用者向けの構成には、followUsers を使用します。
• 追跡対象ユーザーが音声にいない場合でも常駐させる固定ルームのボットには、autoJoin を使用します。
• 一度限りの参加や、自動的に音声へ常駐すると意外に感じられるルームには、/vc join を使用します。

Discord音声コーデック:

• 音声受信ログには discord voice: opus decoder: libopus-wasm と表示されます。
• リアルタイム再生では、生の48 kHzステレオPCMを同梱の同じ libopus-wasm パッケージでOpusにエンコードしてから、パケットを @discordjs/voice に渡します。
• ファイルおよびプロバイダーストリームの再生では、ffmpegを使用して生の48 kHzステレオPCMへトランスコードし、その後Discordへ送信するOpusパケットストリームに libopus-wasm を使用します。

STTとTTSのパイプライン:

• Discord の PCM キャプチャは一時 WAV ファイルに変換されます。
• tools.media.audio が STT を処理します（例: openai/gpt-4o-mini-transcribe）。
• トランスクリプトは Discord の受信処理とルーティングを経由して送信されます。その間、応答 LLM はエージェントの tts ツールを非表示にし、テキストを返すよう求める音声出力ポリシーで実行されます。これは、最終的な TTS 再生を Discord 音声が担当するためです。
• voice.model を設定すると、この音声チャンネルのターンに限り、応答 LLM のみが上書きされます。
• voice.tts は messages.tts に上書きマージされます。ストリーミング対応プロバイダーはプレイヤーへ直接データを送り、それ以外の場合は生成された音声ファイルが参加中のチャンネルで再生されます。

デフォルトのエージェントプロキシ音声チャンネルセッションの例:

{  channels: {    discord: {      voice: {        enabled: true,        model: "openai/gpt-5.6-sol",        followUsersEnabled: true,        followUsers: ["123456789012345678"],        realtime: {          provider: "openai",          model: "gpt-realtime-2.1",          speakerVoice: "cedar",        },      },    },  },}

voice.agentSession ブロックがない場合、各音声チャンネルに個別のルーティング済み OpenClaw セッションが割り当てられます。たとえば、/vc join channel:234567890123456789 は、その Discord 音声チャンネルのセッションと対話します。リアルタイムモデルは音声フロントエンドにすぎず、実質的なリクエストは設定済みの OpenClaw エージェントへ渡されます。リアルタイムモデルがコンサルトツールを呼び出さずに最終トランスクリプトを生成した場合、OpenClaw はフォールバックとしてコンサルトを強制し、デフォルトの動作が引き続きエージェントとの対話として機能するようにします。

従来の STT と TTS の例:

{  channels: {    discord: {      voice: {        enabled: true,        mode: "stt-tts",        model: "openai/gpt-5.4-mini",        tts: {          provider: "openai",          providers: {            openai: {              model: "gpt-4o-mini-tts",              speakerVoice: "cedar",            },          },        },      },    },  },}

リアルタイム双方向通信の例:

{  channels: {    discord: {      voice: {        enabled: true,        mode: "bidi",        model: "openai/gpt-5.6-sol",        realtime: {          provider: "openai",          model: "gpt-realtime-2.1",          speakerVoice: "cedar",          toolPolicy: "safe-read-only",          consultPolicy: "always",        },      },    },  },}

既存の Discord チャンネルセッションを拡張する音声の例:

{  channels: {    discord: {      voice: {        enabled: true,        mode: "agent-proxy",        model: "openai/gpt-5.6-sol",        agentSession: {          mode: "target",          target: "channel:123456789012345678",        },        realtime: {          provider: "openai",          model: "gpt-realtime-2.1",          speakerVoice: "cedar",        },      },    },  },}

agent-proxy モードでは、ボットは設定された音声チャンネルに参加しますが、OpenClaw エージェントのターンでは、対象チャンネルの通常のルーティング済みセッションとエージェントが使用されます。リアルタイム音声セッションは、返された結果を音声チャンネルで読み上げます。スーパーバイザーエージェントは引き続き、そのツールポリシーに従って通常のメッセージツールを使用でき、適切な処理であれば別の Discord メッセージを送信することもできます。

委任された OpenClaw の実行中は、別のエージェントターンを開始する前に、新しい Discord 音声トランスクリプトが実行中の処理に対するリアルタイム制御として扱われます。「状況は」「それをキャンセル」「より小さい修正を使って」「終わったらテストも確認して」などのフレーズは、アクティブなセッションに対するステータス確認、キャンセル、方向修正、またはフォローアップ入力として分類されます。ステータス、キャンセル、受け入れられた方向修正、フォローアップの結果は音声チャンネルへ読み上げられるため、発信者は OpenClaw がリクエストを処理したかどうかを確認できます。

使用可能な対象形式:

• target: "channel:123456789012345678" は Discord テキストチャンネルのセッション経由でルーティングします。
• target: "123456789012345678" はチャンネル対象として扱われます。
• target: "dm:123456789012345678" または target: "user:123456789012345678" は、そのダイレクトメッセージセッション経由でルーティングします。

エコーが多い環境向けの OpenAI Realtime の例:

{  channels: {    discord: {      voice: {        enabled: true,        mode: "bidi",        model: "openai/gpt-5.6-sol",        realtime: {          provider: "openai",          model: "gpt-realtime-2.1",          speakerVoice: "cedar",          bargeIn: true,          minBargeInAudioEndMs: 500,          consultPolicy: "always",          providers: {            openai: {              interruptResponseOnInputAudio: false,            },          },        },      },    },  },}

モデルが開放されたマイクを通じて自身の Discord 再生音を拾うものの、発話による割り込みは引き続き許可したい場合に使用します。OpenClaw は入力された生の音声による OpenAI の自動割り込みを防ぎます。一方、bargeIn: true にすると、次にキャプチャされたターンが OpenAI に到達する前に、Discord の話者開始イベントと、すでにアクティブな話者の音声によって、進行中のリアルタイム応答をキャンセルできます。audioEndMs が minBargeInAudioEndMs 未満の非常に早い割り込み信号は、エコーまたはノイズの可能性が高いものとして無視されるため、モデルが最初の再生フレームで途切れることはありません。

想定される音声ログ:

• 参加時: discord voice: joining ... voiceSession=... supervisorSession=... agentSessionMode=... voiceModel=... realtimeModel=...
• リアルタイム開始時: discord voice: realtime bridge starting ... autoRespond=false interruptResponse=false bargeIn=false minBargeInAudioEndMs=...
• 話者の音声受信時: discord voice: realtime speaker turn opened ...、discord voice: realtime input audio started ... outputAudioMs=... outputActive=...、および discord voice: realtime speaker turn closed ... chunks=... discordBytes=... realtimeBytes=... interruptedPlayback=...
• 古くなった発話をスキップしたとき: discord voice: realtime forced agent consult skipped reason=incomplete-transcript ... または reason=non-actionable-closing ...
• リアルタイム応答の完了時: discord voice: realtime audio playback finishing reason=response.done ... audioMs=... chunks=...
• 再生の停止またはリセット時: discord voice: realtime audio playback stopped reason=... audioMs=... elapsedMs=... chunks=...
• リアルタイムコンサルト時: discord voice: realtime consult requested ... voiceSession=... supervisorSession=... question=...
• エージェントの回答時: discord voice: agent turn answer ...
• 指定どおりの発話をキューに追加したとき: discord voice: realtime exact speech queued ... queued=... outputAudioMs=... outputActive=...、続いて discord voice: realtime exact speech dequeued reason=player-idle ...
• 割り込みの検出時: discord voice: realtime barge-in detected source=speaker-start ... または discord voice: realtime barge-in detected source=active-speaker-audio ...、続いて discord voice: realtime barge-in requested reason=... outputAudioMs=... outputActive=...
• リアルタイム割り込み時: discord voice: realtime model interrupt requested client:response.cancel reason=barge-in、続いて discord voice: realtime model audio truncated client:conversation.item.truncate reason=barge-in audioEndMs=... または discord voice: realtime model interrupt confirmed server:response.done status=cancelled ...
• エコーまたはノイズを無視したとき: discord voice: realtime model interrupt ignored client:conversation.item.truncate.skipped reason=barge-in audioEndMs=0 minAudioEndMs=250
• 割り込みが無効なとき: discord voice: realtime capture ignored during playback (barge-in disabled) ...
• 再生がアイドル状態のとき: discord voice: realtime barge-in ignored reason=... outputActive=false ... playbackChunks=0

音声が途中で途切れる問題をデバッグするには、リアルタイム音声ログを時系列として読み取ります。

1. realtime audio playback started は、Discord がアシスタント音声の再生を開始したことを示します。この時点から、ブリッジはアシスタント出力チャンク、Discord PCM バイト数、プロバイダーのリアルタイムバイト数、合成音声の再生時間をカウントし始めます。
2. realtime speaker turn opened は、Discord の話者がアクティブになったことを示します。再生がすでにアクティブで、bargeIn が有効な場合、その後に barge-in detected source=speaker-start が記録されることがあります。
3. realtime input audio started は、その話者ターンで最初の実際の音声フレームを受信したことを示します。ここで outputActive=true またはゼロ以外の outputAudioMs が記録されている場合、アシスタントの再生中にマイクが入力を送信しています。
4. barge-in detected source=active-speaker-audio は、アシスタントの再生中に OpenClaw が話者のリアルタイム音声を検出したことを示します。これは、実際の割り込みと、有効な音声を伴わない Discord の話者開始イベントを区別するのに役立ちます。
5. barge-in requested reason=... は、OpenClaw がリアルタイムプロバイダーに対し、進行中の応答のキャンセルまたは切り詰めを要求したことを示します。outputAudioMs、outputActive、playbackChunks が含まれるため、割り込み前に実際に再生されたアシスタント音声の量を確認できます。
6. realtime audio playback stopped reason=... は、Discord のローカル再生がリセットされた時点を示します。理由から、再生を停止した主体を確認できます。barge-in、player-idle、provider-clear-audio、forced-agent-consult、stream-close、または session-close のいずれかです。
7. realtime speaker turn closed は、キャプチャされた入力ターンの要約です。chunks=0 または hasAudio=false は、話者ターンは開始されたものの、使用可能な音声がリアルタイムブリッジに到達しなかったことを示します。interruptedPlayback=true は、その入力ターンがアシスタントの出力と重なり、割り込みロジックが作動したことを示します。

有用なフィールド:

• outputAudioMs: そのログ行までにリアルタイムプロバイダーが生成したアシスタント音声の再生時間。
• audioMs: 再生が停止するまでに OpenClaw がカウントしたアシスタント音声の再生時間。
• elapsedMs: 再生ストリームまたは話者ターンの開始から終了までの実時間。
• discordBytes: Discord 音声へ送信、または Discord 音声から受信した 48 kHz ステレオ PCM のバイト数。
• realtimeBytes: リアルタイムプロバイダーへ送信、またはリアルタイムプロバイダーから受信した、プロバイダー形式の PCM バイト数。
• playbackChunks: アクティブな応答について Discord へ転送されたアシスタント音声チャンク数。
• sinceLastAudioMs: 最後にキャプチャした話者音声フレームから話者ターン終了までの間隔。

一般的なパターン:

• source=active-speaker-audio と小さい outputAudioMs を伴う即時の途切れが発生し、同じユーザーが近くにいる場合、通常はスピーカーのエコーがマイクに入ったことを示します。voice.realtime.minBargeInAudioEndMs を増やす、スピーカー音量を下げる、ヘッドホンを使う、または voice.realtime.providers.openai.interruptResponseOnInputAudio: false を設定してください。
• source=speaker-start の後に speaker turn closed ... hasAudio=false が続く場合、Discord は話者の開始を報告したものの、音声は OpenClaw に到達していません。これは一時的な Discord 音声イベント、ノイズゲートの動作、またはクライアントが一瞬だけマイクを有効にしたことが原因の場合があります。
• 近くに割り込みや provider-clear-audio がない状態で audio playback stopped reason=stream-close が記録されている場合、Discord のローカル再生ストリームが予期せず終了しています。直前のプロバイダーと Discord プレイヤーのログを確認してください。
• capture ignored during playback (barge-in disabled) は、アシスタント音声の再生中に OpenClaw が意図的に入力を破棄したことを示します。発話で再生を中断したい場合は、voice.realtime.bargeIn を有効にしてください。
• barge-in ignored ... outputActive=false は、Discord またはプロバイダーの VAD が発話を報告したものの、OpenClaw に中断対象となるアクティブな再生がなかったことを示します。これによって音声が途切れることはありません。

認証情報はコンポーネントごとに解決されます。voice.model には LLM ルート認証、tools.media.audio には STT 認証、messages.tts/voice.tts には TTS 認証、voice.realtime.providers またはプロバイダーの通常の認証設定にはリアルタイムプロバイダー認証が使用されます。

音声メッセージ

Discord の音声メッセージには波形プレビューが表示され、OGG/Opus 音声が必要です。OpenClaw は波形を自動生成しますが、検査と変換のために Gateway ホスト上の ffmpeg と ffprobe が必要です。

• ローカルファイルパスを指定してください（URL は拒否されます）。
• テキスト内容は省略してください（Discord は同じペイロード内のテキストと音声メッセージの併用を拒否します）。
• どの音声形式でも受け付けます。OpenClaw が必要に応じて OGG/Opus に変換します。

message(action="send", channel="discord", target="channel:123", path="/path/to/audio.mp3", asVoice=true)

トラブルシューティング

openclaw doctoropenclaw channels status --probeopenclaw logs --follow

{channels: {discord: {  accounts: {    default: {      eventQueue: {        listenerTimeout: 120000,      },    },  },},},}

{channels: {defaults: {  botLoopProtection: {    maxEventsPerWindow: 20,    windowSeconds: 60,    cooldownSeconds: 60,  },},discord: {  // Optional Discord-wide override. Account blocks override individual  // fields and inherit omitted fields from here.  botLoopProtection: {    maxEventsPerWindow: 4,  },  accounts: {    alpha: {      // Alpha listens to other bots only when they mention it.      allowBots: "mentions",    },    bravo: {      // Bravo listens to all bot-authored Discord messages.      allowBots: true,      mentionAliases: {        // Lets Bravo write an Alpha Discord mention with the configured user id.        Alpha: "ALPHA_DISCORD_USER_ID",      },      botLoopProtection: {        // Allow up to five messages per minute before suppressing the pair.        maxEventsPerWindow: 5,        windowSeconds: 60,        cooldownSeconds: 90,      },    },  },},},}

設定リファレンス

主要リファレンス: 設定リファレンス - Discord。

安全性と運用

• ボットトークンはシークレットとして扱う（管理環境では DISCORD_BOT_TOKEN を推奨）。
• Discord の権限は最小権限で付与する。
• コマンドのデプロイまたは状態が古い場合は、Gateway を再起動し、openclaw channels status --probe で再確認する。

関連項目