Discord

​

クイックセットアップ

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" },
    },
  },
}
JSON5
openclaw config patch --file ./discord.patch.json5 --dry-run
openclaw config patch --file ./discord.patch.json5
openclaw 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 discord
openclaw pairing approve discord <CODE>

​

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

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

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

​

ランタイムモデル

• 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 回だけ送信されます。エージェントが配信可能なペイロードを複数出力した場合、メディアと構造化コンポーネントのペイロードは引き続き複数メッセージとして送信されます。

​

フォーラムチャンネル

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

openclaw message send --channel discord --target channel:<forumId> \
  --message "トピックのタイトル\n投稿の本文"

openclaw message thread create --channel discord --target channel:<forumId> \
  --thread-name "トピックのタイトル" --message "投稿の本文"

​

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

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

• 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: "任意のフォールバックテキスト",
  components: {
    reusable: true,
    text: "パスを選択",
    blocks: [
      {
        type: "actions",
        buttons: [
          {
            label: "承認",
            style: "success",
            allowedUsers: ["123456789012345678"],
          },
          { label: "却下", style: "danger" },
        ],
      },
      {
        type: "actions",
        select: {
          type: "string",
          placeholder: "オプションを選択",
          options: [
            { label: "オプション A", value: "a" },
            { label: "オプション B", value: "b" },
          ],
        },
      },
    ],
    modal: {
      title: "詳細",
      triggerLabel: "フォームを開く",
      fields: [
        { type: "text", label: "申請者" },
        {
          type: "select",
          label: "優先度",
          options: [
            { label: "低", value: "low" },
            { label: "高", 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 },
          },
        },
      },
    },
  },
}

​

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

{
  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 の認証が適用され、「not authorized」と応答します。
• デフォルトのスラッシュコマンド設定: ephemeral: true（channels.discord.slashCommand.ephemeral）。

​

機能の詳細

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

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

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

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

{
  channels: {
    discord: {
      subagentProgress: true,
    },
  },
}

{
  agents: {
    entries: {
      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: {
      intents: { presence: true },
      guilds: {
        "111111111111111111": {
          presenceEvents: {
            channelId: "222222222222222222",
            users: ["333333333333333333"], // 任意。チャンネルの閲覧者をさらに絞り込む
            reconnectSuppressSeconds: 300, // 任意。新規セッションの抑制時間（0 で無効化）
            burstLimit: 8, // 任意。バーストウィンドウあたりの最大イベント数
            burstWindowSeconds: 60, // 任意。スライド式バースト検出ウィンドウ
          },
        },
      },
    },
  },
}

{
  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: "集中時間",
      activityType: 4,
    },
  },
}

{
  channels: {
    discord: {
      activity: "ライブコーディング",
      activityType: 1,
      activityUrl: "https://twitch.tv/openclaw",
    },
  },
}

{
  channels: {
    discord: {
      autoPresence: {
        enabled: true,
        intervalMs: 30000,
        minUpdateIntervalMs: 15000,
        exhaustedText: "トークン枯渇",
      },
    },
  },
}

​

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

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

​

Components v2 UI

• 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。
• embeds は、components v2 が存在する場合は無視されます。
• プレーン URL のプレビューはデフォルトで抑制されます。単一の外部リンクを展開する必要がある場合は、メッセージアクションに suppressEmbeds: false を設定します。

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

​

音声

​

