# Claude Code Telegram

> 管理 Claude Code Telegram Bot 的運行狀態。 使用 cct 將 Claude Code 接入 Telegram， 讓用戶能透過 Telegram 與 Claude Code 進行互動式對話（串流回應、session 持續）。 適用場景： - 用戶問「cct 有沒有在跑」、「Telegram bot 狀態」 - 需要重啟、停止、查看 log - 需要修改 ALLOWED_PATHS 或其他 cct 設定 - 重新安裝或部署新環境

- Skill: `clawdbot520/claude-code-telegram` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add clawdbot520/claude-code-telegram`
- Raw SKILL.md: https://api.skillmd.com/api/skills/clawdbot520/claude-code-telegram/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: clawdbot520 (https://skillmd.com/u/clawdbot520)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/clawdbot520/claude-code-telegram

---


# Claude Code Telegram（cct）

> 將 Claude Code 接入 Telegram，透過 Bot 進行互動式對話。

---

## 為什麼需要

| 傳統方式 | Telegram 方式 |
|----------|---------------|
| 只能在本機 Terminal | 隨時隨地用手機聊 |
| 出門無法使用 | 通勤也能用 |
| 無法串流回應 | 支援串流回應 |
| session 不持續 | session 持續對話 |

---

## 檔案結構

```
scripts/
  install.sh                                   ← 一鍵安裝腳本
  cct                                          ← cct binary（Bun 編譯，60MB，無 source）
  com.clawdbot520.claude-code-telegram.plist  ← launchd 設定
  .env.template                               ← 設定檔範本
  dispatch.sh                                 ← Claude Code Bridge 派任腳本
  on-stop.sh                                  ← Claude Code Stop hook
```

---

## 安裝（新環境）

### 前置需求

- macOS
- `~/.local/bin/claude`（Claude Code binary）已安裝
- Telegram Bot Token（從 @BotFather 取得）
- 你的 Telegram User ID（從 @userinfobot 取得）

### 一鍵安裝

```bash
cd scripts
bash install.sh
```

安裝腳本會自動：
1. 複製 `cct` binary → `~/.local/bin/cct`
2. 建立 `~/.cct/` workspace 並產生 `.env`
3. 安裝 launchd plist（路徑自動替換為當前用戶）
4. 安裝 Claude Code Bridge（`dispatch.sh`）
5. 安裝 Stop hook（`on-stop.sh`）
6. 啟動 cct 服務

### 安裝後設定

**填入 Bot Token：**
```bash
nano ~/.cct/.env
```

必填欄位：
```
TELEGRAM_BOT_TOKEN=你的_bot_token
TELEGRAM_ALLOWED_USERS=你的_telegram_user_id
```

**加入 Stop hook**（`~/.claude/settings.json`）：
```json
{
  "hooks": {
    "Stop": [{ "hooks": [{ "type": "command", "command": "~/.claude/hooks/on-stop.sh", "timeout": 30 }] }]
  }
}
```

**重啟 cct 讓設定生效：**
```bash
launchctl unload ~/Library/LaunchAgents/com.clawdbot520.claude-code-telegram.plist
launchctl load ~/Library/LaunchAgents/com.clawdbot520.claude-code-telegram.plist
```

---

## 常用操作

### 查看狀態

```bash
launchctl list | grep claude-code-telegram
ps aux | grep cct | grep -v grep
tail -20 ~/.cct/cct.log
```

### 啟動 / 停止

```bash
# 啟動
launchctl load ~/Library/LaunchAgents/com.clawdbot520.claude-code-telegram.plist

# 停止
launchctl unload ~/Library/LaunchAgents/com.clawdbot520.claude-code-telegram.plist
```

### 手動測試

```bash
cd ~/.cct && env -u CLAUDECODE ~/.local/bin/cct .
```

---

## 重要坑點

### 1. Nested Session 問題

在 Claude Code TUI 內直接跑 cct 會被保護機制擋住。launchd 啟動沒問題，手動跑要加 `env -u CLAUDECODE`。

### 2. 更新 Antigravity 前要先停 cct

cct 收到 Telegram 訊息可能喚醒 Antigravity，導致更新失敗。更新前：

```bash
launchctl unload ~/Library/LaunchAgents/com.clawdbot520.claude-code-telegram.plist
# 更新完成後
launchctl load ~/Library/LaunchAgents/com.clawdbot520.claude-code-telegram.plist
```

### 3. KeepAlive

plist 設有 `KeepAlive = true`，cct 掛掉自動重啟，重開機自動啟動。

### 4. cct 無 source code

cct binary 是 Bun 編譯產物，source 已遺失。binary 已存放在 `scripts/cct`，這是唯一備份，請妥善保存。