Discord

Discord (Bot API)

狀態：已準備好透過官方 Discord 閘道處理私訊和公會頻道。

配對

Discord 私訊預設為配對模式。

斜線指令

原生指令行為和指令目錄。

頻道疑難排解

跨頻道診斷和修復流程。

快速設定

您需要建立一個包含機器人的新應用程式，將機器人新增至您的伺服器，並將其與 OpenClaw 配對。我們建議將您的機器人新增至您專屬的私人伺服器。如果您還沒有私人伺服器，請先建立一個（選擇 Create My Own > For me and my friends）。

建立 Discord 應用程式和機器人
前往 Discord 開發者入口網站並點擊 New Application。將其命名為類似 “OpenClaw” 的名稱。

點擊側邊欄的 Bot。將 Username 設定為您稱呼 OpenClaw agent 的名稱。
啟用特權意圖
仍在 Bot 頁面上，向下捲動至 Privileged Gateway Intents 並啟用：
- Message Content Intent（必需）
- Server Members Intent（建議；角色允許清單和名稱到 ID 匹配所需）
- Presence Intent（可選；僅在需要狀態更新時需要）
複製您的機器人 Token
在 Bot 頁面上向上捲動並點擊 Reset Token。
Note
顧名思義，這會產生您的第一個 token —— 並沒有東西被「重置」。
複製該 token 並將其保存在某處。這是您的 Bot Token，您稍後會用到它。
Generate an invite URL and add the bot to your server
點擊側邊欄上的 OAuth2。您將生成一個包含適當權限的邀請 URL，以將機器人添加到您的伺服器。

向下捲動至 OAuth2 URL Generator 並啟用：
- bot
- applications.commands
下方會出現 Bot Permissions 區塊。啟用：
- 檢視頻道
- 傳送訊息
- 讀取訊息紀錄
- 嵌入連結
- 附加檔案
- 新增反應 (可選)
複製底部生成的 URL，將其貼到您的瀏覽器中，選擇您的伺服器，然後點擊 Continue (繼續) 進行連線。您現在應該可以在 Discord 伺服器中看到您的機器人了。
啟用開發者模式並收集您的 ID
回到 Discord 應用程式，您需要啟用開發者模式才能複製內部 ID。
1. 點擊 User Settings（頭像旁的齒輪圖示）→ Advanced → 開啟 Developer Mode
2. 在側邊欄對您的 伺服器圖示 按一下滑鼠右鍵 → Copy Server ID
3. 對 您自己的大頭貼 按一下滑鼠右鍵 → Copy User ID
將您的 Server ID 和 User ID 與您的 Bot Token 一起儲存 — 您將在下一步把這三者都發送給 OpenClaw。
Allow DMs from server members
若要進行配對，Discord 需要允許您的機器人向您傳送私人訊息。在 伺服器圖示 上按一下滑鼠右鍵 → 隱私權設定 → 開啟 私人訊息。

這可讓伺服器成員（包括機器人）傳送私人訊息給您。如果您想透過 OpenClaw 使用 Discord 私人訊息，請保持此設定啟用。如果您只打算使用公會頻道，則可以在配對完成後停用私人訊息。

安全設定您的機器人權杖（請勿在聊天中傳送）

您的 Discord 機器人權杖是個機密（就像密碼一樣）。請在傳送訊息給您的 agent 之前，在執行 OpenClaw 的機器上設定它。

export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN
openclaw config set channels.discord.enabled true --strict-json
openclaw gateway

如果 OpenClaw 已經作為背景服務執行，請透過 OpenClaw Mac 應用程式重新啟動，或是停止並重新啟動 `openclaw gateway run` 程序。

設定 OpenClaw 並配對

在任何現有頻道（例如 Telegram）上與您的 OpenClaw agent 聊天並告知它。如果 Discord 是您的第一個頻道，請改用 CLI / config 分頁。

“I already set my Discord bot token in config. Please finish Discord setup with User ID `

and Server ID

`.”

    如果您偏好使用檔案設定，請設定：

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

    預設帳戶的環境變數後備：

DISCORD_BOT_TOKEN=...

    支援純文字 `token` 值。對於跨 env/file/exec providers 的 `channels.discord.token`，也支援 SecretRef 值。請參閱 [機密管理](/en/gateway/secrets)。

