Discord（Bot API）

狀態：透過官方 Discord 閘道，支援 DM 及伺服器頻道。

• 配對 — Discord DM 預設使用配對模式。
• 斜線指令 — 原生指令行為與指令目錄。
• 頻道疑難排解 — 跨頻道診斷與修復流程。

快速設定

你需要建立一個帶有機器人的應用程式，將機器人加入你的伺服器，然後與 OpenClaw 配對。建議將機器人加入你自己的私人伺服器。如果你還沒有，先建立一個（選擇自行建立 > 給我和朋友使用）。

步驟 1：建立 Discord 應用程式和機器人

前往 [Discord 開發者入口](https://discord.com/developers/applications)，點擊**新應用程式**。命名為「OpenClaw」之類的名稱。

在側邊欄點擊 **Bot**。將**使用者名稱**設定為你的 OpenClaw 代理名稱。

步驟 2：啟用特權 Intent

仍在 **Bot** 頁面，向下捲動到 **Privileged Gateway Intents** 並啟用：

- **Message Content Intent**（必要）
- **Server Members Intent**（建議；角色允許名單和名稱轉 ID 需要此項）
- **Presence Intent**（選填；僅在需要狀態更新時使用）

步驟 3：複製機器人 Token

在 **Bot** 頁面向上捲動，點擊 **Reset Token**。

> **注意：** 雖然名稱叫「重設」，但這是在產生你的第一個 token，並沒有「重設」任何東西。

複製 token 並儲存好。這是你的 **Bot Token**，稍後會用到。

步驟 4：產生邀請 URL 並將機器人加入伺服器

在側邊欄點擊 **OAuth2**。你會產生一個含有正確權限的邀請 URL，用來將機器人加入伺服器。

向下捲動到 **OAuth2 URL Generator** 並啟用：

- `bot`
- `applications.commands`

下方會出現 **Bot Permissions** 區段。啟用：

- View Channels
- Send Messages
- Read Message History
- Embed Links
- Attach Files
- Add Reactions（選填）

複製底部產生的 URL，貼到瀏覽器中，選擇你的伺服器，然後點擊**繼續**以連接。你應該可以在 Discord 伺服器中看到你的機器人。

步驟 5：啟用開發者模式並收集 ID

回到 Discord 應用程式，你需要啟用開發者模式以便複製內部 ID。

1. 點擊**使用者設定**（頭像旁的齒輪圖示）→ **進階** → 開啟**開發者模式**
2. 右鍵點擊側邊欄的**伺服器圖示** → **複製伺服器 ID**
3. 右鍵點擊你的**頭像** → **複製使用者 ID**

將你的**伺服器 ID** 和**使用者 ID** 與 Bot Token 一起儲存好——下一步你會將三者都傳送給 OpenClaw。

步驟 6：允許伺服器成員的 DM

為了讓配對正常運作，Discord 需要允許機器人向你傳送 DM。右鍵點擊**伺服器圖示** → **隱私設定** → 開啟**直接訊息**。

這會讓伺服器成員（包括機器人）可以向你傳送 DM。如果你想透過 Discord DM 使用 OpenClaw，請保持啟用。如果你只打算使用伺服器頻道，可以在配對完成後停用 DM。

步驟 7：安全地設定機器人 Token（不要在聊天中傳送）

Discord bot token 是機密（如同密碼）。請在執行 OpenClaw 的機器上設定，而不是在聊天中傳送給代理。

openclaw config set channels.discord.token '"YOUR_BOT_TOKEN"' --json
openclaw config set channels.discord.enabled true --json
openclaw gateway

如果 OpenClaw 已經作為背景服務執行，請改用 `openclaw gateway restart`。

步驟 8：設定 OpenClaw 並配對

  #### 透過代理設定
    在任何已有的頻道（例如 Telegram）上與你的 OpenClaw 代理對話。如果 Discord 是你的第一個頻道，請改用 CLI/設定方式。

    > 「我已經在設定中設好了 Discord bot token。請用使用者 ID `<user_id>` 和伺服器 ID `<server_id>` 完成 Discord 設定。」

  #### CLI/設定
    如果你偏好基於檔案的設定：

{
  channels: {
    discord: {
      enabled: true,
      token: "YOUR_BOT_TOKEN",
    },
  },
}

    預設帳戶的環境變數備用方案：

DISCORD_BOT_TOKEN=...

    `channels.discord.token` 也支援 SecretRef 值（env/file/exec 提供者）。參閱 [密鑰管理](/docs/gateway/secrets)。

步驟 9：核准首次 DM 配對

等閘道執行後，在 Discord 中向你的機器人傳送 DM。它會回覆一個配對碼。


  #### 透過代理核准
    將配對碼傳送到你已有頻道上的代理：

    > 「核准這個 Discord 配對碼：`<CODE>`」

  #### CLI

openclaw pairing list discord
openclaw pairing approve discord <CODE>

配對碼在 1 小時後過期。

你現在應該可以透過 Discord DM 與代理對話了。

注意： Token 解析是帳戶感知的。設定中的 token 值優先於環境變數備用方案。DISCORD_BOT_TOKEN 僅用於預設帳戶。 對於進階的外送呼叫（訊息工具/頻道操作），會使用每次呼叫明確指定的 token。帳戶政策/重試設定仍來自執行中快照中選定的帳戶。

建議設定：建立伺服器工作區

當 DM 正常運作後，你可以將 Discord 伺服器設定為完整的工作區，每個頻道會有自己的代理工作階段和獨立的上下文。建議在只有你和機器人的私人伺服器上使用。

步驟 1：將伺服器加入伺服器允許名單

這會讓你的代理不只在 DM 中回應，也能在伺服器的任何頻道中回應。


  #### 透過代理設定
    > 「將我的 Discord 伺服器 ID `<server_id>` 加入伺服器允許名單」

  #### 設定

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

步驟 2：允許不需 @提及就回應

預設情況下，代理只在伺服器頻道中被 @提及時才回應。在私人伺服器上，你可能希望它回應每則訊息。


  #### 透過代理設定
    > 「讓我的代理在這個伺服器上不需要被 @提及就回應」

  #### 設定
    在伺服器設定中設定 `requireMention: false`：

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

步驟 3：規劃伺服器頻道中的記憶

預設情況下，長期記憶（MEMORY.md）只在 DM 工作階段中載入。伺服器頻道不會自動載入 MEMORY.md。


  #### 透過代理設定
    > 「當我在 Discord 頻道中提問時，如果需要 MEMORY.md 的長期上下文，請使用 memory_search 或 memory_get。」

  #### 手動
    如果你需要在每個頻道共享上下文，將穩定的指示放在 `AGENTS.md` 或 `USER.md`（每個工作階段都會載入）。將長期筆記保存在 `MEMORY.md` 中，並使用記憶工具按需存取。

現在在你的 Discord 伺服器上建立一些頻道並開始對話。代理可以看到頻道名稱，每個頻道有自己隔離的工作階段——你可以設定 #coding、#home、#research 或任何適合你工作流程的名稱。

執行時模型

• 閘道擁有 Discord 連線。
• 回覆路由是確定性的：Discord 收到的訊息回覆到 Discord。
• 預設（session.dmScope=main）下，直接聊天共享代理主工作階段（agent:main:main）。
• 伺服器頻道有隔離的 session key（agent:<agentId>:discord:channel:<channelId>）。
• 群組 DM 預設被忽略（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 components v2 容器用於代理訊息。使用訊息工具搭配 components payload。互動結果會作為正常收到的訊息路由回代理，並遵循現有的 Discord replyToMode 設定。

支援的區塊：

• text、section、separator、actions、media-gallery、file
• 動作列最多允許 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" },
          ],
        },
      ],
    },
  },
}

