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

​

Runtime 模型

• 閘道擁有 Discord 連線。
• 回覆路由是確定性的：Discord inbound 會回覆到 Discord。
• Discord 伺服器/頻道中繼資料會作為不受信任脈絡加入模型 prompt，而不是作為使用者可見的回覆前綴。如果模型把該 envelope 複製回來，OpenClaw 會從 outbound 回覆和未來 replay 脈絡中移除複製的中繼資料。
• 預設情況下（session.dmScope=main），直接聊天會共用代理程式主要工作階段（agent:main:main）。
• 伺服器頻道是隔離的工作階段 key（agent:<agentId>:discord:channel:<channelId>）。
• Group DM 預設會被忽略（channels.discord.dm.groupEnabled=false）。
• 原生斜線命令會在隔離的命令工作階段中執行（agent:<agentId>:discord:slash:<userId>），同時仍攜帶 CommandTargetSessionKey 到路由後的對話工作階段。
• 傳送到 Discord 的純文字 cron/heartbeat 公告會收斂為最終的 assistant-visible answer，並只傳送一次。當代理程式發出多個可傳遞 payload 時，媒體與結構化元件 payload 仍會是多訊息。

​

論壇頻道

• 傳送訊息到論壇父層（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"

​

互動式元件

• text、section、separator、actions、media-gallery、file
• 動作列最多允許 5 個按鈕或單一選取選單
• 選取類型：string、user、role、mentionable、channel

• file 區塊必須指向附件參照（attachment://<filename>）
• 透過 media/path/filePath 提供附件（單一檔案）；多個檔案請使用 media-gallery
• 當上傳名稱應與附件參照相符時，使用 filename 覆寫上傳名稱

• 加入 components.modal，最多可包含 5 個欄位
• 欄位類型：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 },
          },
        },
      },
    },
  },
}

​

以角色為基礎的代理路由

{
  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: "專注時間",
      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 component 容器使用的強調色（十六進位）。各帳號：channels.discord.accounts.<id>.ui.components.accentColor。
• channels.discord.agentComponents.ttlMs 控制已傳送的 Discord component callback 保持註冊的時間長度（預設 1800000，最大 86400000）。各帳號：channels.discord.accounts.<id>.agentComponents.ttlMs。
• 當 components v2 存在時，會忽略 embeds。
• 純 URL 預覽預設會被抑制。當單一傳出連結應展開時，請在訊息動作上設定 suppressEmbeds: false。

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

​

語音

​

語音頻道

1. 在 Discord Developer Portal 啟用 Message Content Intent。
2. 使用角色/使用者允許清單時，啟用 Server Members Intent。
3. 使用 bot 和 applications.commands scope 邀請機器人。
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.5",
        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",
          speakerVoice: "cedar",
        },
      },
    },
  },
}

