telegram-bot/README.md

# telegram-bot

用 Telegram 操控本機 AI CLI 的 bot,**每個 bot 可選 [Codex CLI](https://github.com/openai/codex) 或 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 引擎**,附 web 控制台。
在網頁上新增 bot(選引擎、填 token、指定 AI 可讀寫的目錄),訊息丟給 bot 就會在專案目錄裡動工。

- **雙引擎**:同一個控制台同時管 Codex bot 與 Claude bot,各自的模型/推理強度下拉選
- **web 控制台**:新增/編輯/啟停 bot 都在網頁上,token 等設定不用碰檔案;PM2 檢視是另一個分頁
- **零依賴**:不用裝任何 npm 套件,只吃 Node 內建模組
- **pm2 託管**:控制台與每個 bot 都掛在 pm2,開機自啟、當機自動重啟
- **多 bot**:一頁管理多個 bot,各自不同引擎、token、專案目錄
- **會話延續**:每個聊天室一個會話,`/new` 開新會話;支援傳圖與附件(PDF/文字/程式碼檔)、引用回覆;bot 之間可互相接力(引用另一隻 bot 的回覆再 tag)
- **權限與規範**:可限定只有哪些 Telegram 帳號能讓 AI 改檔/跑指令(其他人自動唯讀);可設每則訊息前綴的回覆規範(專案守門、成員身分)

## 前置需求

| 需求 | 說明 |
|---|---|
| Node.js ≥ 18 | 內建 fetch |
| Codex CLI **或** Claude Code(至少一個) | Codex:`npm i -g @openai/codex` 並 `codex login`;Claude:`npm i -g @anthropic-ai/claude-code` 並執行一次 `claude` 完成登入 |
| pm2 | `npm i -g pm2` |
| Telegram Bot token | 跟 [@BotFather](https://t.me/BotFather) 申請 |

## 快速開始

套件不在官方 npmjs 上,安裝要指定 `--registry`(不用登入):

```bash
npm install -g telegram-bot --registry=https://jianmiau.ddns.net/api/packages/AI/npm/

telegram-bot start        # 先做環境檢查(codex/claude/登入/pm2/git),再把控制台掛上 pm2
```

之後升級同樣帶 `--registry`:

```bash
npm update -g telegram-bot --registry=https://jianmiau.ddns.net/api/packages/AI/npm/
telegram-bot start        # 重新 start 一次,bot 程序會自動切到新版
```

打開 **http://localhost:3799** →「🤖 Bot 管理」→「➕ 新增 Bot」:

1. 填名稱、**選 AI 引擎(Codex 或 Claude)**、Telegram token(儲存時自動驗證)
2. 工作目錄按「📂 瀏覽」用原生視窗選資料夾(AI 可讀寫的專案路徑;Codex 讀裡面的 `AGENTS.md`、Claude 讀 `CLAUDE.md` 當專案規範)
3. 模型/推理強度用下拉選,清單依引擎不同(Codex 來自本機 codex 的模型快取,如 GPT-5.6 Sol/Terra/Luna;Claude 為 Fable 5 / Opus 5 / Sonnet 5)
4. 沙盒模式預設 `workspace-write` → 勾「建立後立即啟動」→ 儲存,完成

之後對 bot 私訊即可;群組中要 `@bot` 或回覆 bot 的訊息。
再開第二、第三個 bot?再按一次「新增 Bot」,各用各的引擎、token 和目錄。

> **要在群組使用的話,記得關閉 Group Privacy**,否則 bot 收不到群組訊息:
> Telegram 開 @BotFather 迷你 APP → 選該機器人 → Bot Settings → 關閉 Group Privacy(改完把 bot 踢出群再拉回才生效)。

## 引擎差異

| | Codex | Claude |
|---|---|---|
| 底層指令 | `codex exec --json` | `claude -p --output-format stream-json` |
| 專案規範檔 | `AGENTS.md` | `CLAUDE.md` |
| 模型 | 本機 codex 模型快取(GPT-5.6 Sol/Terra/Luna…) | Fable 5 / Opus 5 / Sonnet 5(設定檔可手填其他模型 id) |
| 推理強度 | low ~ ultra(依模型) | low / medium / high / max |
| 速度 | 固定 Fast(priority 1.5x) | — |
| `read-only` | codex 唯讀沙盒 | 禁用 Write/Edit/Bash 等工具 |
| `workspace-write` | 可讀寫工作目錄、沙盒內執行指令(可另開連網) | 自動接受檔案編輯;**不執行指令**(非互動模式下會被拒,回覆會標示) |
| `danger-full-access` | 不設限 | `--dangerously-skip-permissions`,不設限 |
| 生圖 | 內建 imagegen 技能,產圖自動傳回 | 無(可自行在 CLAUDE.md 接其他工具) |
| 傳圖給 bot | `-i` 直接餵給模型 | 存暫存檔後由 Read 工具讀取 |
| 傳檔案給 bot(PDF / 文字 / 程式碼) | 路徑寫進 prompt,由 codex 讀取 | 存暫存檔後由 Read 工具讀取 |

兩種引擎的回覆尾端都會附 `— ✅ 時間 | ctx 用量% +本輪 token | 模型 / 強度`。
AI 要傳檔案給你:寫進工作目錄的 `.tgbot-outbox/`,bot 回覆後自動傳到 Telegram 並清空。

## web 控制台

| 分頁 | 功能 |
|---|---|
| 🤖 Bot 管理 | 新增/編輯(引擎、token、目錄用原生視窗選、沙盒、模型/推理強度下拉、會話模式、逾時)、啟動/停止/重啟、log、刪除 |
| 📊 PM2 | 整台機器所有 pm2 程序:狀態、監聽 port(可點)、CPU、記憶體、out/err log、啟停/重啟/刪除 |

### 圖文使用說明

**① Bot 管理首頁** — 每個 bot 一列:名稱旁標示引擎、狀態、工作目錄、沙盒與模型設定、遮罩後的 token。
右側按鈕:▶ 啟動 / ⏹ 停止、🔄 重啟、📄 log、✏️ 編輯、🗑 刪除。上方橫幅提醒群組使用要先關 Group Privacy。

![Bot 管理首頁](https://jianmiau.ddns.net/AI/telegram-bot/media/branch/master/docs/01-bots.png)

**② 新增 Bot** — 按右上「➕ 新增 Bot」:

1. **名稱**:也是 pm2 程序名,建立後不可改
2. **AI 引擎**:Codex 或 Claude;沒裝的引擎會標「未安裝」。切換引擎時,下方的模型/強度/沙盒說明會跟著換
3. **Token**:貼上 BotFather 給的 token,儲存時自動打 Telegram 驗證,無效會警告
4. **工作目錄**:按「📂 瀏覽…」會在這台機器桌面跳出原生資料夾視窗,選完自動帶入
5. **模型 / 推理強度**:下拉選單,預設值自動帶你機器上該引擎的全域設定;換模型時強度選項會連動
6. **會話模式**:各聊天室獨立 / 所有聊天室共用 / 每則訊息獨立(不保留記憶,最快)
7. **額外選項**(打勾才展開;取消打勾儲存會清空):
   - **可讀寫成員**:填 Telegram username(逗號分隔),清單外的人一律以 read-only 沙盒執行,由 CLI 層硬擋;留空 = 所有人都依沙盒設定
   - **回覆規範**:每則訊息開頭附加的規則,例如「只回答本專案相關問題」「@xxx 是後端工程師,回覆用 API 契約視角」;專案本身的規範仍放工作目錄的 `AGENTS.md` / `CLAUDE.md`
8. 勾「建立後立即啟動」→ 儲存,bot 就上線了

![新增 Bot 表單](https://jianmiau.ddns.net/AI/telegram-bot/media/branch/master/docs/02-create.png)

引擎切到 Claude 時，模型/強度/沙盒說明會跟著換：

![新增 Claude Bot](https://jianmiau.ddns.net/AI/telegram-bot/media/branch/master/docs/02b-create-claude.png)

**編輯既有 bot** — 引擎、模型、可讀寫成員、回覆規範都可事後修改;執行中的 bot 儲存後會自動重啟套用。

![編輯 Claude Bot](https://jianmiau.ddns.net/AI/telegram-bot/media/branch/master/docs/05-edit-claude.png)

**③ PM2 分頁** — 整台機器所有 pm2 程序。Port 可直接點開對應網頁,右側可啟停/重啟/刪除任何程序。

![PM2 分頁](https://jianmiau.ddns.net/AI/telegram-bot/media/branch/master/docs/03-pm2.png)

**④ Log 檢視** — 點任一程序的「📄 out」/「⚠ err」,下方展開尾端 200 行,可勾自動更新(5s)。

![Log 檢視](https://jianmiau.ddns.net/AI/telegram-bot/media/branch/master/docs/04-log.png)

- 兩個分頁每 5 秒自動更新
- Bot 設定存於 `~/.tgbot/bots/<名稱>/tgbot.config.json`,bot 掛 pm2 的程序名 = bot 名稱
- 預設只綁 `127.0.0.1`。這個介面能控制 pm2 且存有 token,**不要裸露到外網**;
  區網存取請自行評估(改 `~/.tgbot/console.json` 的 `host`,無帳密保護)

## CLI 指令

```
telegram-bot start               環境檢查 + 啟動 web 控制台(掛 pm2;--port 換 port 會記住;--skip-checks 跳過檢查)
telegram-bot doctor              只做環境檢查(codex / claude CLI 與登入、pm2、git)
telegram-bot stop / restart      停止 / 重啟控制台(bot 不受影響)
telegram-bot delete              從 pm2 移除控制台
telegram-bot status              終端機看控制台與所有 bot 狀態
telegram-bot logs [--name <bot>] 跟看 log(不帶 --name 看控制台)
telegram-bot web                 前景執行控制台(除錯用)
```

短別名:`tgbot`。CLI 只管控制台;bot 的一切(含啟停)都在網頁上操作。

## Telegram 指令與回應規則

| 指令 | 說明 |
|---|---|
| `/new`(或 `!clear`、`!重置`) | 開新會話,清除對話記憶 |
| `/status` | 查看引擎、會話、工作目錄、沙盒模式 |
| `/help` | 使用說明 |

- **私訊**:任何訊息都回應;**群組**:只回應 `@bot` 或回覆 bot 訊息的情況;訊息同時 tag 多個 bot 時只有第一個回應
- **引用**:回覆/圈選引用某則訊息再 tag bot,引用內容會一起送給 AI;只引用不打字就直接把引用當輸入
- **附件**:圖片、PDF、文字/程式碼檔都會下載給 AI 讀(Telegram Bot 下載上限 20MB;docx/xlsx/zip 等二進位不支援,bot 會回覆說明);「回覆別人傳的檔案/圖片再 tag bot」也會讀到那個附件(回覆另一隻 bot 傳的檔案除外,Telegram 不給)
- **bot 接力**:Telegram 不讓 bot 看到其他 bot 的訊息,所以「回覆 A bot 的回覆 + tag B bot(不打字)」時,B 會改拿同聊天室最近一則我們自家 bot 的發言當輸入(6 小時內)
- 對話記憶用到 80% 上下文時自動開新會話(回覆會標示),避免越用越慢

## 安全性

- 沒有使用者白名單:**任何找得到 bot 的人都能叫它在工作目錄跑 AI**,請不要把 bot 加進不信任的群組、bot username 不要外流
- 預設沙盒 `workspace-write`:AI 只能寫工作目錄;`danger-full-access` 只在完全理解風險時使用(Claude 引擎下等於 `--dangerously-skip-permissions`)
- token 以明文存在 `~/.tgbot/` 下的設定檔,請顧好這台機器的檔案權限

## 從 telegram-codex-bot(0.1.x)升級

```bash
npm install -g telegram-bot --registry=https://jianmiau.ddns.net/api/packages/AI/npm/
npm uninstall -g telegram-codex-bot
telegram-bot start
```

`start` 會自動:把 `~/.tgcodex` 搬到 `~/.tgbot`(registry 路徑一併改寫)、把跑在舊套件上的 bot 重新掛到新套件、移除舊的 `tgcodex-console`。既有 bot 全部視為 Codex 引擎,設定與會話都保留;交件匣舊名 `.tgcodex-outbox/` 仍會收。

## 疑難排解

- **找不到 codex / claude**:確認 `codex --version` / `claude --version` 能跑;裝在非標準位置時,在 bot 設定檔加 `"codexPath"` / `"claudePath"`
- **Claude bot 回「有 N 個操作因沙盒權限被拒」**:`workspace-write` 下 Claude 不能執行指令(Bash);需要跑指令請改 `danger-full-access`
- **409 Conflict: terminated by other getUpdates**:同一個 token 跑了兩個實例(每個 bot 要用自己的 token)
- **群組不理人**:見上方 BotFather privacy 設定
- **開機自啟**:`pm2 startup` 照指示設定(Windows 可用 `pm2-installer`),控制台與 bot 啟動時都會自動 `pm2 save`

## License

MIT