發佈 0.2.0：改名 telegram-bot，新增 Claude Code 引擎（新增 bot 時可選 Codex / Claude），start 自動從 0.1.x 遷移

2026-08-24 11:42:37 +08:00
parent a99152d765
commit f7e94e4bd7
21 changed files with 886 additions and 235 deletions
@@ -1,20 +1,21 @@
-# telegram-codex-bot
+# telegram-bot

-用 Telegram 操控本機 [Codex CLI](https://github.com/openai/codex) 的 bot,**附 web 控制台**。
-在網頁上新增 bot(填 token、指定 Codex 可讀寫的目錄),訊息丟給 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、不同專案目錄
- **會話延續**:每個聊天室一個 Codex 會話,`/new` 開新會話;支援傳圖
+- **多 bot**:一頁管理多個 bot,各自不同引擎、token、專案目錄
+- **會話延續**:每個聊天室一個會話,`/new` 開新會話;支援傳圖、引用回覆;bot 之間可互相接力(引用另一隻 bot 的回覆再 tag)

 ## 前置需求

 | 需求 | 說明 |
 |---|---|
 | Node.js ≥ 18 | 內建 fetch |
-| Codex CLI | `npm i -g @openai/codex`,並先 `codex login` 完成登入 |
+| 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) 申請 |

@@ -23,40 +24,59 @@
 套件不在官方 npmjs 上,安裝要指定 `--registry`(不用登入):

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

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

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

 ```bash
-npm update -g telegram-codex-bot --registry=https://jianmiau.ddns.net/api/packages/AI/npm/
+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. 填名稱、Telegram token(儲存時自動驗證)
-2. 工作目錄按「📂 瀏覽」用原生視窗選資料夾(Codex 可讀寫的專案路徑)
-3. 模型/推理強度/速度用下拉選(清單來自本機 codex 的模型快取,如 GPT-5.6 Sol/Terra/Luna、low~ultra、Fast 1.5x)
+1. 填名稱、**選 AI 引擎(Codex 或 Claude)**、Telegram token(儲存時自動驗證)
+2. 工作目錄按「📂 瀏覽」用原生視窗選資料夾(AI 可讀寫的專案路徑;Codex 讀裡面的 `AGENTS.md`、Claude 讀 `CLAUDE.md` 當專案規範)
+3. 模型/推理強度用下拉選(Codex 清單來自本機 codex 的模型快取;Claude 用 opus/sonnet/haiku 別名永遠指向最新版)
 4. 沙盒模式預設 `workspace-write` → 勾「建立後立即啟動」→ 儲存,完成

 之後對 bot 私訊即可;群組中要 `@bot` 或回覆 bot 的訊息。
-再開第二、第三個 bot?再按一次「新增 Bot」,各用各的 token 和目錄。
+再開第二、第三個 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…) | `opus` / `sonnet` / `haiku` 別名或任何模型 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 工具讀取 |
+
+兩種引擎的回覆尾端都會附 `— ✅ 時間 | ctx 用量% +本輪 token | 模型 / 強度`。
+AI 要傳檔案給你:寫進工作目錄的 `.tgbot-outbox/`,bot 回覆後自動傳到 Telegram 並清空。
+
 ## web 控制台

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

 ### 圖文使用說明

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

 ![Bot 管理首頁](https://jianmiau.ddns.net/AI/telegram-codex-bot/media/branch/master/docs/01-bots.png)
@@ -64,13 +84,19 @@ npm update -g telegram-codex-bot --registry=https://jianmiau.ddns.net/api/packag
 **② 新增 Bot** — 按右上「➕ 新增 Bot」:

 1. **名稱**:也是 pm2 程序名,建立後不可改
-2. **Token**:貼上 BotFather 給的 token,儲存時自動打 Telegram 驗證,無效會警告
-3. **工作目錄**:按「📂 瀏覽…」會在這台機器桌面跳出原生資料夾視窗,選完自動帶入
-4. **模型 / 推理強度 / 速度**:下拉選單,預設值自動帶你機器上 codex 的全域設定;清單讀自本機 codex 模型快取,換模型時強度選項會連動(如 ultra 只有支援的模型才出現)
-5. 勾「建立後立即啟動」→ 儲存,bot 就上線了
+2. **AI 引擎**:Codex 或 Claude;沒裝的引擎會標「未安裝」。切換引擎時,下方的模型/強度/沙盒說明會跟著換
+3. **Token**:貼上 BotFather 給的 token,儲存時自動打 Telegram 驗證,無效會警告
+4. **工作目錄**:按「📂 瀏覽…」會在這台機器桌面跳出原生資料夾視窗,選完自動帶入
+5. **模型 / 推理強度**:下拉選單,預設值自動帶你機器上該引擎的全域設定;換模型時強度選項會連動
+6. **會話模式**:各聊天室獨立 / 所有聊天室共用 / 每則訊息獨立(不保留記憶,最快)
+7. 勾「建立後立即啟動」→ 儲存,bot 就上線了

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

+引擎切到 Claude 時，模型/強度/沙盒說明會跟著換：
+
+![新增 Claude Bot](https://jianmiau.ddns.net/AI/telegram-codex-bot/media/branch/master/docs/02b-create-claude.png)
+
 **③ PM2 分頁** — 整台機器所有 pm2 程序。Port 可直接點開對應網頁,右側可啟停/重啟/刪除任何程序。

 ![PM2 分頁](https://jianmiau.ddns.net/AI/telegram-codex-bot/media/branch/master/docs/03-pm2.png)
@@ -80,42 +106,57 @@ npm update -g telegram-codex-bot --registry=https://jianmiau.ddns.net/api/packag
 ![Log 檢視](https://jianmiau.ddns.net/AI/telegram-codex-bot/media/branch/master/docs/04-log.png)

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

 ## CLI 指令

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

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

-## Telegram 指令
+## Telegram 指令與回應規則

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

-## 回應規則與安全性
+- **私訊**:任何訊息都回應;**群組**:只回應 `@bot` 或回覆 bot 訊息的情況;訊息同時 tag 多個 bot 時只有第一個回應
+- **引用**:回覆/圈選引用某則訊息再 tag bot,引用內容會一起送給 AI;只引用不打字就直接把引用當輸入
+- **bot 接力**:Telegram 不讓 bot 看到其他 bot 的訊息,所以「回覆 A bot 的回覆 + tag B bot(不打字)」時,B 會改拿同聊天室最近一則我們自家 bot 的發言當輸入(6 小時內)
+- 對話記憶用到 80% 上下文時自動開新會話(回覆會標示),避免越用越慢

- **私訊**:任何訊息都回應;**群組**:只回應 `@bot` 或回覆 bot 訊息的情況
- 沒有使用者白名單:**任何找得到 bot 的人都能叫它在工作目錄跑 Codex**,請不要把 bot 加進不信任的群組、bot username 不要外流
- 預設沙盒 `workspace-write`:Codex 只能寫工作目錄;`danger-full-access` 只在完全理解風險時使用
- token 以明文存在 `~/.tgcodex/` 下的設定檔,請顧好這台機器的檔案權限
+## 安全性
+
+- 沒有使用者白名單:**任何找得到 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**:確認 `codex --version` 能跑;裝在非標準位置時,在 bot 設定檔加 `"codexPath": "C:/path/to/codex.js"`
+- **找不到 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`