1. 为什么要把 Telegram 接到本地 OpenCode 上先说清楚这套东西到底是什么。opencode-telegram-bot 是一个跑在你本机的 Node.js 小程序它做一件很克制的事监听 Telegram Bot 收到的消息转发给本地正在运行的 OpenCode Server再把执行结果回传到 Telegram 聊天窗口。整条链路是 Telegram App → Telegram Bot API → 本机 bot 进程 → 本地 OpenCode Server代码、项目文件、执行环境全部留在你自己的机器上不需要开放任何入站端口也不需要公网 IP。它适合谁我总结了三类人。第一类是个人项目只放在家里电脑上的开发者公司机器碰不到那台机器但灵感经常在通勤路上冒出来。第二类是习惯用手机记录想法的人与其记到备忘录回家再复现不如直接发一条消息让本地环境跑起来。第三类是不想把代码和 API Key 托管到任何云端服务、但又想享受远程操控便利的人。核心检索词先摆出来opencode-telegram-bot 是一个把 Telegram 变成本地 OpenCode 远程终端的桥接工具Node.js 20 是运行前提OpenCode CLI 是真正干活的引擎Telegram Bot Token 是通信凭证。四样东西凑齐链路就能跑通。我试过在手机上发一句「帮我看下 src/utils/date.ts 里 formatDate 的时区处理」十几秒后 Telegram 就返回了带 diff 的建议。整个过程没有 SSH、没有端口映射、没有把仓库推到任何地方。这种摩擦感的消失是这套方案最值钱的地方。不过要提醒一句Bot 只是控制层真正执行的是本地 OpenCode。所以你的电脑必须保持开机、OpenCode Server 必须持续运行否则消息发出去只会石沉大海。这也是后面要讲进程守护的原因。2. Node.js 环境与 TaoToken 统一通道前置准备在装 bot 之前先把两件基础设施搞定Node.js 运行环境和模型 API 通道。前者决定 bot 能不能跑后者决定 OpenCode 调用模型时走哪条路。Node.js 版本要求 20 以上。用 nvm 管理最省心# 安装 nvm如果还没有 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.zshrc # 安装并使用 Node.js 20 nvm install 20 nvm use 20 node -v # 应输出 v20.x.x确认 OpenCode 已安装which opencode opencode --version # 正常输出类似 # /Users/你的用户名/.opencode/bin/opencode # 1.x.x如果没装去 OpenCode 官方文档按平台脚本装一遍即可。接下来是模型通道。OpenCode 支持自定义 Provider把 Base URL 指向 TaoToken 的 API 端点就能用统一的 Key 调用多家模型省去在多个平台之间来回切换 Key 的麻烦。TaoToken 的 API 地址是https://taotoken.net/api官网入口在https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。先去控制台创建一个 API Key路径是https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteKey 管理页在https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite。拿到形如sk-xxxxxxxx的 Key 后先存好下一步配置要用。这里有个容易踩的坑很多人以为 bot 自己会调模型其实不是。bot 只负责转发消息真正调模型的是 OpenCode Server。所以 TaoToken 的 Key 要配在 OpenCode 这一侧而不是 bot 的.env里。搞混这一点后面会出现「bot 收到了消息但一直没回复」的现象。Telegram 侧的准备也顺手做完。打开 Telegram 搜索BotFather发送/newbot按提示设置名称和 username成功后它会返回一个 Token格式是123456789:AAxxxxxxxxxxxxxxxxxxxx。再搜索userinfobot发任意消息它会返回你的数字 User ID。这两个值后面配置向导会问。3. 可复制的 config.toml 与 settings.json 骨架这一节是全文的核心配置写对了后面基本一路顺。opencode-telegram-bot 首次运行会进配置向导但向导问的项比较多我建议直接手写配置文件可控性更强。先跑一次向导生成目录结构npx grinev/opencode-telegram-bot config向导会依次问界面语言选 6 是简体中文、Bot Token、Telegram User ID、OpenCode API URL、服务器用户名密码、模型 Provider、模型 ID。随便填完让它把目录建出来然后我们直接改文件。配置文件位置分平台macOS 在~/Library/Application Support/opencode-telegram-bot/Linux 在~/.config/opencode-telegram-bot/。目录下有两个关键文件.env存敏感凭证settings.json存界面和会话偏好。先看.env骨架# ~/Library/Application Support/opencode-telegram-bot/.env TELEGRAM_BOT_TOKEN123456789:AAxxxxxxxxxxxxxxxxxxxx TELEGRAM_ALLOWED_USER_ID664478408 OPENCODE_API_URLhttp://127.0.0.1:4096 OPENCODE_SERVER_USERNAMEopencode OPENCODE_SERVER_PASSWORDTELEGRAM_ALLOWED_USER_ID是白名单只有这个 ID 发的消息才会被响应务必填对否则别人拿到你的 bot username 也能驱动你的本地环境。再看settings.json骨架{ locale: zh-CN, model: { provider: taotoken, modelId: claude-sonnet-4-5 }, session: { autoCompress: true, compressThreshold: 0.8 }, ui: { showThinking: true, streamOutput: true } }provider和modelId要和 OpenCode 侧的 Provider 配置对上否则 bot 转发过去 OpenCode 找不到模型。现在配 OpenCode 侧的 TaoToken 通道。OpenCode 的配置文件通常在~/.config/opencode/config.tomlmacOS 也可能在~/Library/Application Support/opencode/。写入# ~/.config/opencode/config.toml [provider.taotoken] name TaoToken baseURL https://taotoken.net/api apiKey sk-你的TaoToken密钥 [provider.taotoken.models.claude-sonnet-4-5] name Claude Sonnet 4.5 [provider.taotoken.models.gpt-4o] name GPT-4o [default] provider taotoken model claude-sonnet-4-5三件套对齐检查Base URL 是https://taotoken.net/apiKey 是sk-开头那串Model ID 是claude-sonnet-4-5。这三样在 OpenCode 的 config.toml 和 bot 的 settings.json 里必须一致任何一处写错都会导致调用失败。配完启动 OpenCode Serveropencode serve # 默认监听 http://127.0.0.1:4096再启动 botnpx grinev/opencode-telegram-bot start # 看到 [INFO] Bot your_bot_username started! 即成功4. 一条消息触发本地命令的验证与结果确认配置写完不算跑通得用一条真实消息验证整条链路。这一步别跳过很多问题只有发消息才会暴露。打开 Telegram找到你创建的 bot发一句最简单的列出当前项目根目录的文件预期行为是bot 先回一条「正在处理」的状态消息然后 OpenCode 在本地执行几秒到几十秒后返回文件列表。如果开了streamOutput你会看到结果逐字刷出来。如果没反应先别急着改配置按顺序排查。第一步确认两个进程都在# 检查 OpenCode Server curl http://127.0.0.1:4096/health # 返回 {status:ok} 之类即正常 # 检查 bot 状态 npx grinev/opencode-telegram-bot status第二步看 bot 日志。前台启动的话日志直接打在终端后台启动的话看日志文件tail -f ~/Library/Logs/opencode-telegram-bot.log正常收到消息时日志里会出现类似Received message from user 664478408和Forwarding to OpenCode的行。如果只看到收到消息、没有转发说明OPENCODE_API_URL配错了。如果转发了但没结果问题在 OpenCode 侧去看opencode serve的输出。验证模型通道是否真的走了 TaoToken可以在 OpenCode 侧单独测一次curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: 回复 ok}] }返回带choices字段的 JSON 就说明 Key 和 Base URL 没问题。这一步能快速把「模型通道问题」和「bot 转发问题」分开。跑通之后可以试试更实用的动作比如发一张报错截图让 OpenCode 分析或者发一句「切到 build 模式把刚才那个函数重构成 async」。会话管理、项目切换、定时任务这些能力都是在链路通了之后才谈得上的。5. 本篇常见报错排查对照这一节把最容易撞上的几个报错摊开讲都是真实会遇到的。401 Unauthorized。出现在 OpenCode 调模型时日志里通常是provider returned 401。原因九成是 TaoToken Key 写错或过期。检查config.toml里apiKey有没有多余空格Key 是否还在有效期内。注意 Key 要配在 OpenCode 侧不是 bot 的.env。local proxy failed / connection refused。bot 日志里出现ECONNREFUSED 127.0.0.1:4096说明 OpenCode Server 没起来或者端口不是 4096。先curl http://127.0.0.1:4096/health确认起不来的话看opencode serve的报错。如果改了端口bot 的OPENCODE_API_URL要同步改。reading choices of undefined。这个报错说明 OpenCode 拿到了响应但结构里没有choices字段。常见原因是 Base URL 写成了https://taotoken.net少了/api或者模型 ID 在 TaoToken 侧不存在。把 Base URL 补全成https://taotoken.net/api模型 ID 换成确认可用的再试。OAuth / token expired。如果你之前用 OAuth 方式登录过某个 Provider切换成 TaoToken 后旧凭证可能还在缓存里捣乱。清掉 OpenCode 的凭证缓存目录通常在~/.config/opencode/下的 auth 相关文件重新用 API Key 方式配置。bot 收到消息但白名单不匹配。日志里出现Ignoring message from unauthorized user说明TELEGRAM_ALLOWED_USER_ID填错了。用userinfobot重新确认你的数字 ID注意别把 username 当成 ID 填进去。npx 找不到命令 / node 版本过低。报错SyntaxError: Unexpected token或requires Node.js 20说明当前 shell 用的 Node 版本不对。nvm use 20切一下或者检查which node指向的路径。排查顺序建议固定成先curl健康检查确认 Server 活着再看 bot 日志确认消息有没有转发最后单独curlTaoToken 确认模型通道。三步走完问题基本定位。6. 长期运行与接入文档入口链路跑通只是开始真正影响体验的是稳定性。Bot 和 OpenCode Server 两个进程都得常驻电脑重启后要能自动拉起。macOS 用 launchdLinux 用 systemd思路一样写一个 plist 或 unit 文件设RunAtLoad和KeepAlive日志重定向到固定文件方便排查。macOS 的 Launch Agent 放在~/Library/LaunchAgents/分别给opencode serve和 bot 各写一个 plistProgramArguments里填绝对路径。注意PATH环境变量要带上 nvm 和 opencode 的 bin 目录否则 launchd 启动时找不到命令。加载用launchctl load重启用unload再load。Linux 侧写两个 systemd user serviceExecStart分别指向 opencode 和 npxRestartalways保证崩溃自愈。systemctl --user enable之后登录即启动。安全上再强调两点。Bot Token 等同于 bot 的控制权别提交到 Git别分享配置文件权限保持默认。OpenCode Server 默认无密码但只监听 127.0.0.1本机以外访问不到如果机器有公网 IP 或处于共享网络务必设OPENCODE_SERVER_PASSWORD并在 bot 配置里对应填入。如果你在接入过程中卡在 Key 或通道配置上接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteAPI Key 管理在https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite。想先验证模型通不通可以直接在模型对话页试一条https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite。长期跑编码任务、需要稳定 Agent 通道的话Coding Plan 在https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite。最后给个实用技巧把常用的 prompt 做成 bot 的自定义命令比如「review 当前 diff」「跑一遍测试」在 Telegram 里一个斜杠就能触发比每次手打省事得多。定时任务也值得配一个比如每天早上让 OpenCode 汇总一下仓库的未提交改动通勤路上就能看。