CCBot：用 Telegram 遠端操控 Claude Code 的開源利器

本篇文章更新時間：2026/02/22
如有資訊過時或語誤之處，歡迎使用 Contact 功能通知或向一介資男的 LINE 社群反應。
如果本站內容對你有幫助，歡迎贊助支持。

你是否曾遇過這樣的情境：Claude Code 正在終端機裡幫你寫程式、跑測試，但你卻不得不離開電腦？或者你想在通勤途中用手機繼續監控 AI 編程的進度、甚至即時下達指令？CCBot 這款開源工具正是為了解決這個痛點而生。

CCBot 是一款基於 Telegram 的機器人，它能讓你透過 Telegram 遠端監控與操作在 tmux 中運行的 Claude Code 會話。不同於使用 Claude Code SDK 建立獨立 API 會話的方式，CCBot 直接操作 tmux 視窗——這代表你可以在桌面終端機和手機 Telegram 之間無縫切換，回到 tmux 後所有的 scrollback 和上下文都完好保留。

內容目錄

1 CCBot 是什麼？
2 核心特色功能
3 系統需求與前置條件
4 安裝步驟
- 4.1 方法一：使用 uv 或 pipx 安裝（推薦）
- 4.2 方法二：從原始碼安裝
5 設定 Telegram Bot
6 環境變數設定
- 6.1 可選環境變數
7 設定 Hook（推薦）
- 7.1 自動安裝 Hook
- 7.2 手動安裝 Hook
8 啟動與使用
9 手動在 tmux 中執行 Claude Code
10 架構設計與原始碼結構
11 資料儲存位置
12 主要依賴套件
13 實用技巧與注意事項
14 結語
- 14.1 相關文章

CCBot 是什麼？

CCBot（全名 Claude Code Bot）是由開發者 six-ddc 發起的開源專案，採用 MIT 授權，以 Python 撰寫。它的核心理念是作為 tmux 之上的「薄控制層（thin control layer）」，讓使用者能夠：

從任何裝置透過 Telegram 遠端監控 Claude Code 的即時輸出
透過 Telegram 訊息下達指令給正在運行的 Claude Code 會話
管理多個 Claude Code 會話，每個 Telegram 話題對應一個獨立的 tmux 視窗
接收 AI 回應、工具呼叫結果、思考過程等即時通知

截至撰文時，該專案在 GitHub 上已獲得 87 顆星、32 個 Fork，並有 12 位貢獻者參與開發。

核心特色功能

話題（Topic）式會話管理

CCBot 的核心設計原則是「一個話題 = 一個 tmux 視窗 = 一個 Claude Code 會話」。Telegram 群組中的每個話題（Topic）都被綁定到一個對應的 tmux 視窗。你可以：

透過建立新的 Telegram 話題來建立新會話
使用內建的目錄瀏覽器 UI 來選擇專案資料夾
關閉或刪除 Telegram 話題時自動終止對應的 tmux 視窗

即時通知系統

CCBot 每 2 秒（可調整）輪詢 Claude Code 的 JSONL 輸出檔案，並推送以下類型的通知到對應的 Telegram 話題：

AI 助理回應：Claude Code 產出的文字回覆
思考過程：以可展開的引用區塊顯示 Claude 的推理過程
工具呼叫與結果：顯示工具使用摘要與統計資訊
本地指令輸出：以 ❯ command_name 前綴呈現

互動式 UI 元件

CCBot 不只是單向的通知推播，它還提供了互動式的 Inline Keyboard，讓你可以在 Telegram 上直接操作：

AskUserQuestion：當 Claude Code 詢問使用者問題時，直接在 Telegram 上回答
ExitPlanMode：審核並批准 Claude Code 的計劃模式
權限提示（Permission Prompts）：批准或拒絕 Claude Code 的工具使用請求
目錄瀏覽器：建立新會話時的專案資料夾選擇介面

Slash 指令透傳

CCBot 支援將常用的 Claude Code slash 指令透過 tmux 按鍵模擬直接轉發：

/clear：清除對話歷史
/compact：壓縮對話上下文
/cost：顯示 Token 用量與費用統計
/help：顯示 Claude Code 說明
/memory：編輯 CLAUDE.md

