快速上手 Discord Bot API

串接聊天機器人最煩人的通常不是寫邏輯，而是處理那堆碎碎念的 Gateway 連線、Session 隔離，還有沒完沒了的權限設定。如果你曾經為了讓機器人正確回覆一則私訊而翻遍文件，你一定懂那種「我只想跑起來」的焦慮。

這份指南會幫你跳過那些坑，直接把你的 Discord Bot 跑起來，支援私訊（DM）與伺服器頻道。

需要準備的東西

Discord Developer Portal 帳號
一個已經建立好的 Discord Application
Bot Token 與必要的權限設定

快速開始

只要 5 分鐘，你就能完成基礎配置並啟動 Gateway。

1. 開啟 Discord Bot 的 Intents

在 Discord Developer Portal 中，找到你的應用程式並添加 Bot，然後務必開啟以下權限：

Message Content Intent
Server Members Intent（推薦開啟，用於處理名稱與 ID 的對應以及白名單比對）

2. 配置你的 Token

你可以直接在配置文件中設定，或使用環境變數。

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

如果你只想為預設帳號設定環境變數：

DISCORD_BOT_TOKEN=...

注意： Token 解析具有帳號感知能力。配置文件中的 token 優先級高於環境變數。DISCORD_BOT_TOKEN 僅供預設帳號使用。

3. 邀請機器人並啟動 Gateway

將機器人邀請到你的伺服器（需具備發送訊息權限），然後執行：

openclaw gateway

4. 核准第一次 DM 配對

Discord 私訊預設使用配對模式。請執行以下指令完成核准：

openclaw pairing list discord
openclaw pairing approve discord <CODE>

請注意，配對代碼會在 1 小時後過期。

Runtime Model 運作邏輯

了解連線如何運作，能幫你省下不少除錯時間：

連線管理：Gateway 負責維護 Discord 的連線。
路由機制：回覆路由是確定的，從 Discord 進來的訊息會直接回傳到 Discord。
Session 隔離：預設情況下（session.dmScope=main），私訊會共用 Agent 的主 Session；而伺服器頻道（Guild channels）則擁有獨立的 Session Key。
Slash Commands：原生指令會在隔離的 Command Session 中執行，但仍會帶著 CommandTargetSessionKey 到對應的對話 Session。

疑難排解

配對失敗：如果 openclaw pairing approve 沒反應，請檢查代碼是否超過 1 小時。
Token 沒生效：如果你在配置文件設定了 token，系統會忽略 DISCORD_BOT_TOKEN 環境變數。
群組私訊沒反應：群組私訊（Group DMs）預設是被忽略的（channels.discord.dm.groupEnabled=false）。

想針對你的特定場景進行設定？試試 AI Setup Assistant 獲取即時協助。

下一步

在開發 Discord 機器人時，最怕的就是控制不住它。有時候你只是想測試一個新功能，結果機器人開始在不該出現的頻道亂說話，或是被陌生人私訊轟炸。要如何精準控制機器人的「發言權」和「聽力範圍」，是每個開發者都會遇到的煩惱。

這篇文章會帶你設定 Discord 的存取控制與路由，讓你不用擔心機器人跑去不該去的地方。

需要準備的東西

在開始設定之前，請確保你已經準備好以下資訊（這些都可以在 Discord 相關頁面找到）：

Discord Developer Portal 的存取權限
你的 Bot Token
Discord 伺服器 ID、頻道 ID 以及使用者 ID（需開啟 Discord 的 Developer Mode 才能複製）

快速開始

只要 5 分鐘，你就能完成最基礎的 Discord 機器人串接：

建立 App 與 Bot：前往 Discord Developer Portal，建立 New Application，然後在 Bot 選項中點擊 Add Bot 並複製你的 Bot Token。
開啟權限：在 Bot -> Privileged Gateway Intents 頁面，務必開啟 Message Content Intent。如果你需要處理成員資訊，建議也開啟 Server Members Intent。
產生邀請連結：在 OAuth URL Generator 中勾選 bot 和 applications.commands 範疇（scopes），並勾選基礎權限（如 View Channels, Send Messages 等）。
配置設定檔：在你的設定中填入 DISCORD_BOT_TOKEN。

如果你沒有在設定檔中建立 channels.discord 區塊，系統預設會將 groupPolicy 設為 "open" 並在日誌中發出警告。

深入存取控制

DM 私訊政策