Approve first DM pairing
等待閘道運行，然後在 Discord 中私訊您的機器人。它將回應一個配對代碼。
將配對代碼傳送給您現有頻道上的代理：

“Approve this Discord pairing code: `

`”
配對代碼將在 1 小時後過期。您現在應該可以透過 DM 在 Discord 上與您的代理聊天。

建議：設定伺服器工作區

一旦私訊（DM）運作正常，您可以將您的 Discord 伺服器設定為完整的工作區，讓每個頻道都擁有自己的代理程式工作階段與上下文。這建議用於僅包含您與您的機器人的私人伺服器。

將您的伺服器新增至伺服器允許清單

這可讓您的代理程式在您伺服器上的任何頻道中回應，而不僅限於私訊。

「將我的 Discord 伺服器 ID `

` 新增至伺服器允許清單」

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

允許無需 @提及即可回應
根據預設，您的 Agent 僅在頻道中被 @提及時才會回應。對於私人伺服器，您可能會希望它回應每則訊息。
「允許我的 Agent 在此伺服器上回應而無需被 @提及」
在您的伺服器設定中設定 `requireMention: false`：
{ channels: { discord: { guilds: { YOUR_SERVER_ID: { requireMention: false, }, }, }, }, }
Plan for memory in guild channels
預設情況下，長期記憶（MEMORY.md）僅在 DM 會話中載入。公會頻道不會自動載入 MEMORY.md。

“當我在 Discord 頻道中提問時，如果你需要來自 MEMORY.md 的長期背景，請使用 memory_search 或 memory_get。”

現在在您的 Discord 伺服器上建立一些頻道並開始聊天。您的代理可以看到頻道名稱，且每個頻道都有自己的獨立會話 — 因此您可以設定 #coding、#home、#research 或任何符合您工作流程的內容。

執行時模型

Gateway 擁有 Discord 連線。
回覆路由是確定性的：Discord 的 inbound 回覆會回傳給 Discord。
預設情況下 (session.dmScope=main)，直接聊天共用代理主會話 (agent:main:main)。
公會頻道是獨立的會話金鑰 (agent:<agentId>:discord:channel:<channelId>)。
群組直接訊息預設會被忽略 (channels.discord.dm.groupEnabled=false)。
原生斜線指令在獨立的指令會話中執行 (agent:<agentId>:discord:slash:<userId>)，同時仍將 CommandTargetSessionKey 攜帶至路由的對話會話。

論壇頻道

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

傳送訊息至論壇父頻道 (channel:<forumId>) 以自動建立主題串。主題串標題使用您訊息中的第一行非空白內容。
使用 openclaw message thread create 直接建立主題串。針對論壇頻道，請勿傳遞 --message-id。

範例：傳送到論壇父頻道以建立討論串

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

範例：明確建立論壇討論串

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

論壇父頻道不接受 Discord 元件。如果您需要使用元件，請傳送至主題串本身 (channel:<threadId>)。

互動元件

OpenClaw 支援針對代理程式訊息使用 Discord 元件 v2 容器。請使用帶有 components 載荷的訊息工具。互動結果會以一般傳入訊息的形式路由回代理程式，並遵循現有的 Discord replyToMode 設定。

支援的區塊：

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

預設情況下，元件只能使用一次。設定 components.reusable=true 以允許按鈕、選取器和表單多次使用，直到過期為止。

若要限制誰可以點擊按鈕，請在該按鈕上設定 allowedUsers（Discord 使用者 ID、標記或 *）。設定後，不符合的使用者會收到一則暫時性的拒絕訊息。

/model 和 /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: "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" },
          ],
        },
      ],
    },
  },
}

存取控制與路由

channels.discord.dmPolicy 控制存取權限（舊版：channels.discord.dm.policy）：

pairing（預設）
allowlist
open（要求 channels.discord.allowFrom 包含 "*"；舊版：channels.discord.dm.allowFrom）
disabled

如果 DM 政策未設定為開放，未知使用者將會被封鎖（或在 pairing 模式下被提示進行配對）。

多帳號優先順序：

channels.discord.accounts.default.allowFrom 僅套用於 default 帳號。
具名帳號會在自身 allowFrom 未設定時繼承 channels.discord.allowFrom。
具名帳號不會繼承 channels.discord.accounts.default.allowFrom。

傳送時的 DM 目標格式：

`user:

-<@id>` 提及