ボイスチャンネル

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 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 リアルタイムモードでは、ウェイクネームのゲートがデフォルトでルームの状況に適応します。人間が 1 人の場合はウェイクネームなしで自然に話せますが、2 人以上の場合は、ターンの先頭または末尾にウェイクネームを付ける必要があります。他のボットは人数に含まれません。ウェイクネームを常に必須にするには voice.realtime.requireWakeName: true、一切必須にしない場合は false を設定します。構成するウェイクネームは 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 音声再生に限り tts を上書きします。リアルタイムモードでは代わりに voice.realtime.speakerVoice を使用します。Discord 再生で OpenAI の音声を使用するには、voice.tts.provider: "openai" を設定し、voice.tts.providers.openai.speakerVoice でテキスト読み上げ音声を選択します。cedar は、現在の OpenAI TTS モデルで男性的に聞こえる適切な選択肢です。
• チャンネル単位の Discord systemPrompt の上書きは、その音声チャンネルの音声文字起こしターンに適用されます。
• OpenClaw が音声チャンネルに参加すると、ルーティング先のエージェントセッションは、現在の参加者一覧を含む無音のシステムイベントを受信します。その後の参加者の参加と退出によってそのセッションは更新されますが、要求されていない音声応答は発生しません。Discord の表示名は信頼されていないラベルとして扱われます。認可された音声ターンも最新の参加者一覧のスナップショットを受信します。
• 音声文字起こしターンと /vc コマンドは、所有者ステータスの判定に commands.ownerAllowFrom 内の Discord エントリを使用します。Discord コマンドの所有者が構成されていない場合でも、選択された Discord アカウントの allowFrom（または従来の dm.allowFrom）によって、所有者ステータスを付与せずに音声アクセスを認可できます。エージェントのツール表示可否は、ルーティング先セッションに構成されたツールポリシーに従います。
• voice.autoJoin に同じギルドのエントリが複数ある場合、OpenClaw はそのギルドで最後に構成されたチャンネルに参加します。
• voice.allowedChannels は、任意の滞在許可リストです。/vc join が認可済みの任意の Discord 音声チャンネルに参加できるようにするには、未設定のままにします。設定すると、/vc join、起動時の自動参加、およびボットの音声状態による移動が、一覧に含まれる { guildId, channelId } エントリに制限されます。Discord 音声へのすべての参加を拒否するには、空の配列に設定します。Discord がボットを許可リスト外へ移動した場合、OpenClaw はそのチャンネルから退出し、構成済みの自動参加先が利用可能であれば、そこへ再参加します。
• voice.daveEncryption と voice.decryptionFailureTolerance は、@discordjs/voice の参加オプションへそのまま渡されます。アップストリームのデフォルトは daveEncryption=true と decryptionFailureTolerance=24 です。
• OpenClaw は、Discord 音声の受信とリアルタイムの raw PCM 再生に、同梱の libopus-wasm コーデックを使用します。固定バージョンの libopus WebAssembly ビルドが同梱されており、ネイティブの opus アドオンは必要ありません。
• voice.connectTimeoutMs は、/vc join および自動参加の試行における、初回の @discordjs/voice Ready 待機時間を制御します。デフォルト: 30000。
• voice.reconnectGraceMs は、切断された音声セッションが再接続を開始するまで、OpenClaw がそのセッションを破棄せずに待機する時間を制御します。デフォルト: 15000。
• stt-tts モードでは、別のユーザーが話し始めただけでは音声再生は停止しません。フィードバックループを避けるため、OpenClaw は TTS の再生中に新しい音声取得を無視します。次のターンは、再生の終了後に話してください。リアルタイムモードでは、話者の発話開始が割り込み信号としてリアルタイムプロバイダーへ転送されます。
• リアルタイムモードでは、スピーカーから開放状態のマイクに入るエコーが割り込みとして認識され、再生を中断することがあります。エコーが多い Discord ルームでは、入力音声による OpenAI の自動中断を防ぐために voice.realtime.providers.openai.interruptResponseOnInputAudio: false を設定します。それでも Discord の話者開始イベントで進行中の再生を中断する場合は、voice.realtime.bargeIn: true を追加します。OpenAI リアルタイムブリッジは、voice.realtime.minBargeInAudioEndMs 未満の再生切り詰めをエコー／ノイズの可能性が高いものとして無視し、Discord の再生をクリアせず、スキップとしてログに記録します。
• voice.captureSilenceGraceMs は、Discord が話者の発話終了を報告してから、OpenClaw がその音声セグメントを STT 用に確定するまでの待機時間を制御します。デフォルト: 2000。Discord が通常の間を細切れの部分文字起こしに分割する場合は、値を大きくしてください。
• ElevenLabs が選択された TTS プロバイダーの場合、Discord の音声再生ではストリーミング TTS が使用され、プロバイダーの応答ストリームから再生が開始されます。ストリーミングをサポートしないプロバイダーは、合成された一時ファイルを使用するパスにフォールバックします。
• OpenClaw は受信時の復号失敗を監視し、短時間に失敗が繰り返された場合は、音声チャンネルから退出して再参加することで自動復旧します。
• 更新後に受信ログで DecryptionFailed(UnencryptedWhenPassthroughDisabled) が繰り返し表示される場合は、依存関係レポートとログを収集してください。同梱の @discordjs/voice 系列には、discord.js issue #11419 を解決した discord.js PR #11449 のアップストリームのパディング修正が含まれています。
• The operation was aborted 受信イベントは、OpenClaw が取得した話者セグメントを確定するときに想定されるものです。これは詳細診断であり、警告ではありません。
• Discord の詳細音声ログには、受け付けた各話者セグメントについて、長さが制限された 1 行の STT 文字起こしプレビューが含まれます。そのため、無制限の文字起こしテキストを出力することなく、デバッグ時にユーザー側とエージェントの応答側の両方を確認できます。
• agent-proxy モードでは、強制相談のフォールバックは、... で終わるテキストや、末尾の「and」のような接続語など、未完了である可能性が高い文字起こし断片、および「be right back」や「bye」のような明らかに操作を必要としない締めくくりをスキップします。これにより古いキュー内の回答が防止された場合、ログには forced agent consult skipped reason=... が表示されます。

​

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

