grinev/opencode-telegram-bot

OpenCode mobile client via Telegram: run and monitor AI coding tasks from your phone while everything runs locally on your machine. Scheduled tasks support.

OpenCode Telegram Bot – 是什麼

一個 Node.js Telegram 機器人，讓你可透過手機控制 OpenCode AI 編碼 CLI。它僅與 本地 OpenCode 伺服器（在同一台機器上執行）和官方 Telegram Bot API 通訊——無需公開端口或暴露 API。實際上，你可以從 Telegram 聊天中啟動編碼會話、切換模型、傳送檔案、取得即時更新，甚至排程任務，全部在聊天中完成。

核心功能（如 README 所述）

領域	你可以在 Telegram 中執行的操作
遠端編碼	向 OpenCode 發送任意文字提示（或語音轉錄提示），並以檔案形式接收生成的程式碼。
會話管理	建立新會話（`/new`）、繼續現有會話（`/sessions`）、重新命名（`/rename`）、中止（`/abort`）、分離（`/detach`）。
即時追蹤	機器人會追蹤正在執行的 OpenCode CLI 會話，顯示即時代理輸出、子代理步驟，以及來自其他 TUI 客戶端的任何外部輸入。
模型管理	從 OpenCode 的最愛或最近使用記錄中選擇模型，或直接在聊天中按提供者瀏覽所有模型。
代理模式	即時在 Plan 和 Build 模式之間切換；觀察子代理活動。
技能與命令	浏覽 OpenCode 的「技能」或自訂命令（`/skills`、`/commands`），並可選參數執行。
檔案互動	上傳圖片、PDF 或任何文字檔案；使用 `/ls` 浏覽專案檔案系統，下載檔案，或將檔案附加到下一個提示。
計畫任務	建立一次性或重複性提示（`/task`、`/tasklist`）。重複任務的最小間隔為 5 分鐘，最多預設支援 10 個任務。
狀態與通知	固定訊息持續顯示專案/工作樹、模型、上下文使用量和已變更的檔案。後台會話通知讓你了解分離會話的狀態。
設定與本地化	`/settings` 可調整執行時選項（訊息佇列、上下文壓縮、STT 等）。透過 `BOT_LOCALE` 支援 10 種語言的 UI。
安全	僅允許你白名單中的 Telegram 使用者與機器人通訊；其他使用者將被忽略。
Docker 與守護模式	可在容器中執行機器人，而 OpenCode 保留在主機上；或使用內建守護程序（`opencode-telegram start --daemon`）。

快速入門（啟動流程）

使用 @BotFather 建立 Telegram 機器人，並記下令牌。
透過 @userinfobot 找到你的 Telegram 數字使用者 ID。
在同一台機器上啟動 OpenCode 伺服器：opencode serve（預設 API 位址 http://localhost:4096）。
執行機器人——最簡單的方式是單行命令：
```
npx @grinev/opencode-telegram-bot@latest
```
如果缺少必要的環境變數，互動式向導將詢問令牌、使用者 ID、API 位址等，並將 .env 檔案寫入平台特定的設定目錄。
開啟 Telegram，與你的新機器人開始聊天，並開始傳送提示。

替代安裝 – npm i -g @grinev/opencode-telegram-bot 後執行 opencode-telegram start。使用 --daemon 以自包含的後台程序執行，或按文件說明與 systemd/pm2/Docker 集成。

設定亮點

變數	含義	通常預設值
`TELEGRAM_BOT_TOKEN`	BotFather 提供的令牌	必需
`TELEGRAM_ALLOWED_USER_ID`	你的數字型 Telegram ID	必需
`OPENCODE_API_URL`	本地 OpenCode 伺服器的 URL	`http://localhost:4096`
`OPENCODE_MODEL_PROVIDER` / `OPENCODE_MODEL_ID`	未選擇模型時使用的預設模型	`opencode` / `big-pickle`
`BOT_LOCALE`	UI 語言（`en`, `es`, `zh`, …）	`en`
`MESSAGE_QUEUE`（透過 `/settings`）	當代理忙碌時排隊訊息	預設關閉
`TASK_LIMIT`	最大並行計畫任務數	`10`
`SCHEDULED_TASK_EXECUTION_TIMEOUT_MINUTES`	機器人等待計畫執行失敗前的時間	`120`

所有這些都可以透過 .env 檔案或實際環境變數提供；向導會將檔案寫入 ~/Library/Application Support/opencode-telegram-bot/.env（macOS）、%APPDATA%\opencode-telegram-bot\.env（Windows）或 ~/.config/opencode-telegram-bot/.env（Linux）。

適合誰使用？

已在本地使用 OpenCode 的開發者，希望在遠離工作台時透過手機快速啟動編碼任務。
需要快速、安全的遠端介面的團隊，無需公開端口或搭建完整 Web UI。
喜愛 Telegram 機器人互動性（內嵌鍵盤、固定訊息、語音轉文字等）的高階使用者。

限制 / README 中的注意事項

機器人僅在 OpenCode 伺服器與機器人運行於同一台機器上（或可透過設定的 OPENCODE_API_URL 存取）時才有效。
計畫任務始終以 build 代理執行；目前不支援其他代理用於重複任務。
npm 套件可能落後於 main 分支——README 中展示的某些功能可能在最新發行版本中不可用。
文件上傳的最大檔案大小可設定（CODE_FILE_MAX_SIZE_KB），但此摘錄中未列出預設值。

總結

OpenCode Telegram Bot 是 OpenCode AI 編碼平台與 Telegram 之間真正的生產級橋樑，為你提供一個安全、可攜帶的 UI，用於遠端程式碼生成、會話管理與自動化。它完全在本地運行，支援多語言，並提供豐富的 Telegram 原生互動功能（內嵌鍵盤、固定狀態、語音提示、檔案瀏覽）。如果你已依賴 OpenCode 進行 AI 輔助開發，這個機器人讓你無需開放任何網路端口，即可將工作流程擴展到手機上。