Discord

OpenClaw 透過官方 Discord 閘道以機器人身分連線至 Discord。支援私訊與伺服器頻道。

快速設定

建立含機器人的 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>

建議：設定伺服器工作區

私訊可正常運作後，你可以將伺服器轉換為完整工作區，讓每個頻道都有具備各自內容脈絡的獨立代理程式工作階段。建議用於只有你和機器人的私人伺服器。

{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，或任何適合你工作流程的頻道。

執行階段模型

• 閘道負責 Discord 連線。
• 回覆路由是確定性的：Discord 的輸入回覆至 Discord。
• Discord 伺服器／頻道中繼資料會以不受信任的內容脈絡加入模型提示，而不是作為使用者可見的回覆前綴。如果模型將該封套複製回來，OpenClaw 會從輸出回覆和未來的重播內容脈絡中移除複製的中繼資料。
• 預設情況下（session.dmScope=main），直接聊天會共用代理程式的主要工作階段（agent:main:main）。
• 伺服器頻道使用隔離的工作階段鍵（agent:<agentId>:discord:channel:<channelId>）。
• 群組私訊預設會被忽略（channels.discord.dm.groupEnabled=false）。
• 原生斜線命令會在隔離的命令工作階段中執行（agent:<agentId>:discord:slash:<userId>），同時仍會將 CommandTargetSessionKey 帶入路由後的對話工作階段。
• 傳送至 Discord 的純文字排程／心跳偵測公告會合併為最終可供助理查看的答案，並只傳送一次。當代理程式產生多個可傳送的承載資料時，媒體與結構化元件承載資料仍會保留為多則訊息。

論壇頻道

Discord 論壇與媒體頻道僅接受討論串貼文。OpenClaw 支援兩種建立方式：

• 傳送訊息至論壇上層頻道（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 "貼文內容"

論壇上層頻道不接受 Discord 元件。若需要元件，請傳送至討論串本身（channel:<threadId>）。

互動式元件

OpenClaw 支援在代理程式訊息中使用 Discord components v2 容器。請搭配 components 承載資料使用訊息工具。互動結果會以一般傳入訊息的形式路由回代理程式，並遵循現有的 Discord replyToMode 設定。

支援的區塊：

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

元件預設只能使用一次。設定 components.reusable=true，可讓按鈕、選取項目與表單在到期前重複使用。

若要限制誰能點擊按鈕，請在該按鈕上設定 allowedUsers（Discord 使用者 ID、標籤或 *）。不符合的使用者會收到僅自己可見的拒絕訊息。

元件回呼預設會在 30 分鐘後到期。設定 channels.discord.agentComponents.ttlMs 可變更預設帳號的回呼登錄存續時間，或為個別帳號設定 channels.discord.accounts.<accountId>.agentComponents.ttlMs。此值以毫秒為單位，必須是正整數，且上限為 86400000（24 小時）。較長的 TTL 適合需要讓按鈕持續可用的審查／核准工作流程，但也會延長舊 Discord 訊息仍可觸發動作的時間範圍。請優先使用符合需求的最短 TTL；若過期回呼可能造成意外，請保留預設值。

/model 與 /models 斜線命令會開啟互動式模型選擇器，其中包含供應商、模型及相容執行環境的下拉式選單，並附有提交步驟。/models add 已淘汰，會傳回淘汰訊息，而不再從聊天中登錄模型。選擇器回覆僅自己可見，且只有叫用它的使用者能操作。Discord 選取選單最多只能包含 25 個選項，因此若希望選擇器只為 openai 或 vllm 等指定供應商顯示動態探索到的模型，請將 provider/* 項目新增至 agents.defaults.modelPolicy.allow。

檔案附件：

• 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: "選用的備用文字",  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[].match.roles，依身分組 ID 將 Discord 伺服器成員路由至不同的代理程式。以身分組為基礎的繫結僅接受身分組 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 使用者介面中看到命令；執行時會強制套用 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: "權杖已耗盡",  },},},}

工具和動作閘門

Discord 訊息動作涵蓋訊息傳送、頻道管理、內容管理、在線狀態和中繼資料。

核心範例：

• 訊息傳送：sendMessage、readMessages、editMessage、deleteMessage、threadReply
• 回應：react、reactions、emojiList
• 內容管理：timeout、kick、ban
• 在線狀態：setPresence

event-create 動作接受選用的 image 參數（URL 或本機檔案路徑），用於設定排定事件的封面圖片。

動作閘門位於 channels.discord.actions.* 之下。

預設閘門行為：

Components v2 使用者介面

OpenClaw 使用 Discord components v2 進行執行核准與跨情境標記。Discord 訊息動作也可接受 components 以建立自訂使用者介面（進階功能；需要透過 discord 工具建構元件承載資料），而舊版 embeds 仍可使用，但不建議使用。

• channels.discord.ui.components.accentColor 設定 Discord 元件容器使用的強調色（十六進位）。各帳號設定：channels.discord.accounts.<id>.ui.components.accentColor。
• channels.discord.agentComponents.ttlMs 控制已傳送的 Discord 元件回呼維持註冊的時間（預設 1800000，最長 86400000）。各帳號設定：channels.discord.accounts.<id>.agentComponents.ttlMs。
• 當 components v2 存在時，會忽略 embeds。
• 預設會抑制純 URL 預覽。當訊息動作中的單一外連連結應展開時，請設定 suppressEmbeds: false。

範例：

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

語音

Discord 有兩種不同的語音介面：即時的語音頻道（持續對話）與語音訊息附件（波形預覽格式）。閘道同時支援兩者。

語音頻道

設定檢查清單：

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 閘道意圖。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 用於設定即時音訊工作階段。若要搭配使用 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 可一律要求喚醒名稱，設定 false 則永不要求。設定的喚醒名稱必須由一或兩個單字組成。如果未設定 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 下選擇文字轉語音的聲音。在目前的 OpenAI TTS 模型中，cedar 是聽起來較陽剛的良好選擇。
• 每個頻道的 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 使用內建的 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 的上游填補修正，該 PR 已關閉 discord.js 議題 #11419。
• 當 OpenClaw 將擷取的發言者片段定稿時，出現 The operation was aborted 接收事件是預期行為；這些是詳細診斷資訊，不是警告。
• 詳細的 Discord 語音記錄會針對每個已接受的發言者片段，加入長度受限的單行 STT 轉錄預覽，讓偵錯時能同時顯示使用者端及代理回覆端，而不會傾印長度不受限的轉錄文字。
• 在 agent-proxy 模式下，強制諮詢備援會略過可能不完整的轉錄片段，例如以 ... 結尾的文字或尾端為 "and" 之類的連接詞，以及 "be right back" 或 "bye" 等明顯無須採取動作的結語。當此機制避免使用過時的排隊答案時，記錄會顯示 forced agent consult skipped reason=...。

在語音頻道中跟隨使用者

如果希望 Discord 語音機器人跟隨一或多名已知的 Discord 使用者，而不是在啟動時加入固定頻道或等待 /vc join，請使用 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，可保留已儲存的清單，但停止自動跟隨語音。
• followUsers 僅控制語音駐留。它不會授予發言者存取權或擁有者權限；請分別設定 commands.ownerAllowFrom，以及伺服器或頻道的使用者與角色。
• 當被跟隨的使用者加入允許的語音頻道時，OpenClaw 會加入該頻道。使用者移動時，OpenClaw 會隨之移動。作用中的被跟隨使用者中斷連線時，OpenClaw 會離開。
• 如果同一伺服器中有多位被跟隨的使用者，且作用中的被跟隨使用者離開，OpenClaw 會先移至另一位受追蹤之被跟隨使用者所在的頻道，再離開伺服器。如果多位被跟隨的使用者同時移動，以最後觀察到的語音狀態事件為準。
• allowedChannels 仍然適用。位於不允許頻道中的被跟隨使用者會被忽略，而由跟隨功能擁有的工作階段會移至另一位被跟隨的使用者，或直接離開。
• OpenClaw 會在啟動時及有界的時間間隔內，協調遺漏的語音狀態事件。協調作業會取樣已設定的伺服器，並限制每次執行的 REST 查詢次數，因此非常大的 followUsers 清單可能需要超過一個間隔才能收斂。
• 如果 Discord 或管理員在機器人跟隨使用者時移動機器人，當目的地受到允許時，OpenClaw 會重建語音工作階段並保留跟隨擁有權。如果機器人被移至 allowedChannels 之外，OpenClaw 會離開，並在有設定目標時重新加入該目標。
• DAVE 接收復原可能會在重複解密失敗後離開並重新加入同一頻道。由跟隨功能擁有的工作階段會在此復原路徑中保留其跟隨擁有權，因此被跟隨的使用者稍後中斷連線時，仍會離開該頻道。

選擇加入模式：

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

Discord 語音轉碼器：

• 語音接收記錄會顯示 discord voice: opus decoder: libopus-wasm。
• 即時播放會使用同一個隨附的 libopus-wasm 套件，將原始 48 kHz 立體聲 PCM 編碼為 Opus，再將封包交給 @discordjs/voice。
• 檔案和供應商串流播放會使用 ffmpeg 轉碼為原始 48 kHz 立體聲 PCM，接著使用 libopus-wasm 產生傳送至 Discord 的 Opus 封包串流。

STT 加 TTS 流水線：

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

沒有 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 讓 Discord 發言者開始事件和已處於作用中的發言者音訊，可在下一個擷取回合抵達 OpenAI 前取消作用中的即時回應。當 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 語音或從中接收的 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 語音事件、噪音閘門行為，或用戶端短暫啟用麥克風。
• 若 audio playback stopped reason=stream-close 附近沒有插話或 provider-clear-audio，表示本機 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 驗證、tts/voice.tts 的 TTS 驗證，以及 voice.realtime.providers 或提供者一般驗證設定的即時提供者驗證。

語音訊息

Discord 語音訊息會顯示波形預覽，且需要 OGG/Opus 音訊。OpenClaw 會自動產生波形，但需要閘道主機上的 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: {defaults: {  botLoopProtection: {    maxEventsPerWindow: 20,    windowSeconds: 60,    cooldownSeconds: 60,  },},discord: {  // 選用的 Discord 全域覆寫。帳號區塊會覆寫個別  // 欄位，並從此處繼承省略的欄位。  botLoopProtection: {    maxEventsPerWindow: 4,  },  accounts: {    alpha: {      // Alpha 僅在其他機器人提及它時才會接收其訊息。      allowBots: "mentions",    },    bravo: {      // Bravo 會接收所有由機器人撰寫的 Discord 訊息。      allowBots: true,      mentionAliases: {        // 讓 Bravo 使用設定的使用者 ID 寫入對 Alpha 的 Discord 提及。        Alpha: "ALPHA_DISCORD_USER_ID",      },      botLoopProtection: {        // 在抑制該配對前，每分鐘最多允許五則訊息。        maxEventsPerWindow: 5,        windowSeconds: 60,        cooldownSeconds: 90,      },    },  },},},}

設定參考

主要參考：設定參考 - Discord。

Discord Activities

設定 channels.discord.activities，讓代理程式可發布在 Discord 內開啟的獨立 HTML 小工具。此區塊為選用；若省略，OpenClaw 不會註冊任何 Activity 路由、工具或互動處理常式。如需 Developer Portal、通道、安全性與疑難排解設定，請參閱 Discord Activities。

• activities.clientSecret：Discord 應用程式的 OAuth2 用戶端密鑰；回退至 DISCORD_CLIENT_SECRET
• activities.applicationId：選用的 Activity 應用程式 ID；預設為閘道啟動時取得的機器人應用程式 ID

安全性與操作

• 將機器人權杖視為機密資訊（在受監督的環境中建議使用 DISCORD_BOT_TOKEN）。
• 授予最低權限的 Discord 權限。
• 若命令部署／狀態已過時，請重新啟動閘道，並使用 openclaw channels status --probe 重新檢查。

相關內容