Claude Code Discord 常駐橋接

Claude Code · Discord · MCP · AI Agent · Windows

專案概述

官方 Discord channel plugin 把 Discord gateway 綁在一條 MCP stdio pipe 上，終端機一關 pipe 就斷，所以 bot 只在 Claude Code 開著的時候上線。這個專案讓 bot.ts 以獨立的長駐行程自己持有 gateway 連線：每則允許清單內使用者的 DM，都會 spawn 一個全新的 headless claude -p，載入完整的全域設定（MCP servers、plugins、CLAUDE.md），再由該行程把回覆貼回 Discord。Windows 登入時自動啟動的排程任務負責讓它撐過關終端、崩潰與重開機。同時以 npm 套件（bunx claude-discord-daemon / cdd）與 Claude Code plugin（/claude-discord-daemon:discord 指令）兩種形式散布，授權為 MIT。

核心功能

即時具名工具狀態卡：執行中以單一 embed 就地更新，指出當下在跑的工具、skill、MCP、子代理或指令（例如 MCP matlab·evaluate、Bash、agent code-reviewer、skill xlsx、/commit），而不是籠統的「思考中」
回覆覆蓋狀態卡：成功時狀態卡直接改寫成最終回覆，末尾附一行 Discord -# 淡色腳註（耗時與各類工具的次數），聊天室只留一則訊息；附件、長文或多段回覆改以新訊息送出（就地編輯無法附檔），此時狀態卡只剩腳註
Rich 輸出指令，每個指令在回覆中獨佔一行：
- [[embed: {json}]] 渲染彩色 embed 卡，JSON 可跨多行
- [[file: /絕對路徑]] 附上產出檔，送出前先驗證存在性與大小
- 末行 [[buttons: A | B]] 渲染 2-5 顆 Discord 選擇按鈕，點按的標籤文字會作為下一則訊息回饋進同一個 session
附件下載：使用者上傳的附件（≤ 50 MB）下載到共用 inbox，本機路徑附進 prompt，供 claude 用 Read 讀取
權限中繼：headless run 的權限提示轉成 Discord 上的核准 / 拒絕按鈕卡，由擁有者點選決定，不需要回終端機批准
idle-watchdog：預設沒有總時長上限，只有事件 stream 靜默超過 BOT_IDLE_TIMEOUT_MS（行程卡死）才會砍掉，跑得久不會被誤殺
自然語言開新對話：整則訊息剛好是少數幾個重置語之一，就清掉已存 session，下一則訊息重新開始
per-chat session 續接：每個聊天的 session UUID 存在 sessions.json，後續訊息以 --resume 續接
24/7 常駐：登入時自動啟動的排程任務、detached 啟動、崩潰即重啟、單例 loopback 鎖，撐過關終端、崩潰、重開機
可攜：沒有硬編碼路徑，工作目錄預設為引擎所在目錄，每個路徑都能用環境變數覆寫

專案架構

常駐的啟動鏈是：登入任務 ClaudeDiscordBridge → wscript launch.vbs（detached）→ supervise.cmd 迴圈 → bun bot.ts。橋接自帶 discord.js gateway，而不走官方 channel engine，原因在 Anthropic 把未核准的自訂 channel 擋在 --dangerously-load-development-channels 後面，該旗標會跳出啟動確認對話框；headless daemon 沒有 TTY 可以回應，會直接卡住。由 bot.ts 自己持有 gateway，就不需要這個旗標，也不需要互動確認，能以服務形式無人值守地執行。專案檔案：

claude-discord-daemon

bot.ts · Discord gateway 長駐行程（橋接引擎）

perm-mcp.ts · 權限中繼 MCP

cli.ts · cdd / claude-discord-daemon CLI

launch.vbs · 以 detached 方式啟動 supervisor

supervise.cmd · 崩潰即重啟

install-service.ps1 · 註冊登入時自動啟動的排程任務

.env.example · 環境變數範本

commands

skills

.claude-plugin

videos

技術棧

執行環境：Bun ≥ 1.1.0，TypeScript
Discord：discord.js v14
權限中繼：perm-mcp.ts，使用 MCP SDK（@modelcontextprotocol/sdk）
常駐：Windows 登入時自動啟動的排程任務、launch.vbs、supervise.cmd
散布：npm 套件與 Claude Code plugin

快速開始

僅支援 Windows 11，排程任務、VBS、cmd 的監督鏈是 Windows 專屬。需要 Bun ≥ 1.1.0 且 bun 在 PATH 上、已安裝並登入的 Claude Code CLI（bridge 會 spawn claude -p），以及你自己的 Discord bot token。bot 必須與你共享一個伺服器，Discord 才允許你 DM 它。

寫入 bot token

啟動前，先把 bot token 與允許清單放進 bridge 的 state 目錄（預設 ~/.claude/channels/discord/，可用 DISCORD_STATE_DIR 覆寫）。token 寫入 ~/.claude/channels/discord/.env：

DISCORD_BOT_TOKEN=你的_discord_bot_token

也可以直接在 process 環境設 DISCORD_BOT_TOKEN，真實環境變數優先於 .env 檔。

設定允許清單

建立 ~/.claude/channels/discord/access.json，把你的 Discord 使用者 ID 加進 allowFrom：

{
  "allowFrom": ["你的_discord_user_id"]
}

只有 allowFrom 內的使用者 ID 發的 DM 會被處理，其餘一律忽略（fail-closed）。此檔每則訊息重讀，改允許清單免重啟。

安裝並啟動（二選一）