你可以透過 channels.discord.dm.policy 來決定誰可以私訊機器人：

pairing (預設值)：未知使用者會被要求進行配對。
allowlist：只允許白名單內的使用者。
open：開放給所有人（需同時將 channels.discord.dm.allowFrom 設為 ["*"]）。
disabled：完全停用私訊功能。

在傳送訊息時，DM 的目標格式可以使用 user:<id> 或 <@id>。請注意，單純的數字 ID 會因為歧義而被拒絕，除非你明確指定了目標類型。

伺服器 (Guild) 政策

當你設定了 channels.discord 後，預設的安全性基準是 allowlist。你可以透過 channels.discord.groupPolicy 進行控制：

open：允許進入所有伺服器。
allowlist：只允許特定的伺服器。
disabled：停用伺服器功能。

在 allowlist 模式下，機器人會檢查伺服器 ID 是否符合 channels.discord.guilds。如果某個伺服器配置了 channels 區塊，則只有列出的頻道會被允許；如果沒有配置 channels 區塊，則該伺服器內的所有頻道都預設允許。

範例設定：

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

提及 (Mentions) 與群組私訊

在伺服器中，機器人預設是「被提及」才會回應。偵測方式包含：

直接 @ 機器人。
符合設定的提及模式（mentionPatterns）。
在支援的情況下，回覆機器人的訊息也會被視為提及。

至於群組私訊（Group DMs），預設是停用的（dm.groupEnabled=false）。如果你需要開啟，可以透過 dm.groupChannels 填入頻道 ID 或 slug 來設定白名單。

原生指令與授權

commands.native 在 Discord 中預設為 "auto"（啟用）。
你可以透過 channels.discord.commands.native 針對特定頻道進行覆寫。
如果設為 false，系統會明確清除之前註冊的所有 Discord 原生指令。
注意：即使使用者沒有權限執行，指令可能仍會出現在 Discord UI 中。但當使用者嘗試執行時，系統依然會執行權限檢查並回傳 “not authorized”。

疑難排解

ID 錯誤：如果你使用純數字 ID 但系統報錯，請確保你提供了明確的 target kind（例如 user:<id>），或者改用 <@id> 格式。
機器人不回應訊息：請檢查 Discord Developer Portal 中的 Message Content Intent 是否已開啟，這是機器人讀取訊息內容的必要條件。
權限不足：避免直接給予機器人 Administrator 權限。請檢查是否已勾選 View Channels, Send Messages 和 Read Message History。
設定未生效：如果你只設定了 DISCORD_BOT_TOKEN 而沒有配置 channels.discord 區塊，系統會退回到 groupPolicy="open" 並在 logs 中顯示警告。

如果你在設定過程中遇到任何問題，可以詢問我們的 AI Setup Assistant 獲取即時協助。

下一步

Slash commands - 查看指令列表與行為設定
Message handling - 深入了解訊息處理機制

開發 Discord 機器人時，最讓人頭痛的就是對話上下文亂跳，或是 Agent 沒辦法精準回覆特定的訊息。如果你也遇過訊息歷史紀錄抓不準，或是想在 Discord 裡直接點個按鈕就完成指令審核，這些進階功能就是幫你解決這些瑣事的關鍵。

我們整理了 Discord 整合中的各項細節，讓你調整出最符合你需求的對話邏輯。

需要準備的東西

已建立的 Discord 機器人與頻道權限
基礎的設定檔編輯能力

快速開始

如果你想在 5 分鐘內優化你的 Discord 整合，可以從這兩個最常用的設定入手：

開啟回覆模式：在設定檔中將 channels.discord.replyToMode 設為 all，讓 Agent 能夠標註並回覆特定訊息。
調整歷史紀錄：透過 channels.discord.historyLimit 控制 Agent 讀取的訊息量，預設為 20 則。

功能細節

回覆標籤與原生回覆

Discord 支援在 Agent 輸出中使用回覆標籤，這能讓你的 Agent 像真人一樣回覆特定訊息：

[[reply_to_current]]：回覆當前訊息
[[reply_to:<id>]]：回覆指定 ID 的訊息

你可以透過 channels.discord.replyToMode 來控制這個行為：

off (預設值)
first
all

訊息 ID 會出現在上下文與歷史紀錄中，方便 Agent 針對特定訊息進行操作。

歷史紀錄、上下文與 Thread 行為

管理對話長度與 Thread 邏輯對於維持 Agent 的反應品質非常重要。

