[筆記] Claude Code Discord 串接設定紀錄

記錄 Claude Code 透過 Discord 插件與 Discord 頻道串接的完整流程。
設定日期：2026-04-02

概述

Claude Code 支援透過 Discord 插件（需要 Bun 環境），讓使用者在 Discord 頻道中直接與 Claude Code session 對話。Bot 收到訊息後會轉發到 Claude Code，回覆也會透過 Bot 發送回 Discord。

限制：一個 Bot Token 同時只能有一個活躍的 Claude Code session 連線。

前置準備

1. 前往 Discord Developer Portal 點選 New Application 並命名
2. 在 Bot 頁面建立 username，點選 Reset Token 並複製 Token
3. 開啟以下 Privileged Gateway Intents：
   • Message Content Intent
4. 使用 OAuth2 > URL Generator 產生邀請連結，勾選 bot scope，並給予以下權限：
   • View Channels
   • Send Messages
   • Send Messages in Threads
   • Read Message History
   • Attach Files
   • Add Reactions
5. 開啟產生的 URL，將 Bot 邀請到你的 Discord 伺服器

設定步驟

Step 1：安裝插件

在 Claude Code 中執行：

/plugin install discord@claude-plugins-official

若提示找不到插件，先執行：
/plugin marketplace update claude-plugins-official
或若尚未新增：/plugin marketplace add anthropics/claude-plugins-official
再重新安裝。

安裝後執行 /reload-plugins 啟用插件的 configure 指令。

Step 2：設定 Bot Token

執行 configure 指令並帶入先前複製的 Token：

/discord:configure <token>

Token 會被儲存到 ~/.claude/channels/discord/.env。也可以在啟動 Claude Code 前，在 shell 環境中設定 DISCORD_BOT_TOKEN 變數。

Step 3：以 channels 模式重新啟動

退出 Claude Code，並以 --channels 參數重新啟動，讓 Discord 插件建立連線：

claude --channels plugin:discord@claude-plugins-official

Step 4：配對帳號（DM Pairing）

在 Discord 上傳送 DM（私訊）給你的 Bot，Bot 會回傳一組配對碼。

若 Bot 沒有回應，請確認 Claude Code 是否有以 --channels 啟動。

回到 Claude Code，執行：

/discord:access pair <code>

鎖定存取權限，讓只有你的帳號可以觸發：

/discord:access policy allowlist

Step 5：設定伺服器頻道（可選）

若要使用伺服器頻道而非 DM：

/discord:access group add <頻道ID>

預設 requireMention: true（需要 @Bot 才觸發），加 --no-mention 可關閉：

/discord:access group add <頻道ID> --no-mention

取得頻道 ID：

1. Discord 設定 → 進階 → 開啟「開發者模式」
2. 對文字頻道右鍵 → 「複製頻道 ID」

access.json 結構說明

檔案位置：~/.claude/channels/discord/access.json

{
  "dmPolicy": "allowlist",
  "allowFrom": ["使用者ID"],
  "groups": {
    "頻道ID": {
      "requireMention": false,
      "allowFrom": []
    }
  },
  "pending": {}
}

已知問題

DM 頻道無法回覆

現象：Bot 可以收到 DM 訊息，但無法回覆，錯誤訊息為 channel is not allowlisted。

原因：Discord 插件的 outbound gate 使用 ch.recipientId 檢查 DM 頻道權限，但 Discord.js 的 partial channel 機制可能導致此值為 undefined，使得權限檢查失敗。Inbound gate 則使用 msg.author.id，所以收訊正常。

解法：使用伺服器（Guild）頻道而非 DM 頻道。伺服器頻道透過 groups 設定檢查，不受此問題影響。

常用指令參考