存取控制與路由

DM 政策

`channels.discord.dmPolicy` 控制 DM 存取（舊版：`channels.discord.dm.policy`）：

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

如果 DM 政策不是 open，未知使用者會被阻擋（或在 `pairing` 模式下收到配對提示）。

多帳戶優先順序：

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

DM 目標格式：

- `user:<id>`
- `<@id>` 提及

單純的數字 ID 具有歧義性，除非提供明確的 user/channel 目標類型，否則會被拒絕。

伺服器政策

伺服器處理由 `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`。

提及與群組 DM

伺服器訊息預設需要提及才會回應。

提及偵測包括：

- 明確的機器人提及
- 設定的提及模式（`agents.list[].groupChat.mentionPatterns`，備用 `messages.groupChat.mentionPatterns`）
- 在支援的情況下隱式的回覆機器人行為

`requireMention` 在每個伺服器/頻道上設定（`channels.discord.guilds...`）。
`ignoreOtherMentions` 可選擇性地丟棄提及了其他使用者/角色但沒有提及機器人的訊息（不包括 @everyone/@here）。

群組 DM：

- 預設：忽略（`dm.groupEnabled=false`）
- 可透過 `dm.groupChannels`（頻道 ID 或 slug）設定允許名單

基於角色的代理路由

使用 bindings[].match.roles 依角色 ID 將 Discord 伺服器成員路由到不同代理。基於角色的 binding 僅接受角色 ID，在 peer 或 parent-peer binding 之後、僅限伺服器的 binding 之前評估。如果 binding 也設定了其他匹配欄位（例如 peer + guildId + roles），所有設定的欄位都必須匹配。