Guild 歷史紀錄控制：

channels.discord.historyLimit：預設為 20
Fallback 機制：若未設定，會使用 messages.groupChat.historyLimit
設為 0 則會停用歷史紀錄

DM 歷史紀錄控制：

全域 DM 設定：channels.discord.dmHistoryLimit
特定用戶設定：channels.discord.dms["<user_id>"].historyLimit

Thread 行為：

Discord Threads 會被引導為 Channel Session。
父 Thread 的 Metadata 可用於父子 Session 的連結。
Thread 會繼承父頻道的設定，除非你有針對該 Thread 建立特定的設定條目。
頻道主題 (Channel Topics) 會作為 untrusted 上下文注入，而不是作為 System Prompt。

反應通知 (Reaction notifications)

你可以設定各個 Guild 的反應通知模式：

off
own (預設值)
all
allowlist (需搭配 guilds.<id>.users 使用)

這些反應事件會轉換為系統事件，並附加到對應的 Discord Session 中。

設定寫入 (Config writes)

預設情況下，允許透過頻道發起的設定寫入。這會影響 /config set|unset 的流程（當 Command 功能開啟時）。

如果你想停用這個功能，可以使用以下設定：

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

PluralKit 支援

如果你需要處理 PluralKit 的代理訊息，可以開啟解析功能來對應成員身份：

{
  channels: {
    discord: {
      pluralkit: {
        enabled: true,
        token: "pk_live_...", // 選填；私人群組系統才需要
      },
    },
  },
}

注意事項：

Allowlist 可以使用 pk:<memberId> 格式。
成員顯示名稱會透過名稱或 Slug 進行比對。
查詢會使用原始訊息 ID 並受時間窗口限制。
如果查詢失敗，代理訊息會被視為機器人訊息並丟棄，除非你設定了 allowBots=true。

Discord 中的執行審核 (Exec approvals)

Discord 支援在 DM 中使用按鈕式的執行審核。

設定路徑：

channels.discord.execApprovals.enabled
channels.discord.execApprovals.approvers
其他參數：agentFilter, sessionFilter, cleanupAfterResolve

疑難排解

審核失敗：如果審核時出現 unknown approval IDs，請檢查 approvers 名單是否正確，以及功能是否確實開啟。
訊息丟失：在 PluralKit 環境下，如果查詢失敗且沒開啟 allowBots=true，訊息會被直接丟棄。
歷史紀錄失效：確認 historyLimit 沒有被誤設為 0。

如果你在設定過程中遇到任何問題，可以直接詢問我們的 AI Setup Assistant。

下一步

Exec approvals 完整文件
了解更多關於 Gateway 的進階配置

寫 Discord bot 最煩人的就是權限管理。有時候你明明寫好了程式碼，bot 卻沒反應，或者在不該說話的時候亂發訊息。搞清楚哪些功能是開箱即用，哪些需要手動在 Gateway 開啟，能幫你省下大量對著報錯訊息發呆的時間。

這篇文會帶你快速看過 Discord 的操作（Actions）分類，以及最重要的 Action Gates 預設設定。

需要準備的東西

Discord 開發者帳號與 Bot token
存取 channels.discord.actions.* 配置的權限

快速開始

Discord 的 Actions 涵蓋了從傳送訊息到頻道管理的所有行為。你可以透過 API 執行以下核心操作：

Messaging 訊息處理: sendMessage, readMessages, editMessage, deleteMessage, threadReply
Reactions 表情回應: react, reactions, emojiList
Moderation 伺服器管理: timeout, kick, ban
Presence 狀態設定: setPresence

所有的 Action Gates 都定義在 channels.discord.actions.* 底下。在開發時，你需要注意哪些功能是預設開啟的，哪些則需要你手動調整。

Action Gates 預設行為

下表列出了各個 Action group 的預設狀態。如果你的 bot 無法執行某個動作，請先檢查該類別是否被設為 disabled：

Action group	Default
reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions	enabled
roles	disabled
moderation	disabled
presence	disabled

疑難排解

如果你發現 timeout 或 kick 等功能無法運作，這通常不是你的程式碼有問題，而是因為 moderation 類別在 Action Gates 中預設是 disabled。同樣地，如果你需要調整 bot 的線上狀態（presence）或管理身分組（roles），你也必須手動將其狀態改為 enabled。

有任何設定上的疑問，直接問 AI Setup Assistant 是最快的方法。