此外，任何 CCBot 無法辨識的 /command 格式也會被直接轉發，例如 /review、/doctor、/init 等。

持久化狀態管理

CCBot 的所有狀態都透過 JSON 檔案持久化儲存，包含話題綁定、視窗狀態、訊息讀取偏移量等。這代表即使 CCBot 重啟，話題與 tmux 視窗的綁定關係依然存在，監控也會自動恢復。

系統需求與前置條件

在安裝 CCBot 之前，請確保你的系統滿足以下條件：

Python ≥ 3.12
tmux：必須已安裝並加入 PATH
Claude Code CLI：claude 指令必須可用
Telegram 帳號：用於建立 Bot 和操作

安裝步驟

方法一：使用 uv 或 pipx 安裝（推薦）

這是最簡單的安裝方式，一行指令即可完成：

# 使用 uv（推薦）
uv tool install git+https://github.com/six-ddc/ccbot.git

# 或使用 pipx
pipx install git+https://github.com/six-ddc/ccbot.git

方法二：從原始碼安裝

如果你想要修改原始碼或進行開發，可以從 GitHub 複製整個專案：

git clone https://github.com/six-ddc/ccbot.git
cd ccbot
uv sync

設定 Telegram Bot

CCBot 需要一個 Telegram Bot 作為溝通橋樑，以下是建立步驟：

步驟一：建立 Bot

在 Telegram 中搜尋 @BotFather 並開啟對話
發送 /newbot 指令
依照提示輸入 Bot 的顯示名稱和使用者名稱
BotFather 會回傳一個 Bot Token，請妥善保存

步驟二：啟用 Threaded Mode（話題模式）

CCBot 依賴 Telegram 的話題功能來管理多個 Claude Code 會話，因此必須啟用 Threaded Mode：

開啟 @BotFather 的 mini-app
選擇你剛建立的 Bot
進入 Settings > Bot Settings
啟用 Threaded Mode

步驟三：取得你的 Telegram User ID

你需要知道自己的 Telegram User ID 來設定白名單。可以透過 @userinfobot 或 @raw_data_bot 等機器人來查詢。

環境變數設定

建立設定檔 ~/.ccbot/.env：

mkdir -p ~/.ccbot

cat > ~/.ccbot/.env

可選環境變數

變數名稱	說明	預設值
`CCBOT_DIR`	CCBot 設定檔目錄	`~/.ccbot`
`TMUX_SESSION_NAME`	tmux session 名稱	`ccbot`
`CLAUDE_COMMAND`	啟動 Claude Code 的指令	`claude`
`MONITOR_POLL_INTERVAL`	輪詢間隔（秒）	`2.0`

⚠️ VPS / 無互動環境注意事項：如果你在 VPS 上執行 CCBot，且不需要互動式權限確認，可以設定：

CLAUDE_COMMAND=IS_SANDBOX=1 claude --dangerously-skip-permissions

請注意，--dangerously-skip-permissions 會跳過所有安全性確認，僅建議在受控環境中使用。

設定 Hook（推薦）

Hook 機制是 CCBot 實現「自動偵測 tmux 視窗與 Claude Code 會話對應關係」的關鍵功能。當 Claude Code 啟動時，Hook 會將對應資訊寫入 session_map.json，讓 CCBot 能自動追蹤會話，即使執行了 /clear 也不會中斷追蹤。

自動安裝 Hook

ccbot hook --install

手動安裝 Hook

如果你偏好手動設定，將以下內容加入 ~/.claude/settings.json：

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "ccbot hook",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

啟動與使用

啟動 CCBot

# 透過 uv tool / pipx 安裝的情況
ccbot

# 從原始碼執行
uv run ccbot

CCBot 指令一覽

指令	說明
`/start`	顯示歡迎訊息
`/history`	瀏覽當前話題的訊息歷史（支援分頁導覽）
`/screenshot`	擷取終端機畫面截圖（支援 ANSI 色彩）
`/esc`	發送 Escape 鍵以中斷 Claude Code

典型工作流程

以下是使用 CCBot 的完整操作流程：