作為 npm 套件：

# 免安裝，一次性啟動
bunx claude-discord-daemon up

# 或全域安裝後用短別名 cdd
npm i -g claude-discord-daemon
cdd up

作為 Claude Code plugin：

/plugin marketplace add felimet/claude-discord-daemon
/plugin install claude-discord-daemon

Claude Code 會為 plugin 指令加上plugin 名前綴，所以實際指令是 /claude-discord-daemon:discord，用它驅動同一個 daemon：

/claude-discord-daemon:discord up | down | status | logs

它底層呼叫同一組 cdd CLI，cdd 不在 PATH 時退回 bunx claude-discord-daemon。

邀請 bot 並直接 DM

把 bot 邀請進任一你也在的 Discord 伺服器，然後直接 DM 這個 bot。

管理 daemon

cdd up       # 註冊登入時自動啟動的任務 + detached 啟動
cdd status   # 任務 / 行程 / log 尾巴
cdd logs     # 最後 40 行 log
cdd down     # 停止監督器 + 引擎

bin 名稱為 claude-discord-daemon 與 cdd，兩者相同。

設定參考

access.json 的額外選用鍵，沿用官方 plugin 的語意：

鍵	預設	作用
`ackReaction`	沙漏表情	收訊 ack 表情；設 `""` 停用
`textChunkLimit`	`2000`	單則訊息字元上限（上限 2000）
`chunkMode`	`newline`	分段策略：`newline`（段落感知）或 `length`（硬切）

環境變數除 DISCORD_BOT_TOKEN 外皆為選用，在 process 環境設定即可覆寫預設：

變數	預設	作用
`DISCORD_BOT_TOKEN`	（必要）	Discord bot token；未設則讀 `<state 目錄>/.env`
`DISCORD_STATE_DIR`	`~/.claude/channels/discord`	存放 `.env`、`access.json`、下載附件 `inbox/` 的目錄
`BOT_WS_DIR`	引擎所在目錄	`sessions.json`、`outbox/`、`bot.log` 的工作目錄
`CLAUDE_BIN`	`~/.local/bin/claude`	bridge spawn 的 `claude` 執行檔路徑
`BOT_PERMISSION_MODE`	`auto`	spawn run 的權限模式。`auto`：auto 分類器逐工具把關，唯讀放行，破壞性或自我修改的操作轉為 Discord 核准 / 拒絕按鈕。設 `default` 則再收緊，所有需審批的工具都走按鈕流程
`BOT_MODEL`	未設（帳號預設）	指定 Claude 模型，如 `claude-sonnet-5` / `haiku`，以降低成本
`BOT_TIMEOUT_MS`	`0`（不設限）	單次 run 的 wall-clock 總上限（ms）；`0` 表示不設限，支援長作業
`BOT_IDLE_TIMEOUT_MS`	`1800000`（30 分）	stream 事件靜默逾此毫秒數即視為卡死並砍掉
`BOT_PERM_PORT`	`49223`	權限核准 endpoint 的 loopback port（`perm-mcp.ts` 回呼）
`BOT_PERM_TIMEOUT_MS`	`600000`（10 分）	權限卡未回應多久後自動拒絕
`BOT_LOCK_PORT`	`49222`	單例 loopback 鎖 port

開新對話：傳一則整則訊息剛好是下列任一者（不分大小寫）的訊息，就會清掉已存 session，下一則訊息開啟全新的 claude -p session：

新對話   開新對話   重新開始   重開   清除對話   忘記
/new   /reset   reset   new chat

比對是嚴格的整則比對，容許尾端空白與標點，所以像 來開新對話討論 X 這種夾帶提及不會重置。重置時 bot 會以表情回應並確認。

注意事項

本橋接與官方 Discord plugin 用同一個 bot token 登入。作為服務執行前，必須先停用官方 plugin（claude plugin disable discord@claude-plugins-official），同一個 token 同時有兩個 gateway 登入會造成重複回覆。

Discord 輸入視為不可信，是 prompt-injection 的攻擊面。

來訊以 <channel source="discord" ...> 包裝，meta 在 tag 內、不可信的文字在標籤內容中；系統提示要求模型把它當成聊天文字，絕不當成修改設定或權限的指令。
只有 access.json 的 allowFrom 內的使用者能觸發任何 run，讀取失敗一律 fail-closed；按鈕點擊者（含權限核准按鈕）同樣經此允許清單重新驗證。
權限模式預設為 auto，永不使用 bypassPermissions；設 BOT_PERMISSION_MODE=default 可再收緊。
access 與配對僅由擁有者在 state 目錄管理，永不經由聊天。
bot token 不要提交版本控制。

實際應用面

適合想讓 Claude Code 在 Discord DM 裡隨時待命、又不想一直開著終端機的情境：預設下長時間作業不會因為跑得久被砍，只有 stream 靜默才算卡死；需要核准的操作在聊天裡按按鈕即可；也能收附件、回傳產出檔。限制是只支援 Windows 11，且只有允許清單內的使用者能觸發 run。

總覽

AI 與電腦視覺

自架服務與網路

物聯網與雲端

Agent 工具與整合

Claude Code Discord 常駐橋接

專案概述

核心功能

專案架構

技術棧

快速開始

設定參考

注意事項

實際應用面

相關連結

​專案概述

​核心功能

​專案架構

​技術棧

​快速開始

​設定參考

​注意事項

​實際應用面

​相關連結

專案概述

核心功能

專案架構

技術棧

快速開始

設定參考

注意事項

實際應用面

相關連結