telegram-bot/README.md

telegram-bot

用 Telegram 操控本機 AI CLI 的 bot,每個 bot 可選 Codex CLI 或 Claude Code 引擎,附 web 控制台。 在網頁上新增 bot(選引擎、填 token、指定 AI 可讀寫的目錄),訊息丟給 bot 就會在專案目錄裡動工。

• 雙引擎:同一個控制台同時管 Codex bot 與 Claude bot,各自的模型/推理強度下拉選
• web 控制台:新增/編輯/啟停 bot 都在網頁上,token 等設定不用碰檔案;PM2 檢視是另一個分頁
• 零依賴:不用裝任何 npm 套件,只吃 Node 內建模組
• pm2 託管:控制台與每個 bot 都掛在 pm2,開機自啟、當機自動重啟
• 多 bot:一頁管理多個 bot,各自不同引擎、token、專案目錄
• 會話延續:每個聊天室一個會話,/new 開新會話;支援傳圖、引用回覆;bot 之間可互相接力(引用另一隻 bot 的回覆再 tag)

前置需求

需求	說明
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 申請

快速開始

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

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

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

之後升級同樣帶 --registry:

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 的模型快取;Claude 用 opus/sonnet/haiku 別名永遠指向最新版)
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…)	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、刪除
📊 PM2	整台機器所有 pm2 程序:狀態、監聽 port(可點)、CPU、記憶體、out/err log、啟停/重啟/刪除

圖文使用說明

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

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

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

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

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

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

• 兩個分頁每 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;只引用不打字就直接把引用當輸入
• 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)升級

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