建立 Telegram 群組話題：在已啟用話題模式的群組中，建立一個新話題
發送訊息：在新話題中發送任意訊息（例如你想讓 Claude Code 完成的任務描述）
選擇專案目錄：CCBot 會自動彈出目錄瀏覽器 UI，讓你選擇要在哪個專案資料夾中啟動 Claude Code
自動建立會話：系統自動建立 tmux 視窗、啟動 claude，並將你的訊息轉發給它
持續互動：在話題中直接發送文字即可與 Claude Code 對話，所有回應都會即時推送通知
結束會話：關閉或刪除 Telegram 話題，對應的 tmux 視窗也會自動終止

手動在 tmux 中執行 Claude Code

除了透過 Telegram 建立會話之外，你也可以手動在 tmux 中啟動 Claude Code：

# 連接到 ccbot 的 tmux session
tmux attach -t ccbot

# 建立新視窗並指定工作目錄
tmux new-window -n myproject -c ~/Code/myproject

# 啟動 Claude Code
claude

請注意，手動建立的視窗必須位於 ccbot 這個 tmux session 中（可透過 TMUX_SESSION_NAME 環境變數自訂名稱）。啟動 Claude Code 後，Hook 會自動將會話資訊註冊到 session_map.json。

架構設計與原始碼結構

CCBot 的原始碼結構清晰，模組職責分明。以下是主要檔案的功能說明：

核心模組（src/ccbot/）

檔案	功能說明
`main.py`	程式進入點
`bot.py`	Telegram Bot 設定與指令路由
`config.py`	環境變數與設定管理
`session.py`	會話與狀態管理
`session_monitor.py`	JSONL 檔案輪詢與通知推送
`tmux_manager.py`	tmux 視窗管理
`transcript_parser.py`	Claude Code JSONL 輸出解析
`terminal_parser.py`	終端機 UI 解析
`telegram_sender.py`	HTTP 訊息傳送與自動分割（4096 字元限制）
`markdown_v2.py`	Markdown 轉 Telegram MarkdownV2 格式
`screenshot.py`	終端機畫面轉 PNG 截圖
`hook.py`	Claude Code SessionStart Hook 處理
`monitor_state.py`	監控狀態持久化
`utils.py`	原子化 JSON 讀寫、JSONL 工具函式

Handler 模組（src/ccbot/handlers/）

Handler 目錄包含各種 UI 互動元件和訊息處理邏輯，如目錄瀏覽器、歷史訊息分頁、互動式 UI（AskUser、ExitPlan、權限提示）、訊息佇列與 Worker、回應建構器、狀態輪詢等。

設計原則

話題為中心（Topic-centric）：每個話題綁定一個 tmux 視窗，話題即會話列表
Window ID 為索引鍵：內部狀態以 tmux window ID（如 @0、@12）為 key，而非視窗名稱，多個視窗可共用同一目錄
Hook 驅動追蹤：透過 Claude Code 的 SessionStart Hook 寫入 session_map.json，監控器輪詢後自動偵測
工具呼叫配對：使用 tool_use_id 跨輪詢週期追蹤，結果會回編到原始工具呼叫的 Telegram 訊息
MarkdownV2 + 降級：訊息透過 telegramify-markdown 轉換，解析失敗時自動降級為純文字
完整解析、分段發送：解析時保留完整內容，發送層依 Telegram 4096 字元限制自動分割

資料儲存位置

CCBot 使用以下檔案來持久化狀態：

檔案路徑	用途
`$CCBOT_DIR/state.json`	話題綁定、視窗狀態、顯示名稱、各使用者的訊息讀取偏移量
`$CCBOT_DIR/session_map.json`	Hook 產生的 tmux window 與 Claude Code session 對應表
`$CCBOT_DIR/monitor_state.json`	各 session 的監控位元組偏移量（避免重複通知）
`~/.claude/projects/`	Claude Code 的 session 資料（唯讀）

主要依賴套件

CCBot 基於以下 Python 套件構建：

