總覽

ClaudeBot 是什麼？

ClaudeBot 不是 Claude 的轉發器。它是一個建立在 Telegram 上的平台，讓你從手機指揮 AI 操控程式碼、管理專案、執行自動化任務。

它能做什麼？

• 從手機送出程式碼修改指令，AI 直接改你的 codebase
• 多 AI 後端切換（Claude、Gemini）
• 插件零成本運行（骰子、計算機、提醒不需 AI）
• 語音辨識：講話就能寫程式
• 佇列系統：多人多 Bot 安全共用
• Session 記憶：對話不會斷

架構概覽

技術棧

Telegraf v4（Telegram Bot 框架）+ TypeScript（嚴格模式）+ Claude CLI / Gemini CLI + zod（驗證）+ bcrypt（認證）

適合誰？

有自己 server 的開發者、想用手機操控程式碼的工程師、需要一個可擴充 Telegram Bot 平台的團隊。

快速開始

五分鐘上手

環境需求

• Node.js 20+
• Claude CLI（已登入）
• Git
• Telegram Bot Token（從 @BotFather 取得）

步驟一：Clone 與安裝

git clone https://github.com/Jeffrey0117/ClaudeBot.git
cd ClaudeBot && npm install

步驟二：設定環境變數

複製 .env.example 為 .env，填入必要設定：

# Telegram Bot Token (from @BotFather)
BOT_TOKEN=your_bot_token_here

# Login password
PASSWORD=your_password

# Allowed project paths (comma-separated)
ALLOWED_PROJECTS=/home/user/project1,/home/user/project2

步驟三：啟動

npm run dev

步驟四：登入

在 Telegram 找到你的 Bot，發送 /start，輸入密碼登入。

步驟五：第一個請求

用 /projects 選擇專案，然後直接發送文字給 AI。

多 AI 後端

Claude、Gemini，自由切換

ClaudeBot 支援多個 AI 後端，你可以根據任務需求選擇最合適的模型。

支援的後端

切換模型

使用 /model 指令，會顯示 inline 按鈕讓你選擇。

/model
# Inline buttons appear: [Claude Sonnet] [Gemini Flash] [Auto]

Auto Router

設定 auto 模式時，ClaudeBot 會根據訊息複雜度自動分流：Tier 1（簡單問答）→ Gemini Flash、Tier 2（一般任務）→ Gemini Pro、Tier 3（程式碼任務）→ Claude Sonnet。

佇列系統

序列執行，安全可靠

Claude CLI 一次只能運行一個進程。ClaudeBot 的佇列系統確保所有請求依序處理，不會互相干擾。

運作方式

每個專案有獨立佇列。當 AI 正在執行時，新的訊息會自動排隊。佇列支援 prompt merging：等待中的多條訊息會合併為一個請求。

跨 Bot 檔案鎖

多個 Bot 共用同一個專案時，.claudebot.lock 檔案確保只有一個 Bot 能執行 AI 操作。鎖會在 5 分鐘後自動過期。

{
  "botId": "abc123",
  "pid": 12345,
  "timestamp": 1709000000000
}

Prompt Merging

在佇列等待期間發送的多條訊息會被合併為單一請求，減少 API 呼叫次數，節省時間。

Session 與記憶

對話延續，不怕忘記

ClaudeBot 使用 Claude CLI 的 --resume 機制保持對話上下文。每個 Bot 實例、每個專案都有獨立的 Session。

Session ID

Session ID 儲存在 .sessions.json，key 格式為 ${BOT_ID}:${projectPath}。BOT_ID 是 bot token 的最後 6 碼，確保多 Bot 不會互相覆蓋。

{
  "abc123:/home/user/project1": "session_uuid_here",
  "def456:/home/user/project2": "another_session_uuid"
}

自動過期

Session 在 30 分鐘沒有活動後自動過期，下次對話會開啟新 session。使用 /new 可以手動開啟新對話。

Context Preservation

短回覆（15 字以內）或肯定回覆（好、OK、可以...）會自動注入前次 AI 回應作為參考，防止 context 壓縮後的「失憶」。

/context 指令

使用 /context 可以 pin/unpin 額外檔案到對話中，或查看/清除目前的上下文。

# Pin a file to conversation context
/context pin src/utils/helpers.ts

# View current pinned files
/context

# Clear all context
/context clear

插件系統

零 AI 成本，無限擴展

ClaudeBot 的插件系統讓你用簡單的 TypeScript 檔案擴展功能。插件不經過 AI，直接執行，零成本。

Plugin 介面

每個插件匯出一個 Plugin 物件，包含 name、description、commands。

import type { Plugin } from '../../types/plugin.js'
import type { BotContext } from '../../types/context.js'

async function myCommand(ctx: BotContext): Promise<void> {
  await ctx.reply('Hello from plugin!')
}

const plugin: Plugin = {
  name: 'my-plugin',
  description: 'My custom plugin',
  commands: [
    { name: 'hello', description: 'Say hello', handler: myCommand },
  ],
}

export default plugin

