Claude Code × Discord 連接完整指南

← 首頁

整理日期：2026-04-03  |  基於實際踩坑經驗整理

🔧 一、前置準備 ▼

需要的東西

  • Claude Code CLI — 需要 Max Plan 或 Teams Plan 才能使用
  • Discord Bot — 在 Discord Developer Portal 建立
  • Bun runtime — Discord Plugin 的執行環境
  • Discord MCP Plugin — Claude Code 的 Discord 橋接插件

Discord Bot 建立步驟

  1. 前往 Discord Developer Portal → 點擊 New Application
  2. 進入 Bot 頁面 → 設定 Bot 的使用者名稱
  3. 啟用 Message Content Intent
    ⚠ 非常重要

    不開啟 Message Content Intent，Bot 將無法讀取訊息內容，所有功能都會失效。

  4. 點擊 Reset Token → 複製 Token 並妥善保存（只會顯示一次）
  5. 前往 OAuth2 → URL Generator
    Scope 勾選：bot
    Bot Permissions 勾選： View Channels、Send Messages、Read Message History、Attach Files、Add Reactions
  6. 複製產生的 URL，用瀏覽器開啟，把 Bot 加入你的伺服器

安裝 Bun

curl -fsSL https://bun.sh/install | bash

⚙ 二、安裝與設定步驟 ▼

  1. 安裝 Discord Plugin 
    /plugin install discord@claude-plugins-official
  2. 設定 Bot Token 
    /discord:configure 你的Bot-Token

    也可以手動建立設定檔：~/.claude/channels/discord/.env

  3. 用 --channels 參數啟動 Claude Code 
    claude --channels plugin:discord:discord
    ⚠ 關鍵重點

    不加 --channels 參數，Discord 即時推送功能完全失效。這是最容易忽略的步驟。

  4. 在 Discord 私訊 Bot → 收到配對碼 → 回到終端機輸入： 
    /discord:access pair 配對碼
  5. 設定存取政策為白名單模式： 
    /discord:access policy allowlist
  6. 如需讓群組頻道也能互動： 
    /discord:access group add 頻道ID

💥 三、踩過的坑 ▼

坑 #1
⚠ --channels 參數不加 → 即時推送完全失效

症狀：Bot 在線但不會回應 Discord 訊息，完全沒反應。

根因：沒有 --channels plugin:discord:discord 參數，Claude Code 不會啟動 Discord channel listener。

解法：確保每次啟動都帶上參數，建議設 alias。

坑 #2
⚠ 兩個 Bot 進程互搶 Token → 反覆斷線

症狀：Bot 不斷上線下線，訊息時有時無。

根因：同一個 Bot Token 被兩個 Claude Code session 同時使用，Discord 會讓後連的踢掉前面的，反覆循環。

解法：確保同一時間只有一個 session 使用 --channels 啟動。

坑 #3
⚠ Plugin 被 disable（卸載殘留設定）

症狀：安裝過 Plugin 但指令無效、找不到 Discord 相關 skill。

根因：之前卸載過 Plugin，殘留的 disable 設定覆蓋了重新安裝。

解法：檢查 ~/.claude/settings.json 裡的 plugin 設定，移除 disable 標記後重啟。

坑 #4
⚠ Allowlist 間歇性失效（蓋螢幕/休眠）

症狀：原本能正常互動的頻道，蓋上螢幕或休眠一段時間後不再回應。

根因：macOS 休眠後網路連線中斷，Bot 重連時 session 狀態可能異常。

解法：設定防休眠措施（見第四節），或發現失效後重啟 session。

坑 #5
⚠ 斷線後可能需要重啟 Session

症狀：長時間斷線後，Bot 重連但不處理訊息。

根因：Claude Code session 內部狀態與 Discord 連線狀態不同步。

解法：直接結束 session 重新啟動 claude --channels plugin:discord:discord。

🛡 四、穩定度優化 ▼

防休眠腳本

防止 macOS 進入休眠狀態導致 Discord 斷線：

# 防止系統休眠（pmset）
sudo pmset -a disablesleep 1

# 或用 caffeinate 保持喚醒（推薦）
caffeinate -dims &

排程觸發（LaunchAgent）

用 macOS LaunchAgent 定時發送 Discord 訊息，確保連線維持：

# ~/Library/LaunchAgents/com.claude.discord.keepalive.plist
# 設定定時執行腳本，透過 Discord API 發送心跳訊息

同一 Session vs 新 Session 比較

面向同一 Session（不重啟）新 Session（重啟）
上下文保留完整對話歷史上下文歸零，需重新建立
記憶體長時間運行可能吃越來越多全新乾淨狀態
連線穩定度越久越容易出問題重連後通常穩定
適合場景持續性任務、需要上下文日常重新開始、修復斷線
建議每天至少重啟一次✓ 推薦每日早上重啟

✅ 五、目前最佳實踐 ▼

啟動指令

claude --channels plugin:discord:discord

建議設定 alias 簡化操作：

alias claude-dc='claude --channels plugin:discord:discord'

日常流程

  1. 啟動 claude-dc（或完整指令）
  2. 在 Discord 傳訊息給 Bot 或在指定頻道 @Bot
  3. Claude 會自動回覆訊息或用 emoji react
  4. 長任務完成後 Claude 會主動發新訊息通知（push notification）

可用工具一覽

reply
回覆 Discord 訊息，支援附檔（files 參數）
react
對訊息加 emoji 反應
edit_message
編輯已發送的訊息（不觸發推送通知）
fetch_messages
拉取頻道歷史訊息
download_attachment
下載訊息中的附件檔案

進度回報規則

📋 建議的回報時機
  • 任務開始時 — 簡述要做什麼、預計步驟
  • 完成一個階段 — 例如「已完成分析，開始寫程式」
  • 遇到錯誤時 — 說明錯誤內容與修復嘗試
  • 任務完成 — 回報結果與產出
  • 長時間處理 — 超過 3 分鐘主動發狀態更新

❓ 六、未解決的問題 ▼

← 回到研究報告索引