opencode-telegram-bot

手机遥控本地 AI 编程，随时监控任务进度

这是一个将 AI 编程助手 OpenCode 接入 Telegram 的移动客户端桥接工具。它解决的核心问题是：开发者无法随时随地查看和操控本地运行的 AI 编程任务。通过 Telegram 机器人，用户可以在手机上发送指令，启动、监控和干预本地机器上的 OpenCode 编码任务，所有计算和代码操作仍在本地完成，确保代码安全。项目基于 Node.js 和 grammY 框架构建，支持任务调度（定时运行），并提供任务状态推送、结果查看等能力。它本质上是一个远程控制面板，让 AI 编程从桌面延伸到移动场景，适合需要在外出时管理长时间运行任务的开发者。

开源 free 智能体

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 1187

维护状态活跃

是否开源是

定价模式 free

项目数据

分类智能体

开发团队grinev

所属国家

官网地址

GitHubhttps://github.com/grinev/opencode-telegram-bot

定价模式free

价格说明开源项目，MIT 许可证，本地运行，完全免费。

访问状态

是否开源是

开源协议MIT

主要语言TypeScript

技术栈/模型ai-agent,autonomous-agent,coding-agent,developer-tools,grammy,nodejs,openclaw-alternative,opencode,telegram,telegrambot,typescript

GitHub 星标★ 1187

30天Star增速

HF 下载量

上线时间2026-02-09 00:00:00

最近更新2026-09-23 00:00:00

维护状态活跃

中文支持

访问方式

移动端支持

综合评分

收录时间2026-08-09

浏览次数4

使用教程

难度：入门约 10 分钟部署方式：命令行工具 8 步

环境要求

已在本机安装并运行 OpenCode（本地 OpenCode 服务器，默认端口 4096）
Node.js 环境（可用 npx / npm）
一个 Telegram Bot Token 和你的 Telegram 用户 ID
系统为 macOS、Windows 或 Linux

安装与启动步骤

1启动 OpenCode 服务

机器人需要连接本地 OpenCode 服务器，先在宿主机启动它并监听 4096 端口，再启动机器人。
```
opencode serve --port 4096
```
2快速运行机器人

最快方式，直接用 npx 运行，无需克隆仓库。注意不要在源码仓库根目录执行，否则会报 opencode-telegram: not found。
```
npx @grinev/opencode-telegram-bot@latest
```
3完成向导配置

若未通过环境变量或 .env 提供配置，会出现交互向导：依次填写界面语言、Bot Token、用户 ID、OpenCode API URL，以及可选的服务器用户名/密码。
4全局安装方式

也可以全局安装后使用 start 命令。前台模式推荐用于 systemd、Docker 和本地调试等外部进程管理场景。
```
npm install -g @grinev/opencode-telegram-bot
opencode-telegram start
```
5后台守护模式

内置后台模式适合没有外部进程管理器的独立 npm 安装场景，可启动、查看状态和停止。
```
opencode-telegram start --daemon
opencode-telegram status
opencode-telegram stop
```
6随时重新配置

需要修改 Bot Token、用户 ID 或 OpenCode 地址等配置时，运行 config 命令重新进入配置流程。
```
opencode-telegram config
```
7从源码运行

克隆仓库、安装依赖并复制环境变量模板，之后按 Development 章节说明启动（不要用 npx）。
```
git clone https://github.com/grinev/opencode-telegram-bot.git
cd opencode-telegram-bot
npm install
cp .env.example .env
```
8Docker 部署准备

镜像只包含 Telegram 机器人，OpenCode 必须已在宿主机运行。克隆后复制 .env 并按 Configuration 小节填写环境变量。
```
git clone https://github.com/grinev/opencode-telegram-bot.git
cd opencode-telegram-bot
cp .env.example .env
```

关键配置

配置项	必填	说明	示例
`OPENCODE_API_URL`	是	OpenCode 服务器地址；Linux 默认 compose 下经 host 网络访问	`http://127.0.0.1:4096`
`OPENCODE_MODEL_PROVIDER`	否	默认模型提供方，与 Model ID 组合后固定出现在模型收藏中	`anthropic`
`OPENCODE_MODEL_ID`	否	默认模型 ID，与 Provider 组合使用	`claude-sonnet-4`
`OPENCODE_TELEGRAM_CONTAINER`	否	Docker Compose 自动设为 1，提示哪些命令需要宿主机文件系统	`1`
`INITIAL_SETTINGS_PRESET`	否	以 JSON 设定初始默认设置，仅影响尚未持久化的键	`{"showAssistantRunFooter":false,"compactOutputMode":true,"tt`
`MAX_QUEUED_PROMPTS`	否	消息队列上限，默认 5 条，队列在 /abort 或切换会话时清空	`5`

如何确认成功

在 Telegram 中打开你的机器人并发送一条任务即可；用 opencode-telegram status 可查看后台运行状态。

常见问题

Q：为什么在源码目录运行 npx 会报 opencode-telegram: not found？

A：快速开始面向 npm 用法，不需要克隆仓库。若从仓库根目录直接运行会失败，请改用 README 的 Development 章节从源码启动。

Q：为什么在 Docker 里 /open、/ls、/opencode_start 等命令不可用？

A：这些命令需要机器人进程看到宿主机项目路径，或在同一命名空间中启停 opencode。默认镜像做不到，机器人会返回警告而非通用错误。

Q：docker 需要暴露 4096 端口吗？

A：不需要。4096 端口属于单独运行的 OpenCode 服务器，机器人镜像并不对外暴露该端口。

Q：systemd、pm2 或 Docker 下该用哪种启动方式？

A：请使用 opencode-telegram start（前台运行），不要加 --daemon。内置守护模式只适合没有外部进程管理器的独立 npm 安装。

注意事项

所有计算和代码操作都在本地完成，机器人只与本地 OpenCode 服务器和 Telegram Bot API 通信，不开放端口、不暴露 API。
Docker 镜像只包含 Telegram 机器人，宿主机必须已运行 OpenCode；镜像内不支持需要宿主机文件系统的命令。
README 跟踪 main 分支，npm 上的最新发布可能还不包含文中描述的全部功能。
设置以原子方式写入 settings.json，旧版本保留为 settings.json.bak；两者都不可读时机器人会拒绝启动而不是覆盖。

核心亮点

手机端直接发起和监控 OpenCode 任务，无需 SSH 或桌面环境
支持定时任务调度，可自动化触发编码流程
本地执行代码，数据不出机器，安全性高

不足之处

依赖 Telegram 服务，网络受限地区使用不便
仅适配 OpenCode 生态，不兼容其他 AI 编码工具

适用场景

外出时查看 CI 或长时编码任务状态
在手机上远程启动代码生成或重构任务
定时触发自动化编码流程并接收结果通知

替代项目

OpenClaw、Telegram Bot API 自建方案、OpenCode 官方 CLI 配合 tmux

项目介绍

opencode-telegram-bot 是智能体领域的开源项目，由 grinev 开发，是 2026 年新上线的项目。

在全站 13,090 个收录项目中，它的 GitHub 星标数（1,187）位列前 30%，在智能体分类中处于中上游。

近 42 天，它的 GitHub 星标从 1,029 增加到 1,187，净增 158。

项目目前处于活跃维护状态，最近一次代码更新于 2026-09-23。MIT 许可证，本地运行，完全免费。

它主要面向的使用场景是：外出时查看CI或长时编码任务状态。同类可对比的替代方案包括 OpenClaw、Telegram Bot API 自建方案、OpenCode 官方 CLI 配合 tmux。

上一篇：ouroboros

下一篇：PokeClaw