{
  bindings: [
    {
      agentId: "opus",
      match: {
        channel: "discord",
        guildId: "123456789012345678",
        roles: ["111111111111111111"],
      },
    },
    {
      agentId: "sonnet",
      match: {
        channel: "discord",
        guildId: "123456789012345678",
      },
    },
  ],
}

開發者入口設定

1. Discord Developer Portal -> **Applications** -> **New Application**
2. **Bot** -> **Add Bot**
3. 複製 bot token

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

- Message Content Intent
- Server Members Intent（建議）

Presence intent 是選填的，只有在你想接收成員狀態更新時才需要。設定機器人狀態（`setPresence`）不需要啟用成員的 Presence 更新。

OAuth URL 產生器：

- 範圍：`bot`、`applications.commands`

一般基準權限：

- View Channels
- Send Messages
- Read Message History
- Embed Links
- Attach Files
- Add Reactions（選填）

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

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

- 伺服器 ID
- 頻道 ID
- 使用者 ID

OpenClaw 設定中建議使用數字 ID 以確保可靠的稽核和探測。

原生指令與指令授權

• commands.native 預設為 "auto"，在 Discord 中啟用。
• 每頻道覆寫：channels.discord.commands.native。
• commands.native=false 會明確清除先前註冊的 Discord 原生指令。
• 原生指令授權使用與正常訊息處理相同的 Discord 允許名單/政策。
• 指令可能在未獲授權的使用者的 Discord UI 中仍然可見；執行時仍會執行 OpenClaw 授權並回傳「未授權」。

參閱 斜線指令 了解指令目錄和行為。

預設斜線指令設定：

• ephemeral: true

功能細節

Discord 在代理輸出中支援回覆標籤：

- `[[reply_to_current]]`
- `[[reply_to:<id>]]`

由 `channels.discord.replyToMode` 控制：

- `off`（預設）
- `first`
- `all`

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

訊息 ID 會在上下文/歷史中呈現，讓代理可以定位特定訊息。

OpenClaw 可以透過傳送暫時訊息並在文字到達時編輯它來串流草稿回覆。

- `channels.discord.streaming` 控制預覽串流（`off` | `partial` | `block` | `progress`，預設：`off`）。
- `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 會跳過預覽串流以避免重複串流。

伺服器歷史記錄上下文：

- `channels.discord.historyLimit` 預設 `20`
- 備用：`messages.groupChat.historyLimit`
- `0` 停用

DM 歷史記錄控制：

- `channels.discord.dmHistoryLimit`
- `channels.discord.dms["<user_id>"].historyLimit`

討論串行為：

- Discord 討論串作為頻道工作階段路由
- 父討論串中繼資料可用於父工作階段關聯
- 討論串設定繼承父頻道設定，除非有討論串專屬項目

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

Discord 可以將討論串綁定到工作階段目標，這樣該討論串中的後續訊息會持續路由到相同的工作階段（包括子代理工作階段）。

指令：

- `/focus <target>` 將目前/新討論串綁定到子代理/工作階段目標
- `/unfocus` 移除目前討論串的綁定
- `/agents` 顯示活動中的執行和綁定狀態
- `/session idle <duration|off>` 檢視/更新聚焦綁定的閒置自動解除
- `/session max-age <duration|off>` 檢視/更新聚焦綁定的硬性最大壽命

設定：

{
  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` 及相關操作將不可用。

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