套件	用途
`python-telegram-bot` ≥ 21.0	Telegram Bot API 整合（含 rate limiter）
`libtmux` ≥ 0.37.0	tmux 程式化控制
`python-dotenv` ≥ 1.0.0	環境變數管理
`httpx` ≥ 0.27.0	非同步 HTTP 客戶端
`Pillow` ≥ 10.0.0	圖片處理（終端截圖轉 PNG）
`telegramify-markdown` ≥ 0.5.0	Markdown 轉 Telegram MarkdownV2
`aiofiles` ≥ 24.0.0	非同步檔案操作

實用技巧與注意事項

建議使用 tmux 常駐管理

CCBot 本身也建議透過 tmux 或 systemd 來常駐運行，確保它在背景持續監控：

# 建立一個獨立的 tmux session 來運行 ccbot
tmux new-session -d -s ccbot-runner 'ccbot'

多使用者支援

ALLOWED_USERS 環境變數支援以逗號分隔多個 Telegram User ID，讓團隊成員都能透過同一個 Bot 操作各自的 Claude Code 會話。每個使用者都有獨立的訊息佇列和 Rate Limiting 機制。

安全性考量

務必設定 ALLOWED_USERS 白名單，避免未授權的使用者操控你的 Claude Code 會話
Bot Token 請妥善保管，不要提交到版本控制系統中
在 VPS 上使用 --dangerously-skip-permissions 時要特別謹慎，建議搭配其他安全措施
CCBot 對 Claude Code 的 session 資料是唯讀存取，不會修改任何 Claude Code 的設定

結語

CCBot 巧妙地利用 tmux 作為中介層，讓 Claude Code 的操作體驗不再被限制在單一終端機前。無論你是需要在通勤途中查看 AI 編程進度、在會議中快速批准一個工具呼叫請求，還是在沙發上用手機繼續與 Claude Code 協作——CCBot 都能讓這一切變得輕而易舉。

值得一提的是，CCBot 本身就是透過 Claude Code + CCBot 的方式迭代開發出來的，充分驗證了它自身的可用性與穩定性。如果你是 Claude Code 的重度使用者，CCBot 絕對值得一試。

🔗 GitHub 專案：https://github.com/six-ddc/ccbot
📄 授權：MIT License

取消回覆

文章

文章

CCBot：用 Telegram 遠端操控 Claude Code 的開源利器

CCBot 是什麼？

核心特色功能

話題（Topic）式會話管理

即時通知系統

互動式 UI 元件

Slash 指令透傳

持久化狀態管理

系統需求與前置條件

安裝步驟

方法一：使用 uv 或 pipx 安裝（推薦）

方法二：從原始碼安裝

設定 Telegram Bot

步驟一：建立 Bot

步驟二：啟用 Threaded Mode（話題模式）

步驟三：取得你的 Telegram User ID

環境變數設定

可選環境變數

設定 Hook（推薦）

自動安裝 Hook

手動安裝 Hook

啟動與使用

啟動 CCBot

CCBot 指令一覽

典型工作流程

手動在 tmux 中執行 Claude Code

架構設計與原始碼結構

核心模組（src/ccbot/）

Handler 模組（src/ccbot/handlers/）

設計原則

資料儲存位置

主要依賴套件

實用技巧與注意事項

建議使用 tmux 常駐管理

多使用者支援

安全性考量

結語

發佈留言

取消回覆

Apply Filters

CCBot 是什麼？

核心特色功能

話題（Topic）式會話管理

即時通知系統

互動式 UI 元件

Slash 指令透傳

持久化狀態管理

系統需求與前置條件

安裝步驟

方法一：使用 uv 或 pipx 安裝（推薦）

方法二：從原始碼安裝

設定 Telegram Bot

步驟一：建立 Bot

步驟二：啟用 Threaded Mode（話題模式）

步驟三：取得你的 Telegram User ID

環境變數設定

可選環境變數

設定 Hook（推薦）

自動安裝 Hook

手動安裝 Hook

啟動與使用

啟動 CCBot

CCBot 指令一覽

典型工作流程

手動在 tmux 中執行 Claude Code

架構設計與原始碼結構

核心模組（src/ccbot/）

Handler 模組（src/ccbot/handlers/）

設計原則

資料儲存位置

主要依賴套件

實用技巧與注意事項

建議使用 tmux 常駐管理

多使用者支援

安全性考量

結語

相關文章

發佈留言

取消回覆

Apply Filters