除非提供明確的使用者/頻道目標類型，否則純數字 ID 具有歧義且會被拒絕。

伺服器處理由 `channels.discord.groupPolicy` 控制：

- `open`
- `allowlist`
- `disabled`

當存在 `channels.discord` 時，安全的基線是 `allowlist`。

`allowlist` 行為：

- 伺服器必須符合 `channels.discord.guilds`（`id` 優先，接受 slug）
- 可選的發送者允許清單：`users`（建議使用穩定的 ID）和 `roles`（僅限角色 ID）；如果設定了其中任何一個，當發送者符合 `users` 或 `roles` 時即被允許
- 預設停用直接名稱/標籤匹配；僅將 `channels.discord.dangerouslyAllowNameMatching: true` 啟用作為緊急相容模式
- `users` 支援名稱/標籤，但 ID 更安全；當使用名稱/標籤條目時 `openclaw security audit` 會發出警告
- 如果伺服器設定了 `channels`，未列出的頻道會被拒絕
- 如果伺服器沒有 `channels` 區塊，則該已列入允許清單的伺服器中的所有頻道皆被允許

範例：

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

如果您僅設定 `DISCORD_BOT_TOKEN` 而未建立 `channels.discord` 區塊，執行時期會回退為 `groupPolicy="allowlist"`（並在日誌中發出警告），即使 `channels.defaults.groupPolicy` 是 `open`。

伺服器訊息預設受提及限制。

提及偵測包含：

明確提及機器人
設定的提及模式 (agents.list[].groupChat.mentionPatterns，後備 messages.groupChat.mentionPatterns)
在支援情況下的隱含回覆機器人行為

requireMention 是針對每個伺服器/頻道設定 (channels.discord.guilds...)。 ignoreOtherMentions 可選地捨棄提及其他使用者/角色但未提及機器人的訊息 (排除 @everyone/@here)。

群組訊息：

預設：忽略 (dm.groupEnabled=false)
透過 dm.groupChannels 的可選允許清單 (頻道 ID 或代碼)

基於角色的代理路由

使用 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",
      },
    },
  ],
}

開發者入口網站設定

Create app and bot

Discord Developer Portal -> Applications -> New Application
Bot -> Add Bot
Copy bot token

Privileged intents

在 Bot -> Privileged Gateway Intents 中，啟用：

Message Content Intent（訊息內容意圖）
Server Members Intent（伺服器成員意圖，推薦）

Presence intent（在線狀態意圖）是可選的，只有當您想要接收在線狀態更新時才需要。設置機器人的在線狀態 (setPresence) 不需要為成員啟用在線狀態更新。

OAuth scopes and baseline permissions

OAuth URL 生成器：

範圍 (scopes)：bot、applications.commands

典型的基礎權限：

View Channels（查看頻道）
Send Messages（發送訊息）
Read Message History（閱讀訊息歷史）
Embed Links（嵌入連結）
Attach Files（附加檔案）
Add Reactions（新增反應，可選）

除非明確需要，否則避免使用 Administrator。

Copy IDs

啟用 Discord 開發者模式，然後複製：

server ID
channel ID
user ID

在 OpenClaw 設定中優先使用數字 ID，以確保稽核和探測的可靠性。

原生指令和指令驗證

commands.native 預設為 "auto"，並針對 Discord 啟用。
頻道覆蓋設定：channels.discord.commands.native。
commands.native=false 會明確清除先前註冊的 Discord 原生指令。
原生指令驗證使用與一般訊息處理相同的 Discord 允許清單/原則。
對於未獲授權的使用者，指令可能仍會顯示在 Discord UI 中；但執行仍會強制執行 OpenClaw 驗證並回傳「未授權」。

請參閱 Slash 指令以了解指令目錄和行為。

預設斜線指令設定：

ephemeral: true

功能詳情

Reply tags and native replies

Discord 支援在 Agent 輸出中使用回覆標籤：

[[reply_to_current]]
`[[reply_to:

]]`

由 `channels.discord.replyToMode` 控制：

- `off` (預設)
- `first`
- `all`

注意：`off` 會停用隱式回覆串接。明確的 `[[reply_to_*]]` 標籤仍會被接受。

訊息 ID 會顯示在上下文/歷史記錄中，以便 Agent 能夠指定特定訊息。

Live stream preview

OpenClaw 可以透過發送暫時訊息並在文字抵達時進行編輯，來串流草稿回覆。

