Skip to content

README.zh-CN.md

Latest commit

 

History

History
238 lines (164 loc) · 9.95 KB

README.zh-CN.md

File metadata and controls

238 lines (164 loc) · 9.95 KB
Raw

OpenCode Telegram Group Topics Bot

English README

License: MIT Node.js

一个面向 OpenCode 的 Telegram 机器人，可以把一个 Telegram 超级群组变成多会话的移动工作区。

本项目是原始单聊天版本 grinev/opencode-telegram-bot 的 fork。

  • 如果你想要更简单的单聊天工作流，请使用上游项目。
  • 如果你想要一个 General 控制话题，再配合多个 forum topic 并行运行 OpenCode 会话，请使用这个 fork。

无需开放公网端口，也不需要暴露 Web UI。机器人只会连接你本地的 OpenCode 服务和 Telegram Bot API。

你可以在一个群里并行跑多个 session topic，也可以在多个群里分别对应不同项目并行使用。

支持平台：macOS、Windows、Linux

机器人界面语言：English (en)、Deutsch (de)、Espanol (es)、Francais (fr)、Russkiy (ru)、简体中文 (zh)

Fork 同步说明：FORK_SYNC.md

说明：英文版 README.md 仍是当前权威文档。如中英文内容有差异，请以英文版为准。

OpenCode Telegram Group Topics Bot screencast

快速了解

  • 一个 Telegram 群通常对应一个仓库 / 项目工作区。
  • General 话题是控制通道，用于 /projects、/sessions、/new 和状态检查。
  • 每个新建的 OpenCode 会话都会对应一个独立的 forum topic。
  • 每个 topic 都维护自己的 session、model、agent 和 pinned status 状态。
  • 多个 topic 可以同时运行，多个群组也可以同时对应不同项目。
  • 私聊更适合轻量控制和状态查看，不是主要的多会话工作流入口。

这个 fork 和上游有什么区别

上游项目主要面向单聊天工作流，而这个 fork 主要面向 Telegram forum topics 场景。核心差异是：这里把 General 作为控制通道，把每个独立话题作为一个 OpenCode 会话通道，更适合移动端并行处理多个任务。

如果你只想在一个聊天窗口里切换会话，上游会更简单；如果你想在一个群里同时管理多个会话线程，这个 fork 更合适。

Quick Start

1. 准备条件

2. 创建并准备 Telegram 群组

  1. 为一个 OpenCode 项目 / 仓库创建一个新的 Telegram supergroup。
  2. 把 bot 拉进这个群。
  3. 给 bot 管理员权限，并允许 Manage Topics。
  4. 在群设置中启用 Topics。
  5. 在 @BotFather 中执行 /setprivacy，并选择 Disable。
  6. 保留默认的 General 话题，它就是控制通道。

3. 启动 OpenCode

在机器人所在的那台机器上运行 OpenCode：

opencode serve

默认 API 地址：http://localhost:4096

4. 安装机器人

方式 A：npx

npx opencode-telegram-group-topics-bot

方式 B：全局安装

npm install -g opencode-telegram-group-topics-bot
opencode-telegram-group-topics-bot config
opencode-telegram-group-topics-bot start

方式 C：从源码运行

git clone https://github.com/shanekunz/opencode-telegram-group-topics-bot.git
cd opencode-telegram-group-topics-bot
npm install
npm run build
node dist/cli.js config --mode sources
npm run dev

dist/cli.js 是由 npm run build 生成的 CLI 入口。

5. 完成配置向导

向导会询问：

  • 界面语言
  • Telegram bot token
  • 允许访问的 Telegram user ID
  • OpenCode API URL
  • 可选的 OpenCode server 用户名 / 密码

6. 首次验证

  1. 在私聊里打开你的 bot，并执行 /start。
  2. 确认 bot 有回复。
  3. 打开你的 Telegram 群，在 General 中执行 /start。
  4. 执行 /status，确认 bot 能连接 OpenCode。
  5. 在 General 中执行 /projects，为当前群选择项目。
  6. 在 General 中执行 /new，创建新的 session topic。
  7. 打开新 topic，发送一个 prompt。

如果这些都正常，说明你的群组工作区已经可以使用。

