OpenClaw Discord 整合：機器人設定與 Gateway Intents 完整解析
建立 Discord 機器人並連接 OpenClaw 的完整指南，涵蓋 Gateway Intents 設定、私訊安全性原則配置，以及伺服器頻道存取控制。
OpenClaw Guides
Tutorial Authors
概述
Discord 整合讓您可以透過 Discord 機器人與 OpenClaw 進行對話，同時支援私訊（DM）和伺服器文字頻道通訊。本指南涵蓋建立機器人、理解 Gateway Intents、設定私訊安全性原則，以及配置伺服器頻道存取控制——所有內容皆以 OpenClaw 官方文件 為基礎。
前提條件
- 已安裝並執行 OpenClaw
- 一個 Discord 帳戶
- 一個您有管理員權限的 Discord 伺服器（用於測試）
運作方式
在開始之前，先了解 OpenClaw 如何路由 Discord 訊息會很有幫助：
- 私訊對話會合併為共享工作階段（
agent:main:main），預設採用配對驗證機制。 - 伺服器頻道對話依頻道隔離，使用
agent:<agentId>:discord:channel:<channelId>格式。 - 群組私訊預設會被忽略，但可透過
channels.discord.dm.groupEnabled啟用。
當有效的 token 存在且 enabled 不為 false 時，閘道會自動啟動。
步驟 1：建立 Discord 應用程式
前往 Discord Developer Portal
- 造訪 Discord Developer Portal
- 點擊 New Application
- 輸入名稱（例如 "OpenClaw Assistant"）
- 點擊 Create
設定機器人
- 在應用程式中，進入 Bot 分頁
- 點擊 Add Bot → Yes, do it!
- 在 Token 下，點擊 Copy 複製機器人權杖
重要： 請將機器人權杖視為密碼妥善保管，切勿公開分享。若權杖外洩，請立即重新產生。
步驟 2：啟用特權 Gateway Intents
Gateway Intents 控制機器人從 Discord 接收哪些事件。OpenClaw 需要特定的特權 intents 才能正常運作。
必要的 Intents
| Intent | 用途 | 是否必要 | |--------|------|----------| | Message Content Intent | 讀取伺服器頻道中的訊息文字 | 必要 — 缺少此 intent 會導致「Used disallowed intents」錯誤，或機器人可連線但無法回應 | | Server Members Intent | 成員查詢與白名單比對 | 建議啟用 — 使用白名單存取控制時需要 |
在 Developer Portal 中啟用 Intents
- 進入 Developer Portal 中的 Bot 分頁
- 捲動到 Privileged Gateway Intents
- 啟用 MESSAGE CONTENT INTENT（必要）
- 啟用 SERVER MEMBERS INTENT（建議）
- 點擊 Save Changes
注意： 加入超過 100 個伺服器的機器人需要通過 Discord 驗證才能使用特權 intents。
步驟 3：產生機器人邀請 URL
設定 OAuth2
-
進入 OAuth2 → URL Generator
-
選擇範圍：
botapplications.commands（原生斜線命令所需）
-
選擇機器人權限：
View ChannelsSend MessagesRead Message HistoryEmbed LinksAttach FilesAdd Reactions（選用但建議啟用）Use External Emojis（選用）
警告： 除非正在進行除錯，否則請避免授予 Administrator 權限。僅授予必要的權限即可。
- 複製產生的 URL
邀請機器人
- 在瀏覽器中開啟該 URL
- 選擇您的測試伺服器
- 點擊 Authorize
取得數字 ID
在 Discord 中啟用開發者模式（使用者設定 → 應用程式設定 → 進階 → 開發者模式），即可透過右鍵選單複製伺服器、頻道和使用者 ID——設定過程中會需要用到這些 ID。
步驟 4：設定 OpenClaw
選項 A：環境變數
將 token 設定為環境變數：
export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"
選項 B：設定檔
在 OpenClaw 設定檔中直接填入 token：
{
channels: {
discord: {
enabled: true,
token: "YOUR_BOT_TOKEN"
}
}
}
注意： 當環境變數和設定檔中的 token 同時存在時，以設定檔為優先。
選項 C：多帳號支援
若需要執行多個機器人帳號：
{
channels: {
discord: {
accounts: [
{ token: "BOT_TOKEN_1", name: "assistant-1" },
{ token: "BOT_TOKEN_2", name: "assistant-2" }
]
}
}
}
步驟 5：啟動與測試
啟動或重新啟動 OpenClaw 閘道：
openclaw gateway restart
檢查頻道狀態：
openclaw channels status --probe
如果出現異常，可執行診斷：
openclaw doctor
首次私訊聯繫時，機器人預設使用配對機制——傳送者會收到一組限時驗證碼（1 小時後過期），需經核准後才能開始對話。
私訊安全性原則
OpenClaw 提供三種私訊存取控制原則：
配對（預設）
未知的傳送者會收到一組限時配對碼，1 小時後過期。該配對碼必須經核准後對話才能進行。
{
channels: {
discord: {
dm: {
enabled: true,
policy: "pairing"
}
}
}
}
白名單
僅允許已設定的使用者 ID 或使用者名稱發送私訊：
{
channels: {
discord: {
dm: {
enabled: true,
policy: "allowlist",
allowFrom: ["123456789012345678", "username#1234"]
}
}
}
}
開放
任何人都可以發送私訊（請謹慎使用）：
{
channels: {
discord: {
dm: {
enabled: true,
policy: "open",
allowFrom: ["*"]
}
}
}
}
伺服器頻道設定
基本伺服器存取控制
限制機器人只能在特定伺服器和頻道運作，並設定提及需求：
{
channels: {
discord: {
guilds: {
"GUILD_ID": {
requireMention: true,
channels: {
"CHANNEL_ID": {
enabled: true
}
}
}
}
}
}
}
重要：
requireMention必須設定在伺服器或頻道層級，而非最上層的 Discord 設定中。
個別頻道設定
您可以針對每個頻道設定白名單和技能限制：
{
channels: {
discord: {
guilds: {
"GUILD_ID": {
channels: {
"CHANNEL_ID_1": {
enabled: true,
requireMention: true
},
"CHANNEL_ID_2": {
enabled: true,
requireMention: false
}
}
}
}
}
}
}
設定參數
訊息設定
| 參數 | 預設值 | 說明 |
|------|--------|------|
| textChunkLimit | 2000 | 每個外送訊息片段的最大字元數 |
| chunkMode | — | 設定為在空白行（段落邊界）處分割，再套用長度限制 |
| maxLinesPerMessage | 17 | 每則訊息的最大行數 |
| mediaMaxMb | 8 | 媒體檔案大小上限（MB） |
上下文歷史記錄
{
channels: {
discord: {
historyLimit: 20 // 作為上下文納入的近期訊息數量（預設：20，設為 0 則停用）
}
}
}
回覆串接
原生回覆串接預設為關閉。啟用方式如下：
{
channels: {
discord: {
replyToMode: "on" // 啟用原生回覆串接
}
}
}
在代理回應中使用回覆標籤來控制串接行為：
[[reply_to_current]]— 回覆目前正在處理的訊息[[reply_to:<message_id>]]— 回覆特定訊息
表情反應通知
依伺服器設定表情反應事件通知：
{
channels: {
discord: {
guilds: {
"GUILD_ID": {
reactionNotifications: "own" // 選項："off"、"own"、"all"、"allowlist"
}
}
}
}
}
工具動作
代理可以呼叫 discord 工具在 Discord 中執行操作。大部分動作預設為啟用，但 roles 和 moderation 預設為停用。
可用動作
| 類別 | 動作 | |------|------| | 表情反應 | react, sticker, poll | | 訊息 | readMessages, sendMessage, editMessage, deleteMessage, searchMessages | | 討論串 | threadCreate, threadList, threadReply | | 釘選 | pinMessage, unpinMessage, listPins | | 頻道 | channelInfo, channelList | | 成員 | memberInfo, roleInfo, permissions | | 身分組 | roleAdd, roleRemove（預設停用） | | 管理 | timeout, kick, ban（預設停用） | | 其他 | emojiList, voiceStatus, eventList, eventCreate, setPresence |
進階功能
PluralKit 支援
啟用後，OpenClaw 會將代理訊息解析至其底層系統成員，將傳送者顯示為「Member (PK:System)」以防止意外的 Discord 提及。
執行核准按鈕 UI
在私訊對話中，OpenClaw 可以顯示執行核准按鈕，供使用者互動確認工具動作。
重試設定
外送 API 呼叫會在遇到速率限制時自動重試，使用 Discord 的 retry_after 標頭搭配指數退避策略。可透過 channels.discord.retry 參數來設定重試行為。
疑難排解
機器人在線但不回應
-
檢查 Message Content Intent： 缺少此 intent 時，機器人可以連線但無法讀取訊息文字。前往 Developer Portal → Bot → Privileged Gateway Intents，確認 MESSAGE CONTENT INTENT 已啟用。
-
確認頻道權限： 確保機器人在目標頻道中擁有 View Channels 和 Send Messages 權限。
-
檢查提及需求： 如果該伺服器或頻道啟用了
requireMention，您必須 @提及機器人。 -
檢查伺服器/頻道白名單： 確認該頻道未被白名單設定所封鎖。
「Used Disallowed Intents」錯誤
這表示必要的 intents 未在 Developer Portal 中啟用：
- 前往 Developer Portal → Bot → Privileged Gateway Intents
- 啟用 MESSAGE CONTENT INTENT
- 儲存並重新啟動 OpenClaw 閘道
私訊無法運作
- 確認
dm.enabled未被設為false - 檢查私訊原則——若設為「allowlist」，請確認使用者 ID 已被納入
- 若使用「pairing」原則，請檢查配對碼是否已過期（限時 1 小時）
診斷命令
使用內建診斷工具來找出問題：
# 執行完整診斷 openclaw doctor # 檢查頻道狀態並探測連線 openclaw channels status --probe
最佳實踐
- 將機器人權杖視為密碼 — 在受管理的主機上使用環境變數，切勿將權杖提交至版本控制。
- 僅授予必要的權限 — 除非正在除錯，否則避免使用 Administrator。
- 使用配對或白名單私訊原則 — 「open」原則僅適用於已設定適當速率限制的公開機器人。
- 啟用 Server Members Intent，若使用白名單存取控制可獲得更可靠的成員比對。
- 在繁忙的伺服器中使用
requireMention，避免機器人對每則訊息都做出回應。 - 如果閘道卡住，使用
--force重新啟動：openclaw gateway restart --force。