• Discord 語音對純文字設定是選用功能；設定 channels.discord.voice.enabled=true（或保留既有的 channels.discord.voice 區塊）即可啟用 /vc 指令、語音執行階段，以及 GuildVoiceStates 閘道意圖。channels.discord.intents.voiceStates 可以明確覆寫意圖訂閱；若不設定，則會跟隨實際的語音啟用狀態。
• voice.mode 控制對話路徑。預設值是 agent-proxy：即時語音前端會處理回合時序、中斷與播放，透過 openclaw_agent_consult 將實質工作委派給路由到的 OpenClaw 代理程式，並將結果視為該說話者輸入的 Discord 文字提示。stt-tts 保留較舊的批次 STT 加 TTS 流程。bidi 讓即時模型直接對話，同時公開 openclaw_agent_consult 給 OpenClaw 大腦使用。
• voice.agentSession 控制哪個 OpenClaw 對話會接收語音回合。若不設定，會使用語音頻道自己的工作階段；也可以設定 { mode: "target", target: "channel:<text-channel-id>" }，讓語音頻道成為既有 Discord 文字頻道工作階段（例如 #maintainers）的麥克風／喇叭延伸。
• voice.model 會覆寫 Discord 語音回應與即時諮詢所使用的 OpenClaw 代理大腦。若不設定，會繼承路由到的代理模型。它與 voice.realtime.model 是分開的。
• voice.followUsers 讓機器人可與選定使用者一起加入、移動及離開 Discord 語音。請參閱在語音中跟隨使用者。
• agent-proxy 會透過 discord-voice 路由語音，這會保留說話者與目標工作階段的正常擁有者／工具授權，但會隱藏代理程式的 tts 工具，因為 Discord 語音負責播放。預設情況下，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 會設定即時音訊工作階段。若要搭配 Codex 大腦使用 OpenAI Realtime 2，請使用 voice.realtime.model: "gpt-realtime-2" 與 voice.model: "openai/gpt-5.5"。
• 即時語音模式預設會在即時提供者指令中包含小型 IDENTITY.md、USER.md 與 SOUL.md 設定檔，讓快速直接回合保有與路由到的 OpenClaw 代理程式相同的身分、使用者根據與角色設定。將 voice.realtime.bootstrapContextFiles 設為子集合可自訂此行為，或設為 [] 可停用。僅支援這些設定檔；AGENTS.md 仍會留在一般代理程式上下文中。注入的設定檔上下文不會取代 openclaw_agent_consult 在工作區工作、目前事實、記憶查詢或工具支援動作中的用途。
• 在 OpenAI agent-proxy 即時模式中，設定 voice.realtime.requireWakeName: true，即可讓 Discord 即時語音在轉錄以喚醒名稱開頭或結尾之前保持靜默。設定的喚醒名稱必須是一個或兩個詞。如果未設定 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 下選擇文字轉語音聲音。cedar 在目前的 OpenAI TTS 模型上是很適合的偏陽性聲音選項。
• 每個 Discord 頻道的 systemPrompt 覆寫會套用到該語音頻道的語音轉錄回合。
• 語音轉錄回合會從 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 使用內建的 libopus-wasm 編解碼器來接收 Discord 語音與播放即時原始 PCM。它隨附固定版本的 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 回報說話者停止後，OpenClaw 在為 STT 最終化該音訊片段前等待的時間。預設值：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 語音記錄會針對每個接受的說話者片段包含一行有界的 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 可保留已儲存清單，但停止自動語音跟隨。
• 當被跟隨的使用者加入允許的語音頻道時，OpenClaw 會加入該頻道。當使用者移動時，OpenClaw 會跟著移動。當目前被跟隨的使用者中斷連線時，OpenClaw 會離開。
• 如果同一個伺服器中有多位被跟隨的使用者，且目前被跟隨的使用者離開，OpenClaw 會先移動到另一位被追蹤跟隨使用者的頻道，再離開該伺服器。如果多位被跟隨的使用者同時移動，最新觀察到的語音狀態事件優先。
• allowedChannels 仍會套用。位於不允許頻道中的被跟隨使用者會被忽略，而跟隨擁有的工作階段會移動到另一位被跟隨使用者，或離開。
• OpenClaw 會在啟動時及以有界間隔調和遺漏的語音狀態事件。調和會取樣已設定的伺服器，並限制每次執行的 REST 查詢數，因此非常大的 followUsers 清單可能需要超過一個間隔才能收斂。
• 如果 Discord 或管理員在機器人跟隨使用者時移動它，OpenClaw 會重建語音工作階段，並在目的地允許時保留跟隨所有權。如果機器人被移到 allowedChannels 之外，OpenClaw 會離開，並在有設定目標時重新加入。
• DAVE 接收復原可能會在重複解密失敗後離開並重新加入同一個頻道。跟隨擁有的工作階段會在該復原路徑中保留跟隨所有權，因此之後被跟隨使用者中斷連線時仍會離開該頻道。

• 對於個人或操作員設定，若機器人應在你進入語音時自動出現在語音中，請使用 followUsers。
• 對於即使沒有被追蹤使用者在語音中也應存在的固定房間機器人，請使用 autoJoin。
• 對於一次性加入，或自動語音存在會令人意外的房間，請使用 /vc join。

• 語音接收記錄會顯示 discord voice: opus decoder: libopus-wasm。
• 即時播放會先使用相同的內建 libopus-wasm 套件，將原始 48 kHz 立體聲 PCM 編碼為 Opus，再將封包交給 @discordjs/voice。
• 檔案與提供者串流播放會使用 ffmpeg 轉碼為原始 48 kHz 立體聲 PCM，然後使用 libopus-wasm 產生傳送到 Discord 的 Opus 封包串流。

• Discord PCM 擷取內容會轉換成 WAV 暫存檔。
• tools.media.audio 處理 STT，例如 openai/gpt-4o-mini-transcribe。
• 轉錄文字會透過 Discord 輸入與路由傳送，而回應 LLM 會以語音輸出政策執行，該政策會隱藏代理的 tts 工具並要求回傳文字，因為 Discord 語音負責最終的 TTS 播放。
• voice.model 設定後，只會覆寫此語音頻道回合的回應 LLM。
• voice.tts 會覆蓋合併到 messages.tts；支援串流的提供者會直接送入播放器，否則會在已加入的頻道中播放產生的音訊檔案。

{
  channels: {
    discord: {
      voice: {
        enabled: true,
        model: "openai/gpt-5.5",
        followUsersEnabled: true,
        followUsers: ["123456789012345678"],
        realtime: {
          provider: "openai",
          model: "gpt-realtime-2",
          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.5",
        realtime: {
          provider: "openai",
          model: "gpt-realtime-2",
          speakerVoice: "cedar",
          toolPolicy: "safe-read-only",
          consultPolicy: "always",
        },
      },
    },
  },
}

{
  channels: {
    discord: {
      voice: {
        enabled: true,
        mode: "agent-proxy",
        model: "openai/gpt-5.5",
        agentSession: {
          mode: "target",
          target: "channel:123456789012345678",
        },
        realtime: {
          provider: "openai",
          model: "gpt-realtime-2",
          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.5",
        realtime: {
          provider: "openai",
          model: "gpt-realtime-2",
          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 語音的 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: {
    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_BOT_TOKEN）。
• 授予最低權限 Discord 權限。
• 如果 command 部署/狀態過期，請重新啟動閘道，並使用 openclaw channels status --probe 重新檢查。

​

相關