熱重載

使用 /reload 指令可以不重啟 Bot 就更新插件程式碼。

Output Hook & Message Hook

Output Hook 攔截 AI 回應做後處理（如 mdfix 修正 Markdown 格式）。Message Hook 攔截用戶訊息做前處理。

const plugin: Plugin = {
  name: 'mdfix',
  description: 'Fix markdown formatting',
  commands: [],
  outputHook: (text: string) => {
    return text.replace(/```(\w+)\n/g, '```$1\n')
  },
}

Plugin Store

使用 /store 瀏覽可用插件，/install 安裝，/uninstall 移除。插件從 GitHub 上的 claudebot-plugins 倉庫下載。

# Browse available plugins
/store

# Install a plugin
/install dice

# Uninstall a plugin
/uninstall dice

# Hot-reload after changes
/reload

語音辨識

說話就能寫程式

ClaudeBot 整合 Sherpa-ONNX 本地語音辨識，不需要雲端 API，保護隱私。

辨識流程

LLM 智慧修正

辨識完成後，使用 Gemini 修正語音辨識的錯字和語句，提高準確度。

Hotword 注入

專案名稱會自動加入辨識詞庫，提高專有名詞的辨識率。

開關設定

使用 /asr 指令開啟或關閉語音辨識功能。

# Toggle voice recognition
/asr

# Then send a voice message — it will be transcribed and sent to AI

互動式 UI

不只是文字對話

ClaudeBot 自動偵測 AI 回應中的互動元素，轉換為 Telegram 原生按鈕，提升操作體驗。

Choice Detector

當 AI 回覆包含數字列表和選擇提示（哪個？要選哪個？）時，自動生成 inline 按鈕。

AI: 有三種方案：
1. 使用 Express 框架
2. 使用 Fastify 框架
3. 使用 Koa 框架
你想選哪個？

→ ClaudeBot 自動生成 [1] [2] [3] 按鈕

確認按鈕

AI 回覆「要繼續嗎？」等確認問句時，自動顯示 ✓ 和 ✗ 按鈕。

Follow-up 建議

AI 回答後自動推薦相關追問，點擊即可繼續對話。

Steer 模式

以 ! 開頭的訊息會取消當前 AI 任務並立即發送新指令，用於緊急切換。

# AI is currently running a long task...
# Send this to cancel and redirect:
!停，改去修 login 的 bug

多 Bot 架構

不同用途，獨立運行

ClaudeBot 支援同時運行多個 Bot 實例，各自擁有獨立的 token、插件設定和 session。

為什麼多 Bot？

不同用途分開管理：開發 Bot 用 Claude，生活 Bot 用 Gemini，團隊 Bot 共享專案。

設定方式

在專案根目錄建立 .env.bot2、.env.bot3... 等檔案，每個檔案設定不同的 BOT_TOKEN。Launcher 會自動偵測並啟動所有 Bot。

# Second bot instance
BOT_TOKEN=second_bot_token
PASSWORD=another_password
ALLOWED_PROJECTS=/home/user/personal
PLUGINS=dice,reminder,calc
DEFAULT_MODEL=gemini-flash

Launcher 進程管理

Launcher 包含 watchdog 監控、crash loop 防護（連續 crash 5 次後等待 60 秒）、自動重啟。

/newbot 指令

使用 /newbot 可以快速產生新的 .env 檔案模板。

Sleep Prevention

設定 PREVENT_SLEEP=true 可防止系統進入睡眠，確保 Bot 24/7 運行。

自動提交

AI 改動，自動版控

啟用 AUTO_COMMIT=true 後，每次 AI 完成程式碼修改，ClaudeBot 會自動執行 git add、commit 和 push。

啟用方式

在 .env 中設定 AUTO_COMMIT=true。

AUTO_COMMIT=true

執行流程

安全機制

自動遵守 .gitignore、過濾可能包含 secrets 的檔案（.env、credentials 等）。

Web Dashboard

視覺化即時監控

ClaudeBot 內建 Express + WebSocket 的 Web Dashboard，提供即時 Bot 狀態監控。

Heartbeat

每 2 秒更新 Bot 狀態，包含目前專案、佇列長度、執行中的任務。

Command Reader

從 Dashboard 直接送指令給 Bot，不需要打開 Telegram。

Runner Tracker

追蹤目前正在執行的 AI 任務，顯示執行時間和狀態。

# Enable dashboard
DASHBOARD_PORT=3000
DASHBOARD_TOKEN=your_secret_token

指令大全

完整指令表

以下是 ClaudeBot 所有內建指令的完整參考。

專案管理

AI 控制

遠端操控

待辦 & 靈感

Bot 管理

Plugin Store

進階用法

/run

/run <command> — 在選定專案目錄執行 shell 指令。支援任何命令，結果直接回傳 Telegram。

/run git status
/run npm test
/run ls -la src/

/chat

/chat 或 @chat — 輕量聊天模式，不載入專案上下文，適合快速問答。

/fav

/fav — 書籤功能，快速切換常用專案。