日常使用流程

  1. 用 opencode serve 启动 OpenCode
  2. 启动 bot
  3. 打开 Telegram 群并进入 General
  4. 用 /projects 确认当前群对应的项目
  5. 用 /new 创建新的 session topic
  6. 在对应 topic 里工作
  7. 需要回到历史会话时，在 General 使用 /sessions

并行工作与 Telegram 限流

  • 这个 fork 就是为并行工作设计的：一个群里多个 topic，同时多个群对应多个项目。
  • Telegram 在高频更新时会有消息速率限制，尤其是多个 topic 同时刷新的时候。
  • 机器人会尽量平滑处理这些限制，必要时放慢或错开更新。
  • 即使 Telegram 更新变慢，OpenCode 里的任务仍会继续执行。
  • 在高并发场景下，你看到的 topic 内实时输出可能会变少，但不会丢失 OpenCode 的实际工作结果。

常用命令

Command 说明
/status 查看服务健康状态、当前项目、会话和模型信息
/new 创建新的 session topic
/abort 中止当前任务
/sessions 浏览并切换最近会话
/projects 切换 OpenCode 项目
/rename 重命名当前会话
/commands 浏览并执行自定义命令
/task 为当前项目创建定时任务
/tasklist 查看和删除当前项目的定时任务
/opencode_start 远程启动 OpenCode 服务
/opencode_stop 远程停止 OpenCode 服务
/help 显示可用命令

当没有阻塞性的交互流程时，session topic 中的普通文本消息会被当作 prompt 发送给 OpenCode。

配置

配置文件位置

  • source mode 会把配置存放在仓库根目录。
  • installed mode 会把配置存放在系统应用数据目录。
  • OPENCODE_TELEGRAM_HOME 可以覆盖前两者，强制指定自定义配置目录。

installed mode 下的配置路径：

  • macOS：~/Library/Application Support/opencode-telegram-group-topics-bot/.env
  • Windows：%APPDATA%\opencode-telegram-group-topics-bot\.env
  • Linux：~/.config/opencode-telegram-group-topics-bot/.env

常用环境变量

环境变量 说明 必须 默认值
TELEGRAM_BOT_TOKEN 来自 @BotFather 的 bot token Yes -
TELEGRAM_ALLOWED_USER_ID 你的 Telegram 数字用户 ID Yes -
OPENCODE_API_URL OpenCode 服务地址 No http://localhost:4096
OPENCODE_SERVER_USERNAME 服务认证用户名 No opencode
OPENCODE_SERVER_PASSWORD 服务认证密码 No -
OPENCODE_MODEL_PROVIDER 默认模型提供方 Yes opencode
OPENCODE_MODEL_ID 默认模型 ID Yes big-pickle
BOT_LOCALE 机器人界面语言（en、de、es、fr、ru、zh） No en
LOG_LEVEL 日志级别（debug、info、warn、error） No info

请务必妥善保管 .env，其中包含你的 bot token。

如果你需要更完整的环境变量说明，请参考英文版 README.md 的 Configuration 章节。

Troubleshooting

Bot 没有响应

  • 确认 TELEGRAM_ALLOWED_USER_ID 是你真实的 Telegram 用户 ID
  • 确认 bot token 正确
  • 确认你已经在 BotFather 中关闭了 privacy mode，便于群组内使用

OpenCode 服务不可用

  • 确认 opencode serve 已经运行
  • 确认 OPENCODE_API_URL 指向正确地址

无法创建新的 session topic

  • 确认当前群是启用了 Topics 的 supergroup
  • 确认 bot 具有管理员权限，且允许 Manage Topics
  • 确认你是在 General 中执行 /new，而不是在已有 session topic 中执行

模型选择器里没有模型

  • 在 OpenCode TUI 中先添加 favorites
  • 确认 OPENCODE_MODEL_PROVIDER 和 OPENCODE_MODEL_ID 对当前环境有效

Linux 权限问题

  • 检查 CLI 是否可执行：chmod +x $(which opencode-telegram-group-topics-bot)
  • 检查配置目录是否可写：~/.config/opencode-telegram-group-topics-bot/

安全说明

只有 TELEGRAM_ALLOWED_USER_ID 对应的 Telegram 用户可以使用这个 bot。

由于 bot 运行在本地，并连接本地 OpenCode 服务，所以除 Telegram 本身外，不需要额外暴露公网服务。

更多文档

License

MIT • 原项目 © Ruslan Grinev • Fork 修改 © Shane Kunz