Discord

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

• [[reply_to_current]]
• [[reply_to:<id>]]

由 channels.discord.replyToMode 控制：

• off（預設）
• first
• all
• batched

注意：off 會停用隱含回覆串接。明確的 [[reply_to_*]] 標籤仍會被遵循。 first 一律會將隱含的原生回覆參考附加到該回合的第一則外送 Discord 訊息。 batched 只會在 傳入回合是多則訊息的防抖批次時，附加 Discord 的隱含原生回覆參考。這在你主要想針對模糊的爆量聊天使用原生回覆，而不是每個 單一訊息回合都使用時很有用。

訊息 ID 會浮現在內容/歷史記錄中，讓代理可以鎖定特定訊息。

OpenClaw 可以透過傳送暫時訊息，並在文字抵達時編輯該訊息來串流草稿回覆。channels.discord.streaming 接受 off | partial | block | progress（預設）。progress 會保留一則可編輯的狀態草稿，並以工具進度更新它直到最終送達；streamMode 是舊版執行階段別名。執行 openclaw doctor --fix，將保存的設定改寫為標準鍵。

將 channels.discord.streaming.mode 設為 off 可停用 Discord 預覽編輯。如果已明確啟用 Discord 區塊串流，OpenClaw 會略過預覽串流以避免雙重串流。

{
channels: {
discord: {
  streaming: {
    mode: "progress",
    progress: {
      label: "auto",
      maxLines: 8,
      toolProgress: true,
    },
  },
},
},
}

• partial 會在 token 抵達時編輯單一預覽訊息。
• block 會輸出草稿大小的區塊（使用 draftChunk 調整大小與斷點，並限制在 textChunkLimit 內）。
• 媒體、錯誤與明確回覆的最終訊息會取消待處理的預覽編輯。
• streaming.preview.toolProgress（預設 true）控制工具/進度更新是否重用預覽訊息。
• streaming.preview.commandText / streaming.progress.commandText 控制精簡進度列中的指令/執行詳細資料：raw（預設）或 status（僅工具標籤）。

隱藏原始指令/執行文字，同時保留精簡進度列：

{
  "channels": {
    "discord": {
      "streaming": {
        "mode": "progress",
        "progress": {
          "toolProgress": true,
          "commandText": "status"
        }
      }
    }
  }
}

預覽串流僅支援文字；媒體回覆會退回一般送達。當已明確啟用 block 串流時，OpenClaw 會略過預覽串流以避免雙重串流。

伺服器歷史內容：

• channels.discord.historyLimit 預設 20
• 後援：messages.groupChat.historyLimit
• 0 會停用

DM 歷史記錄控制：

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

討論串行為：

• Discord 討論串會作為頻道工作階段路由，並繼承父頻道設定，除非被覆寫。
• 討論串工作階段會繼承父頻道的工作階段層級 /model 選擇，作為僅模型的後援；討論串本機的 /model 選擇仍有優先權，且除非啟用逐字稿繼承，否則不會複製父逐字稿歷史記錄。
• channels.discord.thread.inheritParent（預設 false）讓新的自動討論串選擇從父逐字稿播種。每帳號覆寫位於 channels.discord.accounts.<id>.thread.inheritParent。
• 訊息工具反應可以解析 user:<id> DM 目標。
• guilds.<guild>.channels.<channel>.requireMention: false 會在回覆階段啟用後援期間保留。

頻道主題會以不受信任內容注入。允許清單會控管誰能觸發代理，而不是完整的補充內容遮蔽邊界。

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,
    spawnSessions: true,
    defaultSpawnContext: "fork",
  },
},
},
}

注意事項：

• session.threadBindings.* 會設定全域預設值。
• channels.discord.threadBindings.* 會覆寫 Discord 行為。
• spawnSessions 控制 sessions_spawn({ thread: true }) 與 ACP 討論串產生的自動建立/繫結討論串。預設：true。
• defaultSpawnContext 控制討論串繫結產生的原生子代理內容。預設："fork"。
• 已棄用的 spawnSubagentSessions/spawnAcpSessions 鍵會由 openclaw doctor --fix 遷移。
• 如果帳號已停用討論串繫結，/focus 與相關討論串繫結操作將無法使用。