- `channels.discord.streaming` 控制預覽串流（`off` | `partial` | `block` | `progress`，預設值：`off`）。
- 預設值保持為 `off`，因為 Discord 的預覽編輯可能會很快達到速率限制，特別是在多個機器人或閘道共用同一個帳戶或伺服器流量時。
- 為了跨頻道一致性，接受 `progress`，並在 Discord 上對應到 `partial`。
- `channels.discord.streamMode` 是舊版別名，會自動遷移。
- `partial` 會在 token 抵達時編輯單一預覽訊息。
- `block` 會發出草稿大小的區塊（使用 `draftChunk` 來調整大小和中斷點）。

範例：

{
  channels: {
    discord: {
      streaming: "partial",
    },
  },
}

`block` 模式區塊分割預設值（限制為 `channels.discord.textChunkLimit`）：

{
  channels: {
    discord: {
      streaming: "block",
      draftChunk: {
        minChars: 200,
        maxChars: 800,
        breakPreference: "paragraph",
      },
    },
  },
}

預覽串流僅限文字；媒體回覆會回退到正常傳遞。

注意：預覽串流與區塊串流是分開的。當 Discord 明確啟用區塊串流時，OpenClaw 會跳過預覽串流以避免雙重串流。

History, context, and thread behavior

Guild 歷史紀錄上下文：

channels.discord.historyLimit default 20
fallback: messages.groupChat.historyLimit
0 disables

DM 歷史紀錄控制：

channels.discord.dmHistoryLimit
`channels.discord.dms[”

“].historyLimit`

執行緒行為：

- Discord 執行緒被作為頻道會話進行路由
- 父執行緒元資料可用於父會話連結
- 執行緒設定會繼承父頻道設定，除非存在特定於執行緒的條目

頻道主題會被作為 **不受信任的** 上下文注入（而非系統提示詞）。

Thread-bound sessions for subagents

Discord 可以將執行緒繫結至會話目標，以便該執行緒中的後續訊息持續路由至同一會話（包括子代理會話）。

指令：

`/focus

將目前/新執行緒繫結至子代理/會話目標 -/unfocus移除目前的執行緒繫結 -/agents顯示活躍執行與繫結狀態 -/session idle

檢查/更新聚焦繫結的非活動自動取消聚焦 -/session max-age

` 檢查/更新聚焦繫結的強制最大存留時間

設定：

{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false, // opt-in
      },
    },
  },
}

備註：

- `session.threadBindings.*` 設定全域預設值。
- `channels.discord.threadBindings.*` 覆寫 Discord 行為。
- `spawnSubagentSessions` 必須為 true，才能為 `sessions_spawn({ thread: true })` 自動建立/繫結執行緒。
- `spawnAcpSessions` 必須為 true，才能為 ACP（`/acp spawn ... --thread ...` 或 `sessions_spawn({ runtime: "acp", thread: true })`）自動建立/繫結執行緒。
- 如果帳戶停用了執行緒繫結，則 `/focus` 及相關的執行緒繫結操作將無法使用。

請參閱 [子代理](/en/tools/subagents)、[ACP 代理](/en/tools/acp-agents) 和 [設定參考](/en/gateway/configuration-reference)。

Persistent ACP channel bindings

對於穩定的「始終在線」ACP 工作區，請設定針對 Discord 對話的頂層類型化 ACP 繫結。

設定路徑：

- `bindings[]` with `type: "acp"` and `match.channel: "discord"`

範例：

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

備註：

- `/acp spawn codex --bind here` 會將目前的 Discord 頻道或執行緒就地繫結，並確保未來的訊息都路由至同一個 ACP 會話。
- 這仍然可能意味著「啟動一個全新的 Codex ACP 會話」，但它本身不會建立新的 Discord 執行緒。現有的頻道將保持為對話介面。
- Codex 仍可能在其自己的 `cwd` 或磁碟上的後端工作區中執行。該工作區是執行時狀態，而非 Discord 執行緒。
- 執行緒訊息可以繼承上層頻道的 ACP 繫結。
- 在已繫結的頻道或執行緒中，`/new` 和 `/reset` 會就地重設同一個 ACP 會話。
- 臨時執行緒繫結仍然有效，並且在啟用時可以覆寫目標解析。
- 只有當 OpenClaw 需要透過 `--thread auto|here` 建立/繫結子執行緒時，才需要 `spawnAcpSessions`。對於目前頻道中的 `/acp spawn ... --bind here` 則不需要。

