​

Discord (Bot API)

​

快速設定

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

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

DISCORD_BOT_TOKEN=...

openclaw pairing list discord
openclaw pairing approve discord <CODE>

​

建議：設定伺服器工作區

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

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

​

執行模型

• Gateway 擁有 Discord 連線。
• 回覆路由是確定性的：Discord 收入的訊息回覆至 Discord。
• 預設情況下（session.dmScope=main），直接聊天共用 Agent 主要工作階段（agent:main:main）。
• 伺服器頻道使用獨立的工作階段金鑰（agent:<agentId>:discord:channel:<channelId>）。
• 群組私訊預設被忽略（channels.discord.dm.groupEnabled=false）。
• 原生斜線指令在獨立的指令工作階段中執行（agent:<agentId>:discord:slash:<userId>），同時仍將 CommandTargetSessionKey 傳遞至路由的對話工作階段。

​

論壇頻道

• 傳送訊息至論壇父頻道（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"

​

互動元件

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

• 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: {
      groupPolicy: "allowlist",
      guilds: {
        "123456789012345678": {
          requireMention: true,
          ignoreOtherMentions: true,
          users: ["987654321098765432"],
          roles: ["123456789012345678"],
          channels: {
            general: { allow: true },
            help: { allow: true, requireMention: true },
          },
        },
      },
    },
  },
}

​

基於角色的 Agent 路由

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

​

開發者入口網站設定

​

原生指令與指令驗證

• commands.native 預設為 "auto"，在 Discord 上已啟用。
• 每頻道覆寫：channels.discord.commands.native。
• commands.native=false 會明確清除先前已註冊的 Discord 原生指令。
• 原生指令驗證使用與一般訊息處理相同的 Discord 白名單/政策。
• 未獲授權的用戶仍可能在 Discord UI 中看到指令；執行仍會強制執行 OpenClaw 驗證並回傳「未授權」。

• ephemeral: true

​

功能詳細說明

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

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

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

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

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

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

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

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

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

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

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

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

​

工具與操作閘門

• 訊息：sendMessage、readMessages、editMessage、deleteMessage、threadReply
• 反應：react、reactions、emojiList
• 版主：timeout、kick、ban
• 上線狀態：setPresence

​

元件 v2 UI

• channels.discord.ui.components.accentColor 設定 Discord 元件容器使用的強調色（十六進位）。
• 每帳號設定：channels.discord.accounts.<id>.ui.components.accentColor。
• 存在元件 v2 時會忽略 embeds。

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

​

語音頻道

• 啟用原生指令（commands.native 或 channels.discord.commands.native）。
• 設定 channels.discord.voice。
• Bot 需要在目標語音頻道擁有 Connect + Speak 權限。

{
  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 接收錯誤。

​

語音訊息

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

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

​

疑難排解

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

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

​

設定參考指引

• 設定參考 - Discord

• 啟動/驗證：enabled、token、accounts.*、allowBots
• 政策：groupPolicy、dm.*、guilds.*、guilds.*.channels.*
• 指令：commands.native、commands.useAccessGroups、configWrites、slashCommand.*
• 事件佇列：eventQueue.listenerTimeout（監聽器預算）、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 權限。
• 若指令部署/狀態已過期，重啟 Gateway 並用 openclaw channels status --probe 重新確認。

​

相關文件

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