> ## Documentation Index
> Fetch the complete documentation index at: https://felimet-hub.jmcores.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code Discord 常駐橋接

> Windows 常駐的 Discord 與 Claude Code 橋接：獨立行程持有 gateway，每則允許清單內的 DM 啟動一個 headless claude -p。

`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**

**discord.md · /claude-discord-daemon:discord 指令**

**skills**

**discord-presentation**

**SKILL.md · Discord 回覆的格式與 rich 輸出指引**

**.claude-plugin**

**plugin.json · plugin 資訊**

**marketplace.json · 單一 plugin 的 marketplace**

**videos**

**demo.gif · 簡單測試展示**

**demo.mp4 · 完整畫質版本**

## 技術棧

* 執行環境：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

## 快速開始

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

**1. 寫入 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` 檔。

**2. 設定允許清單**

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

```json theme={null}
{
  "allowFrom": ["你的_discord_user_id"]
}
```

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

**3. 安裝並啟動（二選一）**

作為 npm 套件：

```powershell theme={null}
# 免安裝，一次性啟動
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`。

**4. 邀請 bot 並直接 DM**

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

**5. 管理 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 會以表情回應並確認。

## 注意事項

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

> [!WARNING]
>
> 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。

## 相關連結

* GitHub：[felimet/claude-discord-daemon](https://github.com/felimet/claude-discord-daemon)
* Bun：[bun.sh](https://bun.sh)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.