參閱 [ACP Agents](/en/tools/acp-agents) 以了解繫結行為的詳細資訊。

Reaction notifications

每個伺服器的反應通知模式：

off
own (預設)
all
allowlist (使用 `guilds.

.users`)

反應事件會轉換為系統事件，並附加到已路由的 Discord 工作階段。

Ack reactions

當 OpenClaw 正在處理傳入訊息時，ackReaction 會發送一個確認回應的 emoji。

解析順序：

`channels.discord.accounts.

.ackReaction -channels.discord.ackReaction -messages.ackReaction - agent identity emoji 後備機制 (agents.list[].identity.emoji`，否則為 ”👀”)

備註：

- Discord 接受 Unicode emoji 或自訂 emoji 名稱。
- 使用 `""` 來停用特定頻道或帳號的回應。

Config writes

頻道發起的設定寫入預設為啟用。

這會影響 `/config set|unset` 流程（當指令功能啟用時）。

停用方式：

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

Gateway proxy

透過 HTTP(S) 代理伺服器使用 `channels.discord.proxy` 路由 Discord 閘道 WebSocket 流量以及啟動時期的 REST 查詢（應用程式 ID + 白名單解析）。

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

每個帳戶的覆寫設定：

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

PluralKit 支援

啟用 PluralKit 解析以將代理訊息對應到系統成員身分：

{
  channels: {
    discord: {
      pluralkit: {
        enabled: true,
        token: "pk_live_...", // optional; needed for private systems
      },
    },
  },
}

備註：

- allowlists 可以使用 `pk:

- 僅當channels.discord.dangerouslyAllowNameMatching: true時，才會透過名稱/slug 比對成員顯示名稱 - 查詢使用原始訊息 ID，並受限於時間視窗 - 如果查詢失敗，代理訊息將被視為機器人訊息並丟棄，除非allowBots=true`

Presence configuration

當您設定狀態或活動欄位，或啟用自動 Presence 時，會套用 Presence 更新。

僅設定狀態的範例：

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

活動範例（自訂狀態為預設的活動類型）：

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

直播範例：

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

活動類型對應表：

- 0: Playing (正在遊玩)
- 1: Streaming (正在直播，需要 `activityUrl`)
- 2: Listening (正在聆聽)
- 3: Watching (正在觀看)
- 4: Custom (自訂，將活動文字作為狀態內容；表情符號為選填)
- 5: Competing (正在競爭)

自動 Presence 範例（執行期健康訊號）：

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

自動 Presence 會將執行期可用性對應至 Discord 狀態：healthy => online (線上)，degraded 或 unknown => idle (閒置)，exhausted 或 unavailable => dnd (請勿打擾)。選用的文字覆寫：

- `autoPresence.healthyText`
- `autoPresence.degradedText`
- `autoPresence.exhaustedText` (支援 `{reason}` 預留位置)

在 Discord 中進行執行核准

Discord 支援在直接訊息 (DM) 中進行按鈕式的執行核准，並可選擇在原始頻道中發布核准提示。

設定路徑：

channels.discord.execApprovals.enabled
channels.discord.execApprovals.approvers (選用；當可行時，會回退為從 allowFrom 推斷的擁有者 ID 和明確的 DM defaultTo)
channels.discord.execApprovals.target (dm | channel | both，預設：dm)
agentFilter、sessionFilter、cleanupAfterResolve

當 enabled: true 且可解析至少一名核准者時（無論是從 execApprovals.approvers 還是從帳戶現有的擁有者設定 (allowFrom、舊版 dm.allowFrom 或明確的 DM defaultTo)），Discord 會成為核准用戶端。

當 target 為 channel 或 both 時，核准提示在頻道中可見。只有已解析的核准者可以使用按鈕；其他使用者會收到暫時性的拒絕訊息。核准提示包含指令文字，因此請僅在受信任的頻道中啟用頻道傳遞。如果無法從工作階段金鑰衍生頻道 ID，OpenClaw 會回退為 DM 傳遞。

Discord 也會轉譯其他聊天頻道使用的共用核准按鈕。原生的 Discord 配接器主要新增核准者 DM 路由和頻道分發功能。

此處理程序的 Gateway 驗證使用與其他 Gateway 用戶端相同的共用憑證解析合約：

