telegram-codex-bot (0.1.4)
Installation
registry=https://jianmiau.ddns.net/api/packages/AI/npm/npm install telegram-codex-bot@0.1.4"telegram-codex-bot": "0.1.4"About this package
Telegram bot powered by the local Codex CLI — zero-dependency, pm2-managed, with a built-in PM2 web viewer
telegram-codex-bot
用 Telegram 操控本機 Codex CLI 的 bot,附 web 控制台。 在網頁上新增 bot(填 token、指定 Codex 可讀寫的目錄),訊息丟給 bot 就會在專案目錄裡動工。
- web 控制台:新增/編輯/啟停 bot 都在網頁上,token 等設定不用碰檔案;PM2 檢視是另一個分頁
- 零依賴:不用裝任何 npm 套件,只吃 Node 內建模組
- pm2 託管:控制台與每個 bot 都掛在 pm2,開機自啟、當機自動重啟
- 多 bot:一頁管理多個 bot,各自不同 token、不同專案目錄
- 會話延續:每個聊天室一個 Codex 會話,
/new開新會話;支援傳圖
前置需求
| 需求 | 說明 |
|---|---|
| Node.js ≥ 18 | 內建 fetch |
| Codex CLI | npm i -g @openai/codex,並先 codex login 完成登入 |
| pm2 | npm i -g pm2 |
| Telegram Bot token | 跟 @BotFather 申請 |
快速開始
套件不在官方 npmjs 上,安裝要指定 --registry(不用登入):
npm install -g telegram-codex-bot --registry=https://jianmiau.ddns.net/api/packages/AI/npm/
telegram-codex-bot start # 先做環境檢查(codex/登入/pm2/git),再把控制台掛上 pm2
之後升級同樣帶 --registry:
npm update -g telegram-codex-bot --registry=https://jianmiau.ddns.net/api/packages/AI/npm/
打開 http://localhost:3799 →「🤖 Bot 管理」→「➕ 新增 Bot」:
- 填名稱、Telegram token(儲存時自動驗證)
- 工作目錄按「📂 瀏覽」用原生視窗選資料夾(Codex 可讀寫的專案路徑)
- 模型/推理強度/速度用下拉選(清單來自本機 codex 的模型快取,如 GPT-5.6 Sol/Terra/Luna、low~ultra、Fast 1.5x)
- 沙盒模式預設
workspace-write→ 勾「建立後立即啟動」→ 儲存,完成
之後對 bot 私訊即可;群組中要 @bot 或回覆 bot 的訊息。
再開第二、第三個 bot?再按一次「新增 Bot」,各用各的 token 和目錄。
要在群組使用的話,記得關閉 Group Privacy,否則 bot 收不到群組訊息: Telegram 開 @BotFather 迷你 APP → 選該機器人 → Bot Settings → 關閉 Group Privacy(改完把 bot 踢出群再拉回才生效)。
web 控制台
| 分頁 | 功能 |
|---|---|
| 🤖 Bot 管理 | 新增/編輯(token、目錄用原生視窗選、沙盒、模型/推理強度/速度下拉、逾時)、啟動/停止/重啟、log、刪除 |
| 📊 PM2 | 整台機器所有 pm2 程序:狀態、監聽 port(可點)、CPU、記憶體、out/err log、啟停/重啟/刪除 |
圖文使用說明
① Bot 管理首頁 — 每個 bot 一列:狀態、工作目錄、沙盒與模型設定、遮罩後的 token。 右側按鈕:▶ 啟動 / ⏹ 停止、🔄 重啟、📄 log、✏️ 編輯、🗑 刪除。上方橫幅提醒群組使用要先關 Group Privacy。
② 新增 Bot — 按右上「➕ 新增 Bot」:
- 名稱:也是 pm2 程序名,建立後不可改
- Token:貼上 BotFather 給的 token,儲存時自動打 Telegram 驗證,無效會警告
- 工作目錄:按「📂 瀏覽…」會在這台機器桌面跳出原生資料夾視窗,選完自動帶入
- 模型 / 推理強度 / 速度:下拉選單,預設值自動帶你機器上 codex 的全域設定;清單讀自本機 codex 模型快取,換模型時強度選項會連動(如 ultra 只有支援的模型才出現)
- 勾「建立後立即啟動」→ 儲存,bot 就上線了
③ PM2 分頁 — 整台機器所有 pm2 程序。Port 可直接點開對應網頁,右側可啟停/重啟/刪除任何程序。
④ Log 檢視 — 點任一程序的「📄 out」/「⚠ err」,下方展開尾端 200 行,可勾自動更新(5s)。
- 兩個分頁每 5 秒自動更新
- Bot 設定存於
~/.tgcodex/bots/<名稱>/tgcodex.config.json,bot 掛 pm2 的程序名 = bot 名稱 - 預設只綁
127.0.0.1。這個介面能控制 pm2 且存有 token,不要裸露到外網; 區網存取請自行評估(改~/.tgcodex/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 前景執行控制台(除錯用)
短別名:tgcodex。CLI 只管控制台;bot 的一切(含啟停)都在網頁上操作。
Telegram 指令
| 指令 | 說明 |
|---|---|
/new(或 !clear、!重置) |
開新會話,清除對話記憶 |
/status |
查看會話、工作目錄、沙盒模式 |
/help |
使用說明 |
回應規則與安全性
- 私訊:任何訊息都回應;群組:只回應
@bot或回覆 bot 訊息的情況 - 沒有使用者白名單:任何找得到 bot 的人都能叫它在工作目錄跑 Codex,請不要把 bot 加進不信任的群組、bot username 不要外流
- 預設沙盒
workspace-write:Codex 只能寫工作目錄;danger-full-access只在完全理解風險時使用 - token 以明文存在
~/.tgcodex/下的設定檔,請顧好這台機器的檔案權限
疑難排解
- 找不到 codex:確認
codex --version能跑;裝在非標準位置時,在 bot 設定檔加"codexPath": "C:/path/to/codex.js" - 409 Conflict: terminated by other getUpdates:同一個 token 跑了兩個實例(每個 bot 要用自己的 token)
- 群組不理人:見上方 BotFather privacy 設定
- 開機自啟:
pm2 startup照指示設定(Windows 可用pm2-installer),控制台與 bot 啟動時都會自動pm2 save
License
MIT
Keywords
telegram
bot
codex
codex-cli
pm2
ai
agent
Details
Assets (1)
Versions (9)
View all
telegram-codex-bot-0.1.4.tgz
34 KiB