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 元件 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.models。

檔案附件：

• 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 驗證，並回覆「未授權」。
• 預設斜線命令設定：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: "權杖已耗盡",  },},},}

工具與動作閘門

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 可使 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 下選擇文字轉語音的聲音。對目前的 OpenAI TTS 模型而言，cedar 是不錯的陽剛聲線選擇。
• 各 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 的上游填補修正，該 PR 已結束 discord.js issue #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 可保留已儲存的清單，但停止自動語音跟隨。
• 當被跟隨的使用者加入允許的語音頻道時，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 會套用語音輸出原則來執行；由於 Discord 語音負責最終的 TTS 播放，因此該原則會隱藏代理程式的 tts 工具，並要求回傳文字。
• 設定 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 可讓 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 驗證、messages.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: {discord: {  accounts: {    default: {      eventQueue: {        listenerTimeout: 120000,      },    },  },},},}

{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_BOT_TOKEN）。
• 授予最低權限的 Discord 權限。
• 如果命令部署／狀態已過時，請重新啟動閘道，並使用 openclaw channels status --probe 重新檢查。

相關內容