omotg

# OMOTG — Telegram ↔ OpenCode 桥接 OMOTG 是一个基于 Go 的双向桥接工具，连接 **Telegram** 和 **OpenCode**，通过 MCP SSE 服务器和 Telegram webhook。它允许您直接从 Telegram 与 OpenCode 进行交互。 ## 功能 - **🤖 Telegram 机器人** — 向 OpenCode 发送消息并通过 Telegram 获取响应 - **🔌 MCP SSE 服务器** — 向任何 MCP 客户端（包括 OpenCode 本身）公开 Telegram 工具（`send_message`、`send_notification`） - **📦 零依赖** — 纯 Go 标准库，无外部包 - **🤖 多机器人多代理** — 在一个二进制文件中运行 N 个 Telegram 机器人，每个机器人路由到不同的 OMO 代理（Sisyphus、Prometheus、Atlas、Hephaestus） - **🔒 安全** — 秘密令牌验证、聊天 ID 白名单、webhook 的 TLS 证书（或反向代理后面的纯 HTTP） - **🧵 会话管理** — 线程安全的多会话存储，每个聊天和主题路由；会话持续直到显式删除 - **💬 群组和论坛主题** — 支持 Telegram 超级群组论坛主题；`/topic new` 创建专用主题 + OpenCode 会话 - **🤖 机器人角色** — 从 Telegram 读取机器人名称和描述，用于个性化欢迎消息 - **📋 Systemd 集成** — 配备 systemd 用户服务文件，用于自动启动 ## 先决条件 | 需求 | 版本 | 备注 | |-------------|---------|-------| | Go | 1.26+ | 从源代码构建 | | OpenCode CLI | 最新 | 用于 `opencode serve` 后端 | | systemd | 任意 | 用户模式服务（logind） | | OpenSSL | 任意 | 仅在独立 TLS 时需要（或使用反向代理） | | Linux | 任意 | 在 Ubuntu 上测试 | | Homebrew | 最新 | 可选 — 通过 `brew install omotg` 安装 | ## 安装 ### 选项 1：Homebrew（推荐） ```bash brew tap itokun99/omotg brew install omotg ``` 这将二进制文件安装到 `$(brew --prefix)/bin/omotg`，并将环境模板安装到 `$(brew --prefix)/etc/omotg/env.template`。 ### 选项 2：Go 安装（全局二进制） ```bash go install github.com/itokun99/omotg@latest ``` 这将 `omotg` 二进制文件安装到 `$(go env GOPATH)/bin/omotg`。确保 `$(go env GOPATH)/bin` 在您的 `PATH` 中。 ### 选项 3：从源代码构建 ```bash git clone git@github.com:itokun99/omotg.git cd omotg go build -o omotg . sudo cp omotg /usr/local/bin/ # 可选，用于系统范围安装 ``` 或直接安装到您的本地二进制目录： ```bash go build -o ~/.local/bin/omotg/omotg . ``` ### 2. TLS 证书（可选） Telegram webhook 需要 HTTPS。您有两个选项： #### 选项 A：反向代理（生产推荐） 将 OMOTG 放在反向代理（Traefik、Caddy、Nginx）后面，并使用 Let's Encrypt。设置 `OMOTG_TLS_CERT_FILE=` 和 `OMOTG_TLS_KEY_FILE=` 在您的环境文件中均为空，以 在纯 HTTP 模式下启动 webhook 服务器。代理处理 HTTPS 终止。 #### 选项 B：自签名证书（独立） ```bash mkdir -p ~/.config/omotg openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ -keyout ~/.config/omotg/webhook.key \ -out ~/.config/omotg/webhook.crt \ -subj "/CN=your-domain.com" \ -addext "subjectAltName=DNS:your-domain.com" ``` 将 `your-domain.com` 替换为指向您服务器的实际域名。 ### 3. 创建环境配置 ```bash cp env.template ~/.config/omotg/env # 然后用您的值编辑： # TELEGRAM_BOT_TOKEN — 来自 @BotFather # TELEGRAM_WEBHOOK_URL — https://your-domain.com/webhook（或：8443/webhook 独立） # TELEGRAM_SECRET_TOKEN — 任意随机字符串 # OPENCODE_SERVER_PASSWORD — 任意字符串（opencode serve 在 localhost 上忽略身份验证） # # 对于反向代理模式，还需要设置： # OMOTG_TLS_CERT_FILE= # OMOTG_TLS_KEY_FILE= ``` 参见 [配置](#配置) 以获取所有选项。 ### 4. 设置 systemd 服务 复制 systemd 服务文件： ```bash mkdir -p ~/.config/systemd/user ``` **opencode-serve.service** — 启动 OpenCode 无头服务器： ```ini [Unit] Description=OpenCode 无头服务器 (Serve) After=network-online.target Wants=network-online.target [Service] Type=simple ExecStart=/path/to/opencode serve --port 4096 Restart=on-failure RestartSec=5 NoNewPrivileges=true PrivateTmp=true [Install] WantedBy=default.target ``` **omotg.service** — 启动 OMOTG 桥接： ```ini [Unit] Description=OMOTG — Telegram ↔ OpenCode 桥接 After=network-online.target opencode-serve.service Wants=network-online.target BindsTo=opencode-serve.service [Service] Type=simple ExecStart=/path/to/omotg Restart=on-failure RestartSec=5 EnvironmentFile=%h/.config/omotg/env NoNewPrivileges=true ProtectHome=read-only ProtectSystem=full PrivateTmp=true [Install] WantedBy=default.target ``` 然后启用并启动： ```bash systemctl --user daemon-reload systemctl --user enable opencode-serve omotg systemctl --user start opencode-serve omotg ``` ## 配置 配置通过 `~/.config/omotg/env` 中的环境变量进行： ### 必需 | 变量 | 描述 | |----------|-------------| | `TELEGRAM_BOT_TOKEN` | 来自 [@BotFather](https://t.me/botfather) 的机器人令牌 | | `TELEGRAM_WEBHOOK_URL` | Telegram webhook 的公共 HTTPS URL（例如 `https://your.domain/webhook` 或 `https://your.domain:8443/webhook`） | | `TELEGRAM_SECRET_TOKEN` | 自定义秘密字符串，用于验证 webhook 请求 | | `OPENCODE_SERVER_PASSWORD` | OpenCode API 的密码（opencode serve 在 localhost 上忽略身份验证，但需要填写该字段） | ### 可选 | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `OPENCODE_SERVER_URL` | `http://127.0.0.1:4096` | OpenCode serve URL | | `OMOTG_WEBHOOK_PORT` | `8443` | Webhook 监听端口 | | `OMOTG_MCP_PORT` | `9090` | MCP SSE 服务器端口 | | `OMOTG_ALLOWED_CHAT_IDS` | （空 = 允许所有） | 以逗号分隔的 Telegram 聊天 ID | | `OMOTG_SESSION_TIMEOUT` | `300` | 会话超时（秒） | | `OMOTG_TLS_CERT_FILE` | `~/.config/omotg/webhook.crt` | TLS 证书路径（空 = 纯 HTTP，用于反向代理模式） | | `OMOTG_TLS_KEY_FILE` | `~/.config/omotg/webhook.key` | TLS 密钥路径（空 = 纯 HTTP，用于反向代理模式） | | `OMO_PROMETHEUS_BOT_TOKEN` | （无） | 辅助机器人令牌 → 路由到 Prometheus 代理（`/webhook/prometheus`） | | `OMO_ATLAS_BOT_TOKEN` | （无） | 辅助机器人令牌 → 路由到 Atlas 代理（`/webhook/atlas`） | | `OMO_HEPHAESTUS_BOT_TOKEN` | （无） | 辅助机器人令牌 → 路由到 Hephaestus 代理（`/webhook/hephaestus`） | ## 多机器人路由 OMOTG 可以同时运行多个 Telegram 机器人，每个机器人绑定到不同的 OMO 代理： | 机器人密钥 | 环境变量 | 路由到 | Webhook 路径 | |---------|---------|-----------|--------------| | 主要 | `TELEGRAM_BOT_TOKEN` | Sisyphus — ultraworker | `/webhook` | | Prometheus | `OMO_PROMETHEUS_BOT_TOKEN` | Prometheus — 计划生成器 | `/webhook/prometheus` | | Atlas | `OMO_ATLAS_BOT_TOKEN` | Atlas — 计划执行器 | `/webhook/atlas` | | Hephaestus | `OMO_HEPHAESTUS_BOT_TOKEN` | Hephaestus — 深度代理 | `/webhook/hephaestus` | - 主要机器人（`TELEGRAM_BOT_TOKEN`）是**必需的** — 它映射到 Sisyphus 以保持向后兼容。 - 辅助机器人是**可选的** — 仅为所需的代理设置 `OMO_*_BOT_TOKEN` 变量。 - 每个辅助机器人都有自己的 webhook 路径（`/webhook/<key>`）和自己的 Telegram webhook 注册。 - 机器人会话是隔离的 — 每个机器人都有自己的 `SessionMap`。 要添加辅助机器人，请设置其令牌并通过 `@BotFather` 注册 webhook： ``` https://your.domain.com/webhook/prometheus ``` > **注意**：Hephaestus 已配置，但需要上游 OpenCode 服务器修复（截至 2026-06-22 的服务器端 `UnknownError`）。请在解决后启用。 ## 用法 ### Telegram 命令 | 命令 | 描述 | |---------|-------------| | `/start` | 欢迎消息 | | `/help` | 显示可用命令 | | `/status` | 通过 OpenCode 检查服务器状态 | | `/deploy <env>` | 将应用程序部署到环境 | | `/logs [N]` | 显示服务器日志的最后 N 行（默认：50） | | `/session` | 显示当前会话信息 | | `/session new [text]` | 创建新会话（可选，带有第一个提示） | | `/session list` | 列出所有会话 | | `/session switch <id>` | 切换到不同会话 | | `/session delete <id>` | 删除会话 | | `/topic new <nama>` | 创建具有绑定会话的新论坛主题（仅限群组） | | `/topic close` | 关闭当前论坛主题（仅限群组） | | `/topic delete` | 永久删除当前论坛主题（仅限群组） | 任何非命令消息都使用当前会话转发到 OpenCode。 ### 群组和论坛主题 OMOTG 支持 **Telegram 超级群组论坛主题**。对话路由如下： - **主题中的消息** — OMOTG 在同一主题线程中回复，使用绑定到该主题的会话 - **常规消息** — OMOTG 在常规中使用群组的默认会话回复 - **私人聊天** — 像以前一样工作，带有持久会话 要创建专用工作区，请使用 `/topic new <nama>` — 这会创建一个新论坛主题，并将新的 OpenCode 会话绑定到它。使用 `/topic close` 或 `/topic delete` 清理主题及其会话。 每个 OpenCode 会话都映射到一个主题，在繁忙的群组中保持对话有序。 ### MCP 工具 通过 `http://127.0.0.1:9090/mcp/sse` 上的 MCP SSE 服务器可用： | 工具 | 描述 | |------|-------------| | `send_message` | 向 Telegram 聊天发送文本消息 | | `send_notification` | 向 Telegram 聊天发送通知 | ### OpenCode MCP 集成 将以下内容添加到您的 OpenCode 配置（`~/.config/opencode/opencode.json`）： ```json { "mcp": { "omotg": { "type": "remote", "url": "http://127.0.0.1:9090/mcp/sse" } } } ``` ## 架构 ### 独立 TLS ``` Telegram 应用 服务器 (VPS) OpenCode CLI │ │ │ │ POST /webhook │ │ │ ────────────────────→ omotg (端口 8443, TLS) │ │ │ │ │ │ │ │ POST /session │ │ │ │ POST /session/{id}/msg │ │ │ │ DELETE /session/{id} │ │ │ └───────────────────────→ opencode serve │ │ │ (端口 4096) │ │ │ │ sendMessage │ │ │ ←──────────────────── omotg (同步响应) │ │ │ │ │ │ │ │ MCP SSE 端点 │ │ │ │ http://127.0.0.1:9090 │ │ │ │ │ │ │ │ ←── MCP 工具 ────── OpenCode ``` ### 反向代理后面（推荐） ``` Telegram 应用 服务器 (VPS) OpenCode CLI │ │ │ │ POST /webhook │ │ │ ────────────────────→ Traefik (端口 443, Let's Encrypt) │ │ │ │ │ │ │ │ http://172.17.0.1:8443 │ │ │ ↓ │ │ │ omotg (纯 HTTP) │ │ │ │ │ │ │ │ POST /session │ │ │ │ POST /session/{id}/msg │ │ │ │ DELETE /session/{id} │ │ │ └───────────────────────────────→ opencode serve │ │ │ (端口 4096) │ │ │ │ sendMessage │ │ │ ←──────────────────── omotg (同步响应) │ │ │ │ │ │ │ │ MCP SSE 端点 │ │ │ │ http://127.0.0.1:9090 │ │ │ │ │ │ │ │ ←── MCP 工具 ────────────── OpenCode ``` ### 端口 | 端口 | 服务 | 绑定 | 协议 | |------|---------|------|----------| | 8443 | OMOTG Webhook | `0.0.0.0` | HTTPS (TLS) 或反向代理后面的纯 HTTP | | 9090 | OMOTG MCP SSE | `127.0.0.1` | HTTP/SSE | | 4096 | OpenCode Serve | `127.0.0.1` | HTTP/REST | ## 卸载 ### 通过 Homebrew ```bash brew uninstall omotg brew untap itokun99/omotg ``` 然后继续执行步骤 1-3 以清理服务和配置。 ### 手动 ### 1. 停止和禁用服务 ```bash systemctl --user stop omotg opencode-serve systemctl --user disable omotg opencode-serve ``` ### 2. 删除服务文件 ```bash rm ~/.config/systemd/user/omotg.service rm ~/.config/systemd/user/opencode-serve.service systemctl --user daemon-reload ``` ### 3. 注销 Telegram Webhook ```bash curl -X POST "https://api.telegram.org/bot<YOUR_TOKEN>/deleteWebhook" ``` ### 4. 删除二进制文件和配置 ```bash # 如果通过 Homebrew 安装： rm -rf ~/.config/omotg # 如果从源代码安装： rm -rf ~/.local/bin/omotg rm -rf ~/.config/omotg ``` ### 5. 删除 OpenCode MCP 配置（可选） 编辑 `~/.config/opencode/opencode.json` 并删除 `mcp` 部分中的 `omotg` 条目。 ## 故障排除 ### Webhook: "连接被拒绝" 在 getWebhookInfo 这是正常的，如果 OMOTG 已停止。启动服务： ```bash systemctl --user start omotg ``` ### "OpenCode 服务器不可用" OpenCode serve 未运行： ```bash systemctl --user status opencode-serve systemctl --user start opencode-serve ``` ### 检查日志 ```bash # OMOTG 日志 journalctl --user -u omotg -f # OpenCode serve 日志 journalctl --user -u opencode-serve -f ``` ## 安全注意事项 - 对于**独立模式**，webhook 服务器使用自签名证书。对于生产环境，请使用反向代理（Traefik/Caddy/Nginx）并使用 Let's Encrypt，并将 `OMOTG_TLS_CERT_FILE=` 和 `OMOTG_TLS_KEY_FILE=` 设置为空以禁用内部 TLS。 - 在**反向代理模式**中，OMOTG 绑定到 `0.0.0.0`，使用纯 HTTP。确保您的代理是唯一的公开可访问的端点，并且代理端口被防火墙保护。 - MCP 服务器仅绑定到 `127.0.0.1` — 不可从网络访问。 - 强烈建议使用聊天 ID 白名单。没有它，任何找到您的机器人的人都可以与 OpenCode 交互。 - 秘密令牌验证 webhook 请求确实来自 Telegram。 - 本地运行的 OpenCode serve 不强制执行身份验证；将其绑定到 `127.0.0.1`。 ## 许可证 **CC BY-NC 4.0 — 知识共享署名-非商业使用 4.0 国际** 版权 (c) 2026 Indrawan Lisanto 您可以在**仅限非商业用途**的情况下自由分享和改编此软件，但必须给予适当的署名。**严禁**在未获得明确许可的情况下进行商业使用。 参见 [LICENSE](LICENSE) 以获取完整条款。