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 辅助开发，这个机器人让你无需开放任何网络端口，即可将工作流扩展到手机上。