{
  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 に設定します。
• followUsers は、音声への在室のみを制御します。発言者アクセス権や所有者権限は付与しません。commands.ownerAllowFrom と、ギルドまたはチャンネルのユーザーおよびロールは個別に設定してください。
• 追従対象ユーザーが許可された音声チャンネルに参加すると、OpenClaw はそのチャンネルに参加します。ユーザーが移動すると、OpenClaw も一緒に移動します。アクティブな追従対象ユーザーが切断すると、OpenClaw は退出します。
• 複数の追従対象ユーザーが同じギルドにいて、アクティブな追従対象ユーザーが退出した場合、OpenClaw はギルドから退出する前に、追跡中の別の追従対象ユーザーのチャンネルへ移動します。複数の追従対象ユーザーが同時に移動した場合は、最後に観測された音声状態イベントが優先されます。
• allowedChannels は引き続き適用されます。許可されていないチャンネルにいる追従対象ユーザーは無視され、追従所有のセッションは別の追従対象ユーザーへ移動するか退出します。
• OpenClaw は、起動時および上限付きの間隔で、取りこぼした音声状態イベントを照合します。照合では設定済みのギルドを抽出し、1 回の実行あたりの REST ルックアップ数に上限を設けるため、非常に大きな followUsers リストは収束までに複数回の間隔を要する場合があります。
• ユーザーの追従中に Discord または管理者がボットを移動した場合、OpenClaw は音声セッションを再構築し、移動先が許可されていれば追従所有を維持します。ボットが allowedChannels の外へ移動された場合、OpenClaw は退出し、設定済みの対象が存在すればそこへ再参加します。
• DAVE の受信復旧では、復号に繰り返し失敗した後、同じチャンネルから退出して再参加する場合があります。追従所有のセッションは、その復旧経路でも追従所有を維持するため、その後に追従対象ユーザーが切断した場合もチャンネルから退出します。

• 自分が音声に参加しているときにボットも自動的に参加する必要がある、個人用またはオペレーター用のセットアップでは、followUsers を使用します。
• 追跡対象ユーザーが音声に参加していないときでも常駐する必要がある、固定ルーム用ボットでは、autoJoin を使用します。
• 単発の参加や、音声への自動参加が予想外となるルームでは、/vc join を使用します。

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

• Discord の PCM キャプチャは、一時 WAV ファイルに変換されます。
• tools.media.audio が STT を処理します。たとえば openai/gpt-4o-mini-transcribe です。
• 文字起こしは Discord の受信処理とルーティングを通じて送信されます。その間、応答 LLM は、エージェントの tts ツールを非表示にし、テキストを返すよう求める音声出力ポリシーで実行されます。これは、最終的な TTS 再生を Discord 音声が所有するためです。
• voice.model が設定されている場合、この音声チャンネルのターンについてのみ応答 LLM を上書きします。
• voice.tts は 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",
        },
      },
    },
  },
}

{
  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",
        },
      },
    },
  },
}

{
  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",
        },
      },
    },
  },
}

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

{
  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 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 に中断対象のアクティブな再生がなかったことを意味します。これによって音声が打ち切られることはありません。

​

ボイスメッセージ

• ローカルファイルパスを指定してください（URL は拒否されます）。
• テキストコンテンツは省略してください（Discord は同じペイロード内のテキストとボイスメッセージを拒否します）。
• 任意の音声形式を使用できます。OpenClaw は必要に応じて OGG/Opus に変換します。

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

​

トラブルシューティング

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

{
  channels: {
    defaults: {
      botLoopProtection: {
        maxEventsPerWindow: 20,
        windowSeconds: 60,
        cooldownSeconds: 60,
      },
    },
    discord: {
      // 任意の Discord 全体の上書き。アカウントブロックは個々の
      // フィールドを上書きし、省略されたフィールドをここから継承します。
      botLoopProtection: {
        maxEventsPerWindow: 4,
      },
      accounts: {
        alpha: {
          // Alpha は、他のボットが自身をメンションした場合にのみ、そのメッセージを受信します。
          allowBots: "mentions",
        },
        bravo: {
          // Bravo は、ボットが作成したすべての Discord メッセージを受信します。
          allowBots: true,
          mentionAliases: {
            // 設定されたユーザー ID を使用して、Bravo が Alpha の Discord メンションを記述できるようにします。
            Alpha: "ALPHA_DISCORD_USER_ID",
          },
          botLoopProtection: {
            // ペアを抑制する前に、1 分あたり最大 5 件のメッセージを許可します。
            maxEventsPerWindow: 5,
            windowSeconds: 60,
            cooldownSeconds: 90,
          },
        },
      },
    },
  },
}

​

設定リファレンス

​

Discord Activities

• activities.clientSecret：Discord アプリケーションの OAuth2 クライアントシークレット。DISCORD_CLIENT_SECRET にフォールバックします
• activities.applicationId：任意の Activity アプリケーション ID。デフォルトでは Gateway 起動時に取得したボットアプリケーション ID を使用します

​

安全性と運用

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

​

関連項目