env-first 本地驗證 (OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD 然後 gateway.auth.*)
在本地模式中，只有在未設定 gateway.auth.* 時，才可以將 gateway.remote.* 作為回退；已設定但未解析的本地 SecretRef 會以封閉模式失敗
適用時透過 gateway.remote.* 支援遠端模式
URL 覆寫是覆寫安全的：CLI 覆寫不會重複使用隱含憑證，而 env 覆寫僅使用 env 憑證

執行核准預設在 30 分鐘後過期。如果核准因未知的核准 ID 而失敗，請驗證核准者解析和功能啟用狀態。

相關文件：執行核准

工具和動作閘門

Discord 訊息動作包括傳訊、頻道管理、審核、狀態和元數據動作。

核心範例：

訊息傳遞：sendMessage, readMessages, editMessage, deleteMessage, threadReply
反應：react, reactions, emojiList
管理：timeout, kick, ban
狀態：setPresence

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

預設閘門行為：

動作群組	預設
reactions、messages、threads、pins、polls、search、memberInfo、roleInfo、channelInfo、channels、voiceStatus、events、stickers、emojiUploads、stickerUploads、permissions	已啟用
roles	已停用
moderation	已停用
presence	已停用

Components v2 UI

OpenClaw 使用 Discord 組件 v2 進行執行批准和跨上下文標記。Discord 訊息動作也可以接受 components 以實現自訂 UI（進階；需要透過 discord 工具建構組件負載），而舊版的 embeds 仍然可用但不建議使用。

channels.discord.ui.components.accentColor 設定 Discord 組件容器使用的強調顏色（十六進位）。
使用 channels.discord.accounts.<id>.ui.components.accentColor 為每個帳戶設定。
當存在組件 v2 時，會忽略 embeds。

範例：

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

語音頻道

OpenClaw 可以加入 Discord 語音頻道進行即時、連續的對話。這與語音訊息附件是分開的。

需求：

啟用原生指令 (commands.native 或 channels.discord.commands.native)。
設定 channels.discord.voice。
機器人在目標語音頻道中需要 Connect + Speak 權限。

使用 Discord 專用的原生指令 /vc join|leave|status 來控制會話。該指令使用帳戶預設代理程式，並遵循與其他 Discord 指令相同的允許清單和群組原則規則。

自動加入範例：

{
  channels: {
    discord: {
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        tts: {
          provider: "openai",
          openai: { voice: "alloy" },
        },
      },
    },
  },
}

備註：

voice.tts 會覆寫 messages.tts 僅用於語音播放。
語音文字記錄回合源自 Discord allowFrom（或 dm.allowFrom）衍生擁有者狀態；非擁有者發言者無法存取僅限擁有者的工具（例如 gateway 和 cron）。
語音功能預設啟用；設定 channels.discord.voice.enabled=false 以停用它。
voice.daveEncryption 和 voice.decryptionFailureTolerance 會傳遞至 @discordjs/voice 加入選項。
如果未設定，@discordjs/voice 的預設值為 daveEncryption=true 和 decryptionFailureTolerance=24。
OpenClaw 也會監控接收解密失敗，並在短時間內多次失敗後通過離開/重新加入語音頻道來自動恢復。
如果接收日誌反覆顯示 DecryptionFailed(UnencryptedWhenPassthroughDisabled)，這可能是 discord.js #11419 中追蹤的上游 @discordjs/voice 接收錯誤。

語音訊息

Discord 語音訊息會顯示波形預覽，並且需要 OGG/Opus 音訊加上元資料。OpenClaw 會自動產生波形，但它在閘道主機上需要 ffmpeg 和 ffprobe 才能檢查和轉換音訊檔案。

需求與限制：

提供 本機檔案路徑（不接受 URL）。
省略文字內容（Discord 不允許在同一個 payload 中同時包含文字和語音訊息）。
接受任何音訊格式；OpenClaw 會在需要時轉換為 OGG/Opus。

範例：

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

疑難排解

Used disallowed intents or bot sees no guild messages

啟用訊息內容意圖
當您依賴使用者/成員解析時，啟用伺服器成員意圖
變更意圖後重新啟動閘道

伺服器訊息意外被阻擋

- 驗證 `groupPolicy`
- 驗證 `channels.discord.guilds` 下的伺服器允許清單
- 如果伺服器 `channels` 對應存在，則只允許列出的頻道
- 驗證 `requireMention` 行為和提及模式