請參閱子代理、ACP 代理與設定參考。

若要使用穩定且「永遠開啟」的 ACP 工作區，請設定頂層具型別的 ACP 繫結，以 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 spawn codex --bind here 會就地繫結目前頻道或討論串，並讓未來訊息保留在相同 ACP 工作階段。討論串訊息會繼承父頻道繫結。
• 在已繫結的頻道或討論串中，/new 與 /reset 會就地重設相同 ACP 工作階段。暫時討論串繫結可在作用中時覆寫目標解析。
• spawnSessions 會控管透過 --thread auto|here 建立/繫結子討論串。

請參閱 ACP 代理了解繫結行為詳細資料。

每伺服器反應通知模式：

• 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) 代理搭配 channels.discord.proxy 路由 Discord gateway WebSocket 流量與啟動 REST 查詢（應用程式 ID + 允許清單解析）。

{
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，並受時間範圍限制
• 如果查詢失敗，代理訊息會被視為 bot 訊息並丟棄，除非 allowBots=true

當代理需要對已知 Discord 使用者進行確定性的外送提及時，請使用 mentionAliases。鍵是不含前置 @ 的控制代碼；值是 Discord 使用者 ID。未知控制代碼、@everyone、@here，以及 Markdown 程式碼範圍內的提及都會保持不變。

{
channels: {
discord: {
  mentionAliases: {
    Vladislava: "123456789012345678",
  },
  accounts: {
    ops: {
      mentionAliases: {
        OpsLead: "234567890123456789",
      },
    },
  },
},
},
}

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

僅狀態範例：

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

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

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

串流範例：

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

活動類型對照：

• 0：正在玩
• 1：正在串流（需要 activityUrl）
• 2：正在聆聽
• 3：正在觀看
• 4：自訂（使用活動文字作為狀態；表情符號為選用）
• 5：正在競賽

自動顯示狀態範例（執行階段健康訊號）：

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

自動狀態會將執行階段可用性對應到 Discord 狀態：healthy => online、degraded 或 unknown => idle、exhausted 或 unavailable => dnd。選用文字覆寫：

• autoPresence.healthyText
• autoPresence.degradedText
• autoPresence.exhaustedText（支援 {reason} placeholder）

Discord 支援在 DM 中以按鈕處理核准，也可以選擇在來源頻道中發布核准提示。

設定路徑：

• channels.discord.execApprovals.enabled
• channels.discord.execApprovals.approvers（選用；可行時會回退到 commands.ownerAllowFrom）
• channels.discord.execApprovals.target（dm | channel | both，預設：dm）
• agentFilter、sessionFilter、cleanupAfterResolve

當 enabled 未設定或為 "auto"，且至少可從 execApprovals.approvers 或 commands.ownerAllowFrom 解析出一位核准者時，Discord 會自動啟用原生 exec 核准。Discord 不會從頻道 allowFrom、舊版 dm.allowFrom，或 direct-message defaultTo 推斷 exec 核准者。設定 enabled: false 可明確停用 Discord 作為原生核准用戶端。

對於 /diagnostics 和 /export-trajectory 等敏感的 owner-only 群組命令，OpenClaw 會私下傳送核准提示和最終結果。當發起命令的擁有者有 Discord 擁有者路由時，它會先嘗試 Discord DM；若無法使用，則回退到 commands.ownerAllowFrom 中第一個可用的擁有者路由，例如 Telegram。

當 target 為 channel 或 both 時，核准提示會在頻道中可見。只有已解析的核准者可以使用按鈕；其他使用者會收到短暫的拒絕訊息。核准提示包含命令文字，因此只有在可信任的頻道中才應啟用頻道傳遞。若無法從 session key 推導出頻道 ID，OpenClaw 會回退到 DM 傳遞。

Discord 也會呈現其他聊天頻道使用的共用核准按鈕。原生 Discord adapter 主要新增核准者 DM 路由和頻道 fanout。 當這些按鈕存在時，它們是主要的核准 UX；OpenClaw 只有在工具結果表示聊天核准無法使用，或手動核准是唯一途徑時， 才應包含手動 /approve 命令。 如果 Discord 原生核准執行階段未啟用，OpenClaw 會保留 本機 deterministic /approve <id> <decision> 提示可見。如果 執行階段已啟用，但原生卡片無法傳遞到任何目標， OpenClaw 會在同一聊天中傳送備援通知，內含待處理核准中的確切 /approve 命令。

Gateway 驗證和核准解析遵循共用 Gateway client contract（plugin: ID 會透過 plugin.approval.resolve 解析；其他 ID 會透過 exec.approval.resolve 解析）。核准預設會在 30 分鐘後過期。

請參閱 Exec approvals。

• 啟用 Message Content Intent
• 當你依賴使用者/成員解析時，啟用 Server Members Intent
• 變更 intents 後重新啟動 gateway

• 驗證 groupPolicy
• 驗證 channels.discord.guilds 下的 guild allowlist
• 如果 guild channels map 存在，則只允許列出的頻道
• 驗證 requireMention 行為和提及模式

實用檢查：

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

常見原因：

• groupPolicy="allowlist" 沒有相符的 guild/channel 允許清單
• requireMention 設定在錯誤位置（必須位於 channels.discord.guilds 或頻道項目底下）
• 傳送者遭 guild/channel users 允許清單封鎖

典型記錄：

• Slow listener detected ...
• stuck session: sessionKey=agent:...:discord:... state=processing ...

Discord Gateway 佇列旋鈕：

• 單帳號：channels.discord.eventQueue.listenerTimeout
• 多帳號：channels.discord.accounts.<accountId>.eventQueue.listenerTimeout
• 這只控制 Discord Gateway 監聽器工作，不控制代理回合生命週期

Discord 不會對已排入佇列的代理回合套用頻道擁有的逾時。訊息監聽器會立即交接，而已排入佇列的 Discord 執行會保留每個工作階段的順序，直到 session/tool/runtime 生命週期完成或中止工作。

{
channels: {
discord: {
  accounts: {
    default: {
      eventQueue: {
        listenerTimeout: 120000,
      },
    },
  },
},
},
}

OpenClaw 會在連線前擷取 Discord /gateway/bot 中繼資料。暫時性失敗會退回 Discord 的預設 Gateway URL，並在記錄中受到速率限制。

中繼資料逾時旋鈕：

• 單帳號：channels.discord.gatewayInfoTimeoutMs
• 多帳號：channels.discord.accounts.<accountId>.gatewayInfoTimeoutMs
• 未設定 config 時的 env 後援：OPENCLAW_DISCORD_GATEWAY_INFO_TIMEOUT_MS
• 預設值：30000（30 秒），最大值：120000

OpenClaw 會在啟動期間與 runtime 重新連線後等待 Discord 的 Gateway READY 事件。具有啟動錯開的多帳號設定，可能需要比預設值更長的啟動 READY 時窗。

READY 逾時旋鈕：

• 啟動單帳號：channels.discord.gatewayReadyTimeoutMs
• 啟動多帳號：channels.discord.accounts.<accountId>.gatewayReadyTimeoutMs
• 未設定 config 時的啟動 env 後援：OPENCLAW_DISCORD_READY_TIMEOUT_MS
• 啟動預設值：15000（15 秒），最大值：120000
• runtime 單帳號：channels.discord.gatewayRuntimeReadyTimeoutMs
• runtime 多帳號：channels.discord.accounts.<accountId>.gatewayRuntimeReadyTimeoutMs
• 未設定 config 時的 runtime env 後援：OPENCLAW_DISCORD_RUNTIME_READY_TIMEOUT_MS
• runtime 預設值：30000（30 秒），最大值：120000

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

如果你使用 slug 鍵，runtime 比對仍可運作，但 probe 無法完整驗證權限。

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

預設會忽略由 bot 撰寫的訊息。

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

{
channels: {
discord: {
  accounts: {
    mantis: {
      // Mantis listens to other bots only when they mention her.
      allowBots: "mentions",
    },
    molty: {
      // Molty listens to all bot-authored Discord messages.
      allowBots: true,
      mentionAliases: {
        // Lets Molty write "@Mantis" and send a real Discord mention.
        Mantis: "MANTIS_DISCORD_USER_ID",
      },
    },
  },
},
},
}

• 保持 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.js #11449 中的上游 DAVE 接收歷史進行比較