Tutorial
Claude Code 串接 Telegram 完整教學
從零開始打造你的 AI 助理 — 包含所有踩過的坑和解決方案
2026-05-05 · 點點滴滴喵兒貴
0. 前言：為什麼要串接 Claude Code + Telegram
想像一下：你在通勤的捷運上，掏出手機打開 Telegram，直接用語音跟 Claude 對話。它能幫你寫程式碼、分析文件、規劃行程、甚至幫你查資料。不需要打開電腦，不需要瀏覽器 —— 你的 AI 助理就住在你最常用的通訊軟體裡。
Claude Code 本身是一個強大的 CLI 工具，但它的 Telegram plugin 讓它從「只能坐在電腦前用」變成「隨時隨地可用」。這篇教學會帶你從零開始完成整個串接，包含我自己踩過的所有坑。
串接完成後，你可以：
- 用手機隨時跟 Claude 對話（文字 + 語音）
- 在群組中 @bot 讓它參與討論
- 傳送檔案給它分析
- 把它當作 24/7 不斷線的私人 AI 助理
1. 前置準備
在開始之前，確認你有以下東西：
一台主機
Linux 或 Mac（或雲端 VM）。需要 24/7 開機才能持續接收 Telegram 訊息。
Claude 帳號（二擇一）
方式一：訂閱帳號登入 — 用 claude.ai 的付費訂閱帳號直接登入，月付固定費用，適合一般使用。
方式二：API Key — 到
console.anthropic.com 申請，按量計費，適合重度使用或自動化場景。
Telegram 帳號
需要能建立 Bot。如果你有 Telegram 帳號就行。
基本終端機操力
知道怎麼 ssh、執行指令、編輯設定檔。
Tip：推薦的主機選擇
如果你沒有一台 24/7 開機的主機，推薦用一台便宜的 VPS（例如 Linode 最低方案 $5/月），或一台放在家裡的 Mac mini / Raspberry Pi。重點是它要能持續運行。
2. 步驟一：安裝 Bun
Bun 是一個高效能的 JavaScript runtime，Claude Code 的 Telegram plugin 依賴它來運行。必須先安裝 Bun，才能正常使用 Telegram plugin。
安裝指令（Mac / Linux 通用）
curl -fsSL https://bun.sh/install | bash
安裝完成後，重新載入你的 shell 設定：
source ~/.zshrc
source ~/.bashrc
驗證安裝
bun --version
坑：Bun 必須預先安裝
Claude Code 的 Telegram plugin 在啟動時會呼叫 Bun 來執行相關腳本。如果系統上沒有安裝 Bun，plugin 會靜默失敗 —— 不會報錯，就是不動。這是最常見的「bot 沒回應」原因之一。
坑（Mac）：不能用 root 安裝
在 Mac 上，絕對不要用 sudo 執行安裝指令。Bun 的安裝腳本會把二進位檔放到 ~/.bun/bin/，如果用 root 執行，路徑會跑到 root 的 home 目錄，之後普通用戶就找不到 bun。
坑（Mac）：系統權限請求
安裝過程中 macOS 可能會跳出安全性權限請求對話框（例如「允許終端機存取下載項目」）。一定要點「允許」，否則安裝會失敗但不會顯示明確的錯誤訊息。
Tip：確認 PATH 設定
如果安裝完 bun --version 顯示 command not found，檢查你的 shell 設定檔（~/.zshrc 或 ~/.bashrc）裡有沒有這行：
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"
3. 步驟二：安裝 Claude Code
安裝 Claude Code CLI
npm install -g @anthropic-ai/claude-code
坑（Mac）：不能用 sudo 安裝
跟 Bun 一樣，不要用 sudo npm install -g。如果遇到權限問題，正確做法是修改 npm 的全域安裝路徑：
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH="$HOME/.npm-global/bin:$PATH"
source ~/.zshrc
npm install -g @anthropic-ai/claude-code
設定認證（二擇一）
方式一：用訂閱帳號登入（推薦新手）
如果你有 Claude Pro / Team / Max 訂閱，可以直接用帳號登入，不需要 API Key：
claude
訂閱帳號 vs API Key 怎麼選？
訂閱帳號：月付固定費用（Pro $20/月），適合一般使用，不用擔心用量。
API Key：按量計費，適合重度自動化、需要精確控制成本、或企業部署的場景。
建議：先用訂閱帳號開始，等用量穩定後再評估是否轉 API。
方式二：用 API Key
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxx"
為了讓每次開機都生效，把它寫入 shell 設定檔：
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-你的key"' >> ~/.zshrc
source ~/.zshrc
安全提醒
API Key 等同於你的信用卡。不要把它放到公開的 git repo 或分享給別人。如果你用雲端主機，確認 ~/.zshrc 的檔案權限是 600（只有自己能讀）。
驗證安裝
claude --version
claude -p "說 hello"
4. 步驟三：建立 Telegram Bot
在 Telegram 中建立一個 Bot，取得 Bot Token。
4.1 建立 Bot
- 在 Telegram 中搜尋 @BotFather
- 點開對話，輸入
/newbot
- BotFather 會問你 bot 的顯示名稱（可以是中文，例如「阿貴的 AI 助理」）
- 接著問username（必須英文、底線結尾
_bot，例如 agui_ai_bot）
- 完成後，BotFather 會給你一段 Bot Token，格式像這樣：
7123456789:AAF1x2y3z4a5b6c7d8e9f0-AbCdEfGhIjKlM
Tip：保管好你的 Bot Token
Bot Token 就像是你 bot 的密碼。拿到 token 的人可以控制你的 bot。妥善保管，不要公開分享。
4.2 設定 Group Privacy（重要！）
這是最容易被忽略的設定。預設情況下，Bot 在群組中只能收到以下訊息：
- 以
/ 開頭的 command
- @mention 到 bot 的訊息
- 回覆 bot 先前訊息的回覆
如果你想讓 bot 收到群組內所有訊息（例如不用每次都 @mention），需要關閉 Group Privacy：
- 跟 @BotFather 對話
- 輸入
/setprivacy
- 選擇你剛建立的 bot
- 選擇 Disable
你：/setprivacy
BotFather：Choose a bot to change group messages settings.
你：@your_bot_username
BotFather：'Disable' - your bot will receive all messages in groups.
'Enable' - your bot will only receive messages that...
你：Disable
BotFather：Success! The new status is: DISABLED.
坑：Group Privacy 必須在加入群組「之前」設定
如果你的 bot 已經在群組裡了，改了 privacy 設定之後，需要把 bot 移出群組再重新加入，新的設定才會生效。這是 Telegram Bot API 的已知行為。
4.3 取得你的 Chat ID
Claude Code 的 Telegram plugin 需要知道哪些 chat_id 被允許互動（安全措施，防止陌生人用你的 bot 消耗你的 API 額度）。
取得個人 Chat ID 的方法：
curl -s "https://api.telegram.org/bot你的TOKEN/getUpdates" | python3 -m json.tool
Tip：群組的 Chat ID
群組的 chat_id 是負數（例如 -1001234567890）。用同樣的 getUpdates 方法，在把 bot 加入群組後發一則訊息就能看到。
5. 步驟四：設定 Claude Code Telegram Plugin
5.1 設定 Bot Token
在 Claude Code 的 CLI 中，使用設定指令來配置 Telegram plugin：
claude
/telegram:configure
按照提示貼上你的 Bot Token。
5.2 設定允許的 Chat ID
為了安全，你需要設定哪些 chat_id 可以跟 bot 互動：
/telegram:access
設定好之後，只有在允許清單中的 chat_id 發來的訊息，bot 才會回應。
5.3 啟動 Claude Code daemon 模式
要讓 bot 持續運行，需要以 daemon 模式啟動 Claude Code：
claude --daemon
nohup claude --daemon &> ~/claude-daemon.log &
tail -f ~/claude-daemon.log
5.4 驗證
在 Telegram 中對你的 bot 發一則訊息（例如「你好」），如果一切設定正確，bot 應該在幾秒內回覆。
成功指標
如果 bot 有回覆你的訊息，恭喜！基本串接已經完成。接下來可以進入進階設定。
如果 bot 沒回應
最常見的原因（按照排查順序）：
1. Bun 沒裝 → 執行 bun --version 確認
2. Bot Token 打錯 → 重新檢查
3. Chat ID 不在允許清單 → 檢查 access 設定
4. Claude Code 沒有在 daemon 模式運行 → 檢查 process
6. 步驟五：進階設定
6.1 語音訊息自動轉文字（Whisper）
如果你想用語音跟 bot 對話，需要設定語音轉文字。Claude Code 的 Telegram plugin 支援接收語音訊息，並透過 Whisper 模型自動轉成文字後處理。
pip install faster-whisper
export OPENAI_API_KEY="sk-..."
Tip：本地 Whisper vs. API
如果你的主機有 GPU，用本地 Whisper 省錢又快。沒 GPU 的話用 OpenAI Whisper API 比較實際，一分鐘音訊大約 $0.006。
6.2 群組支援
要在群組中使用 bot：
- 確認已經關閉 Group Privacy（步驟三有教）
- 把 bot 加入群組
- 把群組的 chat_id（負數）加到允許清單中
-1001234567890
/telegram:access
6.3 自動啟動（systemd / pm2）
你不會想每次重開機都手動啟動 bot。以下是兩種常見的自動啟動方案：
方案 A：systemd（Linux 推薦）
sudo nano /etc/systemd/system/claude-telegram.service
[Unit]
Description=Claude Code Telegram Bot
After=network.target
[Service]
Type=simple
User=你的用戶名
Environment=ANTHROPIC_API_KEY=sk-ant-api03-你的key
Environment=HOME=/home/你的用戶名
ExecStart=/home/你的用戶名/.npm-global/bin/claude --daemon
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable claude-telegram
sudo systemctl start claude-telegram
sudo systemctl status claude-telegram
journalctl -u claude-telegram -f
方案 B：pm2（Mac / Linux 都適用）
npm install -g pm2
pm2 start "claude --daemon" --name claude-telegram
pm2 startup
pm2 save
pm2 status
pm2 logs claude-telegram
pm2 restart claude-telegram
6.4 CLAUDE.md 自訂指令
你可以在專案目錄或 home 目錄建立 CLAUDE.md（或 ~/.claude/CLAUDE.md），自訂 Claude 的行為：
# 我的偏好設定
- 請用繁體中文回覆
- 回覆要簡潔有力，不要冗長
- 程式碼請加上註解
- 如果我問的問題不夠明確，請追問而不是猜測
Tip：CLAUDE.md 的優先順序
Claude Code 會依序讀取：專案目錄的 CLAUDE.md > ~/.claude/CLAUDE.md。專案層級的設定會覆蓋全域設定。Telegram 對話預設使用全域的 ~/.claude/CLAUDE.md。
7. 常見問題排除
Bot 沒有回應
bun --version
ps aux | grep claude
curl -s "https://api.telegram.org/bot你的TOKEN/getMe"
權限錯誤（Mac）
EACCES / Permission denied
Mac 上最常見的權限問題就是用了 sudo 安裝。解法：
1. 刪除用 root 安裝的東西：sudo rm -rf /usr/local/lib/node_modules/@anthropic-ai
2. 設定 npm 全域路徑到 home 目錄（步驟二有教）
3. 用普通用戶重新安裝
Bun not found
ls ~/.bun/bin/bun
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"
API Rate Limit
語音訊息無法辨識
pip show faster-whisper
ffmpeg -version
brew install ffmpeg
sudo apt install ffmpeg
8. 結語
恭喜你完成了 Claude Code + Telegram 的串接！你現在擁有了一個 24/7 運行的私人 AI 助理，隨時隨地都能透過 Telegram 跟它互動。
回顧一下我們做了什麼：
安裝 Bun → 安裝 Claude Code → 建立 Telegram Bot → 設定 Plugin → 進階配置。整個過程大約 30-60 分鐘（不含踩坑的時間）。
一些使用建議：
- 定期檢查 API 用量 —— 尤其是加了群組之後，多人使用會快速消耗額度
- 善用 CLAUDE.md —— 把你的常用偏好寫進去，bot 會記住
- 監控 daemon 狀態 —— 偶爾看一下 log 確認沒有異常
- 保持更新 —— Claude Code 更新頻繁，新版本通常修了很多 bug
npm update -g @anthropic-ai/claude-code
如果你覺得這篇教學有幫助，歡迎分享給也想串接的朋友。有任何問題也可以在 Telegram 上找我討論。
Happy hacking!