有用的檢查方式：

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

要求提及設為 false 但仍被阻擋

常見原因：

groupPolicy="allowlist" 但沒有對應的伺服器/頻道允許清單
requireMention 設定在錯誤的位置（必須在 channels.discord.guilds 或頻道項目下）
發送者被伺服器/頻道 users 允許清單阻擋

長時間執行的處理程序逾時或重複回覆

典型日誌：

Listener DiscordMessageListener timed out after 30000ms for event MESSAGE_CREATE
Slow listener detected ...
discord inbound worker timed out after ...

監聽器預算旋鈕：

單一帳號： channels.discord.eventQueue.listenerTimeout
多重帳號： `channels.discord.accounts.

.eventQueue.listenerTimeout`

Worker 執行逾時旋鈕：

- 單一帳號： `channels.discord.inboundWorker.runTimeoutMs`
- 多重帳號： `channels.discord.accounts.

.inboundWorker.runTimeoutMs - 預設值：1800000(30 分鐘)；設定0` 以停用

建議基準：

{
  channels: {
    discord: {
      accounts: {
        default: {
          eventQueue: {
            listenerTimeout: 120000,
          },
          inboundWorker: {
            runTimeoutMs: 1800000,
          },
        },
      },
    },
  },
}

使用 `eventQueue.listenerTimeout` 進行緩慢的監聽器設定，並且僅在您想要為佇列中的代理回合設定獨立的安全閥時才使用 `inboundWorker.runTimeoutMs`

權限稽核不符

channels status --probe 權限檢查僅適用於數值頻道 ID。

如果您使用 slug 鍵，執行階段比對仍然可以運作，但 probe 無法完全驗證權限。

DM 和配對問題

DM 已停用：channels.discord.dm.enabled=false
DM 原則已停用：channels.discord.dmPolicy="disabled" (舊版：channels.discord.dm.policy)
正在等待 pairing 模式下的配對批准

Bot 對 bot 迴圈

預設會忽略由 bot 建立的訊息。

如果您設定 channels.discord.allowBots=true，請使用嚴格的提及與允許清單規則來避免迴圈行為。建議優先使用 channels.discord.allowBots="mentions"，以僅接受提及該 bot 的 bot 訊息。

語音 STT 因 DecryptionFailed(...) 而中斷

保持 OpenClaw 為最新版本 (openclaw update)，以確保存在 Discord 語音接收恢復邏輯
確認 channels.discord.voice.daveEncryption=true (預設值)
從 channels.discord.voice.decryptionFailureTolerance=24 (上游預設值) 開始，並視需要進行調整
監控日誌中的：
- discord voice: DAVE decrypt failures detected
- discord voice: repeated decrypt failures; attempting rejoin
如果在自動重新加入後仍持續失敗，請收集日誌並與 discord.js #11419 進行比較

設定參考指標

主要參考：

設定參考 - Discord

高優先級 Discord 欄位：

啟動/驗證：enabled, token, accounts.*, allowBots
原則：groupPolicy, dm.*, guilds.*, guilds.*.channels.*
指令：commands.native, commands.useAccessGroups, configWrites, slashCommand.*
事件佇列：eventQueue.listenerTimeout (監聽器預算), eventQueue.maxQueueSize, eventQueue.maxConcurrency
inbound worker: inboundWorker.runTimeoutMs
reply/history: replyToMode, historyLimit, dmHistoryLimit, dms.*.historyLimit
delivery: textChunkLimit, chunkMode, maxLinesPerMessage
streaming: streaming (legacy alias: streamMode), draftChunk, blockStreaming, blockStreamingCoalesce
media/retry: mediaMaxMb, retry
- mediaMaxMb 限制傳出 Discord 上傳 (預設：8MB)
actions: actions.*
presence: activity, status, activityType, activityUrl
UI: ui.components.accentColor
features: threadBindings, top-level bindings[] (type: "acp"), pluralkit, execApprovals, intents, agentComponents, heartbeat, responsePrefix

安全性與操作

請將機器人令牌視為機密 (在監管環境中優先使用 DISCORD_BOT_TOKEN)。
授予最小權限的 Discord 權限。
如果指令部署/狀態過時，請重新啟動 gateway 並使用 openclaw channels status --probe 重新檢查。