下一步

寫 Discord 機器人最崩潰的瞬間，通常不是程式碼噴錯，而是明明 Gateway 跑起來了，機器人卻像死掉一樣完全不理人。這種「安靜的失敗」往往藏在權限、Intent 或複雜的白名單配置裡。

如果你發現訊息發不出去，或者機器人根本看不見頻道裡的對話，這篇指南整理了從權限審計到配置優化的所有細節，幫你快速抓出問題。

需要準備的東西

Discord Bot Token（建議準備好環境變數 DISCORD_BOT_TOKEN）
Discord Developer Portal 的存取權限
已安裝 OpenClaw CLI 並配置好基礎 Gateway

快速開始

遇到機器人沒反應時，請照這四步快速診斷：

基礎檢查：執行 openclaw doctor 確認 Gateway 與 Discord API 的連線狀態。
權限探測：執行 openclaw channels status --probe 檢查特定頻道的權限是否正常。
監控日誌：使用 openclaw logs --follow 觀察訊息是否被攔截以及攔截的原因。
重啟生效：如果你修改了 Discord Portal 的 Intent 設定，請務必重啟 Gateway。

疑難排解

權限與 Intent 問題

使用了不允許的 Intent 或機器人看不到訊息：
- 請在 Discord 開發者後台開啟 Message Content Intent。
- 如果你的功能依賴使用者或成員解析，請開啟 Server Members Intent。
- 注意：修改 Intent 設定後，必須重啟 Gateway。

訊息攔截與過濾

Guild 訊息被意外攔截：
- 檢查 groupPolicy 設定。
- 確認 channels.discord.guilds 下的 Guild 白名單。
- 如果你設定了 Guild 的 channels map，則只有被列出的頻道會被允許。
- 檢查 requireMention 的行為與 Mention Pattern 是否符合預期。

你可以利用這些工具進行檢查：

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

設定了 requireMention 為 false 但訊息仍被攔截：
- 常見原因是 groupPolicy="allowlist" 但沒有匹配的 Guild/Channel 白名單。
- requireMention 配置位置錯誤（必須放在 channels.discord.guilds 下或具體的 Channel 項目中）。
- 發送者被 Guild/Channel 的 users 白名單封鎖。

診斷工具限制

權限審計不匹配：
- channels status --probe 的權限檢查僅支援數字形式的 Channel ID。
- 如果你使用 Slug Key（別名），運行時的匹配雖然有效，但 probe 工具無法完全驗證其權限。

私訊與配對

DM 或配對問題：
- 確認 DM 是否被停用：channels.discord.dm.enabled=false。
- 確認 DM 策略是否為：channels.discord.dm.policy="disabled"。
- 如果處於 pairing 模式，請確認是否正在等待配對核准。

機器人循環

Bot to Bot 迴圈：
- 預設情況下，Gateway 會忽略機器人發出的訊息。
- 如果你將 channels.discord.allowBots 設為 true，請務必搭配嚴格的 Mention 和白名單規則，避免產生無限迴圈。

Configuration reference pointers

以下是你最常需要調整的核心配置項：

啟動與認證：enabled, token, accounts.*, allowBots
策略控制：groupPolicy, dm.*, guilds.*, guilds.*.channels.*
指令設定：commands.native, commands.useAccessGroups, configWrites
回覆與歷史紀錄：replyToMode, historyLimit, dmHistoryLimit, dms.*.historyLimit
訊息傳遞：textChunkLimit, chunkMode, maxLinesPerMessage
媒體與重試：mediaMaxMb, retry
動作與功能：actions.*, pluralkit, execApprovals, intents, agentComponents, heartbeat, responsePrefix

更詳細的參數說明可以參考： Configuration reference - Discord

Safety and operations

金鑰安全：請將 Bot Token 視為最高機密。在受控環境中，優先使用 DISCORD_BOT_TOKEN 環境變數。
最小權限原則：只授予機器人運作所需的最低 Discord 權限。
狀態同步：如果發現指令部署或狀態過時，請重啟 Gateway 並使用 openclaw channels status --probe 重新檢查。

遇到搞不定的配置？直接問 AI Setup Assistant 幫你診斷。

下一步

Pairing - 了解如何進行頻道配對
Channel routing - 掌握訊息路由邏輯
Troubleshooting - 更多通用排錯技巧
Slash commands - 設定 Discord 指令

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。