對於穩定的「常駐」ACP 工作區，可設定最上層的 typed ACP binding 以指向 Discord 對話。

設定路徑：

- `bindings[]` 搭配 `type: "acp"` 和 `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 綁定。
- 在綁定的頻道或討論串中，`/new` 和 `/reset` 會在原地重設相同的 ACP 工作階段。
- 臨時討論串綁定仍然有效，可以在啟用時覆寫目標解析。

參閱 [ACP 代理](/docs/tools/acp-agents) 了解綁定行為詳情。

每伺服器的回應通知模式：

- `off`
- `own`（預設）
- `all`
- `allowlist`（使用 `guilds.<id>.users`）

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

`ackReaction` 在 OpenClaw 處理收到的訊息時傳送確認表情符號。

解析順序：

- `channels.discord.accounts.<accountId>.ackReaction`
- `channels.discord.ackReaction`
- `messages.ackReaction`
- 代理身份表情符號備用（`agents.list[].identity.emoji`，否則 "👀"）

注意事項：

- Discord 接受 unicode 表情符號或自訂表情符號名稱。
- 使用 `""` 停用該頻道或帳戶的回應。

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

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

停用：

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

透過 HTTP(S) 代理路由 Discord 閘道 WebSocket 流量和啟動 REST 查詢（應用程式 ID + 允許名單解析），使用 `channels.discord.proxy`。

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

每帳戶覆寫：

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

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

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

注意事項：

- 允許名單可使用 `pk:<memberId>`
- 僅在 `channels.discord.dangerouslyAllowNameMatching: true` 時才透過名稱/slug 匹配成員顯示名稱
- 查詢使用原始訊息 ID 並受時間視窗約束
- 如果查詢失敗，代理訊息會被視為機器人訊息並丟棄，除非 `allowBots=true`

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

僅設定狀態範例：

{
  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

自動狀態範例（執行時健康信號）：

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

自動狀態將執行時可用性對應到 Discord 狀態：健康 => 線上、降級或未知 => 閒置、耗盡或不可用 => 請勿打擾。可選的文字覆寫：

- `autoPresence.healthyText`
- `autoPresence.degradedText`
- `autoPresence.exhaustedText`（支援 `{reason}` 佔位符）

Discord 在 DM 中支援基於按鈕的執行核准，也可選擇性地在原始頻道中發布核准提示。

設定路徑：

- `channels.discord.execApprovals.enabled`
- `channels.discord.execApprovals.approvers`
- `channels.discord.execApprovals.target`（`dm` | `channel` | `both`，預設：`dm`）
- `agentFilter`、`sessionFilter`、`cleanupAfterResolve`

當 `target` 為 `channel` 或 `both` 時，核准提示會在頻道中可見。只有設定的核准者可以使用按鈕；其他使用者會收到短暫的拒絕訊息。核准提示包含指令文字，因此僅在信任的頻道中啟用頻道送達。如果無法從 session key 推導頻道 ID，OpenClaw 會回退到 DM 送達。

此處理程式的閘道授權使用與其他閘道用戶端相同的共享憑證解析契約：

- 環境優先的本地授權（`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`，然後 `gateway.auth.*`）
- 在本地模式下，`gateway.remote.*` 僅在 `gateway.auth.*` 未設定時作為備用；已設定但未解析的本地 SecretRef 會安全失敗
- 透過 `gateway.remote.*` 支援遠端模式（適用時）
- URL 覆寫是安全的：CLI 覆寫不會重用隱式憑證，env 覆寫僅使用 env 憑證

如果核准因未知核准 ID 而失敗，請驗證核准者清單和功能啟用狀態。

相關文件：[執行核准](/docs/tools/exec-approvals)

工具和操作控制

Discord 訊息操作包括傳訊、頻道管理、管理功能、狀態和中繼資料操作。

核心範例：

• 傳訊：sendMessage、readMessages、editMessage、deleteMessage、threadReply
• 回應：react、reactions、emojiList
• 管理：timeout、kick、ban
• 狀態：setPresence

操作控制位於 channels.discord.actions.*。

預設控制行為：

Components v2 UI

OpenClaw 使用 Discord components v2 來處理執行核准和跨上下文標記。Discord 訊息操作也可以接受 components 用於自訂 UI（進階；需要 Carbon 元件實例），而舊版 embeds 仍然可用但不建議使用。

• channels.discord.ui.components.accentColor 設定 Discord 元件容器使用的強調色（十六進位）。
• 透過 channels.discord.accounts.<id>.ui.components.accentColor 按帳戶設定。
• 當 components 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)，這可能是上游 @discordjs/voice 的接收 bug，追蹤於 discord.js #11419。

語音訊息

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)

疑難排解

- 啟用 Message Content Intent
- 當依賴使用者/成員解析時啟用 Server Members Intent
- 變更 Intent 後重新啟動閘道

- 驗證 `groupPolicy`
- 驗證 `channels.discord.guilds` 下的伺服器允許名單
- 如果伺服器有 `channels` 對照表，只有列出的頻道被允許
- 驗證 `requireMention` 行為和提及模式

有用的檢查：

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

常見原因：

- `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 ...`

Listener 預算調整：

- 單帳戶：`channels.discord.eventQueue.listenerTimeout`
- 多帳戶：`channels.discord.accounts.<accountId>.eventQueue.listenerTimeout`

Worker 執行逾時調整：

- 單帳戶：`channels.discord.inboundWorker.runTimeoutMs`
- 多帳戶：`channels.discord.accounts.<accountId>.inboundWorker.runTimeoutMs`
- 預設：`1800000`（30 分鐘）；設定 `0` 停用

建議基準：

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

使用 `eventQueue.listenerTimeout` 處理慢速 listener 設定，僅在需要對排隊的代理回合設定另一道安全閥時使用 `inboundWorker.runTimeoutMs`。

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

如果你使用 slug key，執行時匹配仍可運作，但探測無法完整驗證權限。

- DM 停用：`channels.discord.dm.enabled=false`
- DM 政策停用：`channels.discord.dmPolicy="disabled"`（舊版：`channels.discord.dm.policy`）
- 在 `pairing` 模式下等待配對核准

預設忽略機器人發送的訊息。

如果你設定了 `channels.discord.allowBots=true`，請使用嚴格的提及和允許名單規則以避免循環行為。
建議使用 `channels.discord.allowBots="mentions"` 僅接受提及機器人的機器人訊息。

- 保持 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](https://github.com/discordjs/discord.js/issues/11419) 比對

設定參考

主要參考：

• 設定參考 - Discord

Discord 重要欄位：

• 啟動/授權：enabled、token、accounts.*、allowBots
• 政策：groupPolicy、dm.*、guilds.*、guilds.*.channels.*
• 指令：commands.native、commands.useAccessGroups、configWrites、slashCommand.*
• 事件佇列：eventQueue.listenerTimeout（listener 預算）、eventQueue.maxQueueSize、eventQueue.maxConcurrency
• 收到處理器：inboundWorker.runTimeoutMs
• 回覆/歷史記錄：replyToMode、historyLimit、dmHistoryLimit、dms.*.historyLimit
• 送達：textChunkLimit、chunkMode、maxLinesPerMessage
• 串流：streaming（舊版別名：streamMode）、draftChunk、blockStreaming、blockStreamingCoalesce
• 媒體/重試：mediaMaxMb、retry
  • mediaMaxMb 限制 Discord 傳出上傳（預設：8MB）
• 操作：actions.*
• 狀態：activity、status、activityType、activityUrl
• UI：ui.components.accentColor
• 功能：threadBindings、最上層 bindings[]（type: "acp"）、pluralkit、execApprovals、intents、agentComponents、heartbeat、responsePrefix

安全與營運

• 將 bot token 視為機密（在受監管環境中建議使用 DISCORD_BOT_TOKEN）。
• 授予最小權限的 Discord 權限。
• 如果指令部署/狀態過時，重新啟動閘道並使用 openclaw channels status --probe 重新檢查。

相關

• 配對
• 頻道路由
• 多代理路由
• 疑難排解
• 斜線指令