你知道吗OpenCode 这类本地 AI 编程代理最大的痛点不是不好用而是被绑死在工位上。跑一个长时间的重构任务你人出门了任务跑挂了或者需要确认下一步你根本不知道。我实际用下来的方案是搭一个 Telegram Bot 来远程控制 OpenCode把任务状态推送、命令执行都接到手机上。这篇文章就完整记录我怎么从零搭起这套 opencode-telegram-bot 远程操控闭环的原理、配置、坑、优化一次讲清楚适合所有把 OpenCode 当日常主力工具的开发者参考。1. 为什么需要给 OpenCode 加一个远程遥控器1.1 OpenCode 本身很好但它有个天然的短板用过 OpenCode 的人都知道它本质上是一个跑在本地终端里的 AI 编程代理给你的感觉像是有一个坐在你旁边、随时能帮你写代码改代码的结对程序员。跟传统的 ChatGPT 网页版、直接用 Claude 这类聊天窗口完全不同OpenCode 最大的优势是它直接吃你本地仓库的上下文——能读文件、能跑命令、能帮你调用工具链相当于直接在你代码库的“手术台”上干活。但这个模式带来一个与生俱来的问题它跟你的人绑定在一起。它跑在你的电脑上你在工位前才能看到它在干什么它输出了一大段分析你得盯着终端才能读到它跑测试跑到一半卡住了你在手机面前干着急。我自己曾经遇到一个特别实际的场景一个 E2E 测试跑了二十多分钟我不敢去会议室开会因为跑挂了没人处理白白浪费一两个小时。很多人觉得那用 SSH 不就行了手机上有 Termius、Blink 这类工具可以连回电脑。理论上这条路可行但实际体验很糟糕手机屏幕看 OpenCode 的 TUI 界面本身就费劲那个界面设计是给大屏幕终端用的。而且 SSH 隧道需要你提前配置好内网穿透或者公网 IP安全性和稳定性另说。Telegram 的优势在于它本身就是为移动端消息交互设计的推送即时、消息界面简洁、Bot API 不需要你暴露本地端口只要 Bot 能发出请求你就能收到、能回复。1.2 我想要的远程控制不只是一条命令在动手找方案之前我先明确了一件事我想要的不是一个“远程终端控制台”因为那只是把 OpenCode 那个不适合手机操作的界面强行塞进手机里。我更想要的是一个“消息控制层”让它给我发关键通知我动动手指就能给它下达明确指令。这里有必要先看清楚 opencode-telegram-bot 这个项目的定位。它不是一个单纯的“命令转发器”它的核心设计思路是把 OpenCode 的交互消息做一次语义转换把 OpenCode 在终端里输出的那种长文本、结构化的信息转成适合在 Telegram 上快速浏览的短消息把你发在 Telegram 里的自然语言指令转成 OpenCode 能执行的动作。这就是它区别于简单 SSH 方案的关键。我实际体验下来它像一个翻译官不是一根水管。1.3 备选方案对比为什么最终选了它我调研过的远程控制 OpenCode 的方案大大小小有几种。一是最原始的方式物理层面避免远程。比如开个 tmux人在外面用 SSH 回来查看。最大的问题还是交互困难以及所有的判断决策还是要人回到终端去做这相当于你把办公桌搬到了手机上而且办公桌还是一块 6 英寸的屏幕。二是写一套自定义 webhook 服务自己搭后端接口 前端页面来调 OpenCode API。这个方案适合想深度定制的人但开发成本不低。你得自己处理消息推送、用户认证、界面适配还要维护一套独立服务等于项目还没用上 AI 提升效率先被工具开发消耗了一把。三是直接选择能云同步会话的方案让 OpenCode 跑在云端服务器上本地用网页访问。这种方案要求你有云服务器资源还要把代码和密钥传上去对很多人来说不是首选代码安全也是一个考量。而跑在本地、只是在需要时推送消息到手机的设计显然更适合代码敏感度高的项目。综合下来opencode-telegram-bot 的定位很清晰它面向的是“OpenCode 继续跑在我的本地机器上但我的人可以不在电脑前”的场景。它在 OpenCode 的 TUI 和你的手机之间放了一层消息代理把“看屏幕盯输出”变成“收消息做决策”这个体验才是质变。2. 动手前必须搞懂的三个核心组件2.1 OpenCode 侧不只是装一个 CLI 那么简单既然标题里同时出现了 OpenCode 和 opencode-telegram-bot那这两者之间的连接关系就值得先捋清楚。OpenCode 本身是一个开源项目你可以把它理解为 Claude Code 的一个替代品或者竞品同时也兼容了很多同类工具的思路。它支持多种模型后端Anthropic 的 Claude、OpenAI 兼容接口等支持 skill 机制也可以配置全局的 agent 行为。我最喜欢它的地方是它对本地操作的支持很宽松你可以允许它读写代码文件、在终端执行命令这样它才真正像一个代理而不只是一个聊天气泡。安装 OpenCode 本身很简单官方文档有提供一键脚本或者用包管理器。但在接 telegram bot 之前你必须先确认 OpenCode 能在本地正常跑通一个完整的 agent session这能避免后面排错时分不清问题是出在 OpenCode 还是 bot 侧。有一点必须提醒的是OpenCode 的“会话”概念和 Telegram 的“聊天”概念不是一一对应的。OpenCode 启动后可能是让你进入一个新的交互会话而 opencode-telegram-bot 在这个设计里可能会把每一次 Telegram 消息当成一条需要处理的命令或者维护某个后台运行的 OpenCode 会话。你在配置之前最好先想清楚你的使用场景是希望一个长期运行的 OpenCode 会话在后台待命等着你通过 Telegram 发号施令还是希望每次通过 Telegram 触发一个新的 OpenCode session 来处理指定任务这决定了你在配置 bot 和 OpenCode 时的具体做法也决定了对模型消耗的预期。2.2 Telegram Bot 侧拿到 Token 只是万里长征第一步Telegram Bot 的创建流程网上教程一大把核心就是找到 BotFather发一条/newbot按照提示设置名字和用户名最后得到一串类似110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw的 HTTP API Token。但这只是最简单的部分。你实际接 opencode-telegram-bot 的时候有几个细节经常被一笔带过我到后面才发现它们其实很关键。第一你要决定这个 Bot 是给谁用的。默认情况下Bot 可以被任何知道它用户名的人发起对话。但是你的 OpenCode 跑在你自己电脑上消息内容涉及代码权限如果不对所有人开放那等于把你仓库的钥匙挂在了大门口。Telegram Bot API 本身没有一个官方的“用户白名单”机制你必须在 bot 的逻辑层做限制或者依赖 opencode-telegram-bot 已有的配置项或环境变量指定允许的 chat_id。如果你没有在配置里限定只允许你自己的 Telegram 账号来发指令风险会非常高。这个点一定要在配置前就确认清楚而不是配完再补。第二Telegram Bot 有“隐私模式”的说法。你如果只是把 bot 加进群聊里让它响应群消息那就需要在 BotFather 里把隐私模式关掉否则群消息它一条都收不到。但如果你是自己跟 Bot 私聊就不存在这个问题。我自己的使用场景是纯私聊所以隐私模式没困扰我。第三网络连通性。Telegram Bot 要能正常收发消息你本地的网络环境需要能访问 Telegram API。这一点对不少地区的开发者来说是个实际障碍如果你遇到 bot 收不到消息或者发不出消息不一定是程序 bug很可能是网络连通问题。这里不做展开。2.3 桥接层opencode-telegram-bot 是怎么把两边黏起来的opencode-telegram-bot 不是一个官方项目它属于社区开源的个人/团队工具这一类。它的核心逻辑分成三块第一块是 Telegram 消息接收器。它会通过 Long Polling 方式持续监听 Telegram 服务器看有没有新消息发到你的 Bot。这个监听是长连接式的不需要你提供公网 HTTPS 地址。第二块是命令解释器。它接收到 Telegram 消息后会根据预设规则判断这是一条需要直接执行的 bash 命令是一条要转给 OpenCode 的指令还是查看任务状态的查询把它理解成一个弱化版的路由器也行。第三块是 OpenCode 执行器与反馈回路。它会调用你本地的 OpenCode 能力把输出的结果抓出来再通过 Telegram 发回给你的手机。这里我补充一个我实际的判断如果你要直接用这个开源项目它的功能边界跟你的需求可能会有出入。比如你可能希望它支持多会话或者希望它的消息格式能更适配某些模型的输出。遇到这些情况不要急着说服自己“能用就行”你要看清楚项目有没有提供扩展机制或者配置开关。如果实在不行fork 一份自己改也不复杂因为核心桥接逻辑就那么几百行。3. 安装与接入的完整实操记录3.1 环境准备清单在开始安装 opencode-telegram-bot 之前我建议先把环境梳理一遍。虽然不一定每项都用到但不至于到后面手忙脚乱。一台能跑 OpenCode 的电脑建议是 Linux 或者 macOS。Windows 虽然能跑但在本地会话和路径处理上会有额外的坑。OpenCode CLI 已经安装好并且确认在非交互模式下能正常输出。一个 Telegram 账号并且你创建好了一个 Bot拿到了 Token。如果你要把 Bot 部署到系统服务里最好有 systemd 的基本知识如果只是临时跑起来测试有 Node.js 或者 Python 环境就够了根据你 clone 的仓库代码语言而定。Git用于拉取项目代码。我自己的环境是 macOS Node.js 20 LTSOpenCode 跑在本地 PATH 里Telegram Bot 是全程私聊。这个组合比较省事。3.2 拉取项目并安装依赖项目本身的安装我分成了三步走。第一步拉取源码。你用git clone把项目拉到本地某个目录我习惯放在~/tools/opencode-telegram-bot而不是项目代码目录因为它是工具不是项目的一部分隔离了比较好。第二步安装依赖。这个要看项目是用什么语言写的。如果项目是 Node.js 的那在根目录执行npm install就行。如果是 Python 的那就是pip install -r requirements.txt。第三步确认配置文件模板。大多数类似的 bot 项目都会提供一个.env.example或者config.example你需要复制一份改名成实际的配置文件然后填入自己的参数。这里是最容易出错的地方因为不同的作者对配置项的命名习惯不同。有的叫TELEGRAM_BOT_TOKEN有的叫BOT_TOKEN有的用ALLOWED_USER_IDS有的可能定义成AUTHORIZED_CHAT_ID。你不看清楚直接套网上的教程很容易填错位置。这也是我为什么说自己的项目自己先读一遍 README 是最靠谱的。3.3 配置里的几个关键参数剖析以我接过的几个类似项目来看核心配置参数一般绕不开这几项BOT_TOKEN你的 Bot 密钥相当于这个远程控制器的钥匙。不能泄露也不能提交到 Git。ALLOWED_CHAT_ID或类似字段限定谁能控制你的 OpenCode通常是你的个人 chat_id。获取 chat_id 的方式也简单直接给 Bot 发条消息然后去 Telegram API 的getUpdates接口看就行了。OPENCODE_BIN或COMMAND_PREFIX指定 OpenCode 的可执行文件路径或者是否需要加前缀执行。WORKING_DIRECTORYOpenCode 默认在哪个目录下执行任务。这个要格外小心因为远程命令是在这个目录层面跑的。如果你把工作目录设置成/又不小心让 AI 执行了什么清理命令后果会很麻烦。建议单独建一个项目目录或者明确到你希望 AI 操作的某个仓库名下。LANGUAGE或LOCALE如果你希望 bot 回复的语言统一有些项目支持配语言包。这里我想重点展开一个小点就是ALLOWED_CHAT_ID和白名单的关系。由于 Telegram Bot 不像 SSH 那样天然有账号体系每一个给 bot 发消息的人只要拿到了 bot 的链接都能在 Telegram 里跟它对话。如果 bot 不校验用户的身份那任何发现你这个 bot 用户名的人都可以向你的本地 OpenCode 下发指令——包括让它执行 shell 命令。那这个 Bot 就相当于一个没有密码的远程控制端口任何人都能通过 Telegram 往你的机器上下发操作指令。所以白名单不是可选优化项而是安全底线。你自己是唯一用户的话白名单里就一个 chat_id如果是团队使用那就把核心开发者的 chat_id 都塞进去。3.4 测试启动先让它跑起来再说依赖装好、配置填好后我建议先不要直接后台运行而是在终端前台启动 bot这样能看到日志。node index.js # 假设这是入口文件 # 或者 python main.py # 或者按项目 README 里写的启动命令来启动成功的标志是能看到类似 “Bot started” 或 “polling…” 的日志。这时候在 Telegram 里找到你的 Bot点 Start给它发一条最简单的消息看看有没有响应。我第一次测试的时候犯了个低级错误启动 bot 的终端窗口是在我前一个 SSH 会话里我人已经不在那个终端了结果 bot 进程随着 SSH 会话断开被系统杀掉我发了消息完全没反应。排查了半天才发现是自己把它跑在了不持久的会话里。后来我改用了 systemd 服务来托管才彻底解决。如果你测试时发现 bot 没有任何反应优先排查三件事Bot Token 是否复制错了尤其是末尾有没有多空格网络层是否能正常访问 Telegram APIbot 是否真的在持续运行不报错。三件事按顺序查基本能解决大部分问题。4. 实际用起来之后的体验与调优4.1 一条指令从 Telegram 到 OpenCode 的完整旅程现在假设白名单配置完成bot 也在稳定运行我来追踪一条指令的完整执行链路。我通过 Telegram 给我的 bot 发一句帮我看看项目里有没有未使用的 import。这条消息经过 Telegram 服务器通过 Long Polling 被本地的 bot 进程接收。bot 进程识别出这条消息不是内建的快捷命令于是把它作为一条任务下发到 OpenCode。OpenCode 接收到任务后会在你设定的工作目录里开始分析代码、执行搜索。处理完之后bot 进程把结果整理成文本发回我的手机。这套链路里最花时间的环节基本都出在 OpenCode 那一层因为模型推理需要时间如果你叠加了比较大的代码扫描任务那可能是几十秒甚至几分钟。Telegram 的消息传输本身是秒级的基本可以忽略不计。所以如果一条指令发出去之后超过两分钟没动静大概率不是链路断了而是 OpenCode 那侧还在处理。这时我一般会再发一条“status”或者“进度如何”之类的内置查询看能不能拿到中间状态。4.2 什么任务适合交给远程 OpenCode什么不适合用了几个星期之后我形成了一个经验性判断。适合远程操控的场景有这几类跑 CI 前先让 AI 静态检查一下代码风格休息前丢一个“重构 xxx 模块并补充测试”的长任务出门在外临时让 AI 查一个配置在哪个文件里让 AI 把一个大文件的函数拆成多个模块并逐个验证。这些任务的共性是目标明确、不需要太频繁的人工确认、失败了重跑成本不算太高。不适合远程操控的场景则包括需要多轮深度交互、依赖你实时给出大量设计决策的任务——AI 连续问你五个问题你在手机上逐条打字回答效率反而比坐电脑前低很多。还有就是涉及敏感密钥操作的任务比如让 AI 修改部署凭证、云服务密钥任何一步失误都可能造成比本地操作更大的损失。这一点值得展开讲一下因为它是远程控制 AI 编程代理的核心风险判断。本地使用 OpenCode 时你和 AI 在同一台机器上你随时能看到它执行了什么命令CtrlC 也能强制中断它。远程使用就完全不同了你隔着一个 Telegram 通道消息是异步的执行是滞后的。如果 AI 误判了你的意图执行了破坏性命令你可能过几分钟才收到报错通知。因此我给自己定了一个规矩任何涉及 git 强制推送、文件删除、大规模替换的任务默认不在远程模式下交给 AI 去跑。换个直观的说法远程操控 AI 编程代理就像通过手机遥控扫地机器人——你能让它去扫地但别让它在你不在家的时候执行可能把猫砂打翻的复杂操作。4.3 消息格式与可读性的二次优化原版 opencode-telegram-bot 的消息格式设计在我看来只能打 70 分。它把 OpenCode 的主要输出直接转为文本发出来好处是信息完整、不丢细节坏处是太长了。想象一下你手机收到一条一万字的代码分析报告滑动阅读是一件很消耗耐心的事情。我自己琢磨了一套优化方案核心思路是“结果导向、控制详略”。第一步在 bot 的适配层增加一层输出摘要逻辑。让模型在生成任务回复时要求它先给结论再给依据。比如 “共发现 7 个文件包含未使用的 import重点文件是 src/utils.js、src/api/client.js”然后再附上具体的行号和内容片段。这样一来我在手机上 30 秒能掌握核心信息如果需要对某个文件深入处理再单独发指令让它展开。第二步对超长输出做折叠处理。Telegram 的消息虽然没有强制的长度上限但超过一定长度之后手机端查看历史记录非常卡。我一般的做法是超过 3000 字符就把完整内容写入本地日志文件Telegram 里只给一个简短摘要和日志路径。第三步给固定的高频状态配置默认回复模板。比如任务开始、任务完成、任务失败这三种情况使用一致的消息格式任务名、执行时间、结果状态、下一步建议。这样在手机上扫一眼就能对当前任务情况心里有数不用每次都去翻上下文。4.4 多任务并发别让它成为一匹脱缰的野马OpenCode 作为一个交互式代理默认其实是单会话的。你通过 bot 传进去一条任务它正在执行的时候如果你又发了第二条任务进去到底会发生什么这取决于项目的设计。有的实现会做队列把第二条任务排在待办区等第一条结束了再执行有的实现则直接报错或者丢消息。我自己的使用习惯是不并发。虽然有队列的实现能兜底但 OpenCode 的执行本来就是上下文敏感的两个任务之间如果操作的是同一个 repo容易互相污染。比如任务 A 在重构文件任务 B 也在改同一个文件最后结果很容易变成一场灾难。如果真的有多任务并存的需求正确做法是开多个工作目录配合容器或者虚拟机隔离不同的执行环境然后用不同前缀区分指令把任务路由到对应的 OpenCode 会话里。这是进阶玩法等你把单会话用成熟了再尝试也不迟。5. 部署层优化从“跑起来”到“跑得稳”5.1 用 systemd 把它变成开机自启的后台服务前面提到我最初把 bot 跑在前台终端里一个 SSH 断开它就死了。这个方法只适合做连通性测试不适合做真实服务。我后来选择了用 systemd 托管。一个最小化的 systemd service 文件长这样[Unit] DescriptionOpenCode Telegram Bot Afternetwork-online.target [Service] Typesimple User你的系统用户名 WorkingDirectory/home/你的用户名/tools/opencode-telegram-bot EnvironmentFile/home/你的用户名/tools/opencode-telegram-bot/.env ExecStart/usr/bin/node /home/你的用户名/tools/opencode-telegram-bot/index.js Restartalways RestartSec5 [Install] WantedBymulti-user.target这里我踩过一个坑必须单独提一下EnvironmentFile这个字段如果你的.env文件里某个值包含了特殊字符例如#或空格systemd 的解析方式可能跟你预期的不同。所以如果发现进程起不来先检查.env文件里的值有没有需要转义的字符。另一个建议是给 bot 单独创建一个低权限系统用户不要直接用它跑在你的主用户下尤其是在远程控制场景下。如果 bot 进程被攻破一个低权限用户能把破坏范围限制在它自己的工作目录里不至于让你整个账号沦陷。配置好之后执行sudo systemctl daemon-reload sudo systemctl enable opencode-telegram-bot sudo systemctl start opencode-telegram-bot后续的查看日志、重启服务就用journalctl -u opencode-telegram-bot -f和systemctl restart opencode-telegram-bot。这两个命令我会用得非常频繁尤其是改完代码或配置之后。5.2 日志与审计远程控制必须有迹可循远程操控本地 AI 代理除了便利性还有一个安全和审计问题。本地敲命令终端里天然有历史记录通过 Telegram 远程控制命令的发出和执行过程都应该有持久化的日志。我的建议是在 bot 的日志输出中至少记录以下字段消息来源 chat_id、收到时间、消息全文脱敏后、路由到的处理函数、执行结果状态、耗时。这样万一哪次 AI 做了什么异常动作你可以回溯到是哪一个用户、在哪一条指令里触发的。我自己是把日志接入到了系统日志里由journald统一管理然后配合定时任务做日志轮转防止长期运行把磁盘吃掉。如果你有服务端日志采集的习惯也可以直接往日志系统里扔。核心原则只有一条这个系统要能回答“谁在什么时候让本地 AI 做了什么”的问题。5.3 断线重连与异常自愈机制Telegram Bot 的 Long Polling 模式本质上是一条长连接。它最大的问题是如果网络掉线或者 Telegram 服务器端连接超时bot 进程可能不会自动恢复表现在外面就是“Bot 失联了”。虽然很多 Bot 框架自带了重连机制但实现程度良莠不齐。为了提升稳定性我在 systemd 里配置了Restartalways让进程崩溃后自动拉起。但这还不够因为进程没有退出只是它的长轮询循环卡死了systemd 是不会知道需要重启的。这种情况下需要一种“看门狗”思路。我采用的方案是定时健康巡检用一个 cron 任务每隔 5 分钟通过getMe接口检查 bot 是否正常响应如果连续两次失败就调用 systemd 重启服务。这个巡检本身不复杂但能很有效地避免“进程还在、服务实际不可用”的假死状态。类似的思路你如果不想自己写也可以在进程管理器层面解决比如 pm2 的max_memory_restart配合 cron 重启能缓解一部分问题。不过必须承认这类机器人服务要做到 99.9% 的可用性是需要花不少心思在运维上的。如果只是个人使用我认为做到“进程崩溃能自动拉起 手动重启足够熟练”就已经超过大多数人能接受的稳定线了。6. 常见问题与排查技巧实录6.1 Bot 收不到任何消息这是最长遇到的一个问题。我的排查路径是按照这个顺序来的第一步确认 bot 进程还活着。查看日志看有没有报错尤其是权限类的错误。第二步确认你的消息确实发给了正确的 Bot。Telegram 私聊界面里如果出现的是一个类似网页预览的窗口而不是聊天输入框说明你可能打开的不是真正的 Bot 聊天。第三步查看getUpdates。有时候 bot 进程崩溃后重新启动会丢失掉之前已经拉取过的事件导致你的测试消息被跳过。手动通过浏览器访问https://api.telegram.org/bot你的TOKEN/getUpdates看看里面有没有你发的消息记录。第四步检查网络连通性。如果在服务器上直接 curl Telegram API 超时那问题就出在网络层。6.2 OpenCode 任务执行成功但 Telegram 没收到结果这个问题的典型表现是bot 能收到命令OpenCode 也确实执行了但结果没有推送回来。我之前遇到过一次原因让我印象很深刻OpenCode 进程在输出时使用了 ANSI 转义码bot 原样捕获并试图通过 Telegram 发送导致消息里包含大量不可见字符。一部分聊天客户端在解析异常字符时会直接不显示。解决方案就是在 bot 捕获 OpenCode 输出之后做一次清洗去掉 ANSI 控制序列再发送。如果你直接用 shell 管道重定向输出也可以考虑加上--no-color或类似参数让 OpenCode 以纯文本模式输出。遇到消息变成空白或乱码时优先检查这一环。6.3 白名单失效非授权用户依然能触发命令我实测时遇到过白名单逻辑有缺陷的情况项目里的白名单校验只发生在处理特定命令时对于某些不以斜杠开头的普通消息根本没有进入校验分支任何用户都能直接给 OpenCode 发指令。这个漏洞很隐蔽因为表面看起来你已经配置好了ALLOWED_CHAT_ID。排查方法是翻看 bot 的源码从消息入口处追踪校验逻辑到底被放到了哪个环节。如果项目太老或者作者没有考虑周全稳妥的做法是自己加一道全局拦截所有非白名单 chat_id 发来的消息一律在入口处直接丢弃不进入后续处理流程。6.4 一条指令触发两次执行Telegram Bot 的消息确认机制里有一个细节如果你的 bot 处理一条消息的耗时超过了 Long Polling 的超时时间或者处理过程中进程意外重启了Telegram 服务器会认为这条消息没有被成功接收于是在下次连接时重新推送同一条消息。结果就是你的 OpenCode 可能把同一任务跑了两遍。解决思路有两个层面。应用层面给每条消息做去重记录最近处理过的 message_id如果新收到的消息 id 已经存在就直接忽略。这需要在 bot 里维护一个小型缓存或 Redis对个人工具来说缓存在内存里就够了。操作层面避免执行特别耗时且不可并行的任务如果任务本身就要跑十几分钟那就要有“它可能执行了两次”的心理预期。6.5 安全加固的经验补充最后聊几句容易被新手忽略的安全配置。第一不要把敏感信息通过 Telegram 明文发送到手机Telegram 的私聊有端到端加密但 Bot API 属于另外一套机制Bot 和服务器之间的传输并不默认端到端加密代码片段、API 密钥这类内容要谨慎。第二定期轮换你的 Bot Token。如果换了 Token旧 Token 会立即失效可以避免因为 token 泄露导致的被控制风险。第三如果你在多人协作环境里使用同一个 OpenCode 实例建议给 OpenCode 增加独立的系统账号和目录权限不让它裸奔在你的主目录中。在远程控制场景里多一道权限栅栏就多一分安心。写在最后的一点个人经验这套 opencode-telegram-bot 方案我实际跑了两周之后最明显的变化不是代码效率提升了多少而是“能离开电脑”的安全感提升了。以前我开一个长时间运行的 OpenCode 任务基本就要守在电脑前刷手机打发时间现在我可以把任务交给它自己去处理别的杂事有结果了手机上会收到推送。真正的价值不在于你把 AI 编程代理搬到了口袋里而在于它给了你一个可以随时问一句“现在项目什么状态”的远程窗口。如果这个项目后续还能继续扩展我建议可以关注两个方向一是集成更多的 AI Agent 事件推送比如把 git 提交、CI 构建状态也接入到同一条 Telegram 通道里让工作信息流聚合成一个单一入口另一个方向是支持通过 Telegram 语音消息下发任务让语音转文字后直接变成 OpenCode 的指令。对于一个懂行的开发者来说这些方向实现起来难度都不大但它们带来的便利度会是台阶式的提升。希望这篇记录能给你一些可以直接落地的经验少走几个我走过的弯路。 用 Telegram Bot 远程操控 OpenCode：本地 AI 编程代理的移动控制方案
你知道吗OpenCode 这类本地 AI 编程代理最大的痛点不是不好用而是被绑死在工位上。跑一个长时间的重构任务你人出门了任务跑挂了或者需要确认下一步你根本不知道。我实际用下来的方案是搭一个 Telegram Bot 来远程控制 OpenCode把任务状态推送、命令执行都接到手机上。这篇文章就完整记录我怎么从零搭起这套 opencode-telegram-bot 远程操控闭环的原理、配置、坑、优化一次讲清楚适合所有把 OpenCode 当日常主力工具的开发者参考。1. 为什么需要给 OpenCode 加一个远程遥控器1.1 OpenCode 本身很好但它有个天然的短板用过 OpenCode 的人都知道它本质上是一个跑在本地终端里的 AI 编程代理给你的感觉像是有一个坐在你旁边、随时能帮你写代码改代码的结对程序员。跟传统的 ChatGPT 网页版、直接用 Claude 这类聊天窗口完全不同OpenCode 最大的优势是它直接吃你本地仓库的上下文——能读文件、能跑命令、能帮你调用工具链相当于直接在你代码库的“手术台”上干活。但这个模式带来一个与生俱来的问题它跟你的人绑定在一起。它跑在你的电脑上你在工位前才能看到它在干什么它输出了一大段分析你得盯着终端才能读到它跑测试跑到一半卡住了你在手机面前干着急。我自己曾经遇到一个特别实际的场景一个 E2E 测试跑了二十多分钟我不敢去会议室开会因为跑挂了没人处理白白浪费一两个小时。很多人觉得那用 SSH 不就行了手机上有 Termius、Blink 这类工具可以连回电脑。理论上这条路可行但实际体验很糟糕手机屏幕看 OpenCode 的 TUI 界面本身就费劲那个界面设计是给大屏幕终端用的。而且 SSH 隧道需要你提前配置好内网穿透或者公网 IP安全性和稳定性另说。Telegram 的优势在于它本身就是为移动端消息交互设计的推送即时、消息界面简洁、Bot API 不需要你暴露本地端口只要 Bot 能发出请求你就能收到、能回复。1.2 我想要的远程控制不只是一条命令在动手找方案之前我先明确了一件事我想要的不是一个“远程终端控制台”因为那只是把 OpenCode 那个不适合手机操作的界面强行塞进手机里。我更想要的是一个“消息控制层”让它给我发关键通知我动动手指就能给它下达明确指令。这里有必要先看清楚 opencode-telegram-bot 这个项目的定位。它不是一个单纯的“命令转发器”它的核心设计思路是把 OpenCode 的交互消息做一次语义转换把 OpenCode 在终端里输出的那种长文本、结构化的信息转成适合在 Telegram 上快速浏览的短消息把你发在 Telegram 里的自然语言指令转成 OpenCode 能执行的动作。这就是它区别于简单 SSH 方案的关键。我实际体验下来它像一个翻译官不是一根水管。1.3 备选方案对比为什么最终选了它我调研过的远程控制 OpenCode 的方案大大小小有几种。一是最原始的方式物理层面避免远程。比如开个 tmux人在外面用 SSH 回来查看。最大的问题还是交互困难以及所有的判断决策还是要人回到终端去做这相当于你把办公桌搬到了手机上而且办公桌还是一块 6 英寸的屏幕。二是写一套自定义 webhook 服务自己搭后端接口 前端页面来调 OpenCode API。这个方案适合想深度定制的人但开发成本不低。你得自己处理消息推送、用户认证、界面适配还要维护一套独立服务等于项目还没用上 AI 提升效率先被工具开发消耗了一把。三是直接选择能云同步会话的方案让 OpenCode 跑在云端服务器上本地用网页访问。这种方案要求你有云服务器资源还要把代码和密钥传上去对很多人来说不是首选代码安全也是一个考量。而跑在本地、只是在需要时推送消息到手机的设计显然更适合代码敏感度高的项目。综合下来opencode-telegram-bot 的定位很清晰它面向的是“OpenCode 继续跑在我的本地机器上但我的人可以不在电脑前”的场景。它在 OpenCode 的 TUI 和你的手机之间放了一层消息代理把“看屏幕盯输出”变成“收消息做决策”这个体验才是质变。2. 动手前必须搞懂的三个核心组件2.1 OpenCode 侧不只是装一个 CLI 那么简单既然标题里同时出现了 OpenCode 和 opencode-telegram-bot那这两者之间的连接关系就值得先捋清楚。OpenCode 本身是一个开源项目你可以把它理解为 Claude Code 的一个替代品或者竞品同时也兼容了很多同类工具的思路。它支持多种模型后端Anthropic 的 Claude、OpenAI 兼容接口等支持 skill 机制也可以配置全局的 agent 行为。我最喜欢它的地方是它对本地操作的支持很宽松你可以允许它读写代码文件、在终端执行命令这样它才真正像一个代理而不只是一个聊天气泡。安装 OpenCode 本身很简单官方文档有提供一键脚本或者用包管理器。但在接 telegram bot 之前你必须先确认 OpenCode 能在本地正常跑通一个完整的 agent session这能避免后面排错时分不清问题是出在 OpenCode 还是 bot 侧。有一点必须提醒的是OpenCode 的“会话”概念和 Telegram 的“聊天”概念不是一一对应的。OpenCode 启动后可能是让你进入一个新的交互会话而 opencode-telegram-bot 在这个设计里可能会把每一次 Telegram 消息当成一条需要处理的命令或者维护某个后台运行的 OpenCode 会话。你在配置之前最好先想清楚你的使用场景是希望一个长期运行的 OpenCode 会话在后台待命等着你通过 Telegram 发号施令还是希望每次通过 Telegram 触发一个新的 OpenCode session 来处理指定任务这决定了你在配置 bot 和 OpenCode 时的具体做法也决定了对模型消耗的预期。2.2 Telegram Bot 侧拿到 Token 只是万里长征第一步Telegram Bot 的创建流程网上教程一大把核心就是找到 BotFather发一条/newbot按照提示设置名字和用户名最后得到一串类似110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw的 HTTP API Token。但这只是最简单的部分。你实际接 opencode-telegram-bot 的时候有几个细节经常被一笔带过我到后面才发现它们其实很关键。第一你要决定这个 Bot 是给谁用的。默认情况下Bot 可以被任何知道它用户名的人发起对话。但是你的 OpenCode 跑在你自己电脑上消息内容涉及代码权限如果不对所有人开放那等于把你仓库的钥匙挂在了大门口。Telegram Bot API 本身没有一个官方的“用户白名单”机制你必须在 bot 的逻辑层做限制或者依赖 opencode-telegram-bot 已有的配置项或环境变量指定允许的 chat_id。如果你没有在配置里限定只允许你自己的 Telegram 账号来发指令风险会非常高。这个点一定要在配置前就确认清楚而不是配完再补。第二Telegram Bot 有“隐私模式”的说法。你如果只是把 bot 加进群聊里让它响应群消息那就需要在 BotFather 里把隐私模式关掉否则群消息它一条都收不到。但如果你是自己跟 Bot 私聊就不存在这个问题。我自己的使用场景是纯私聊所以隐私模式没困扰我。第三网络连通性。Telegram Bot 要能正常收发消息你本地的网络环境需要能访问 Telegram API。这一点对不少地区的开发者来说是个实际障碍如果你遇到 bot 收不到消息或者发不出消息不一定是程序 bug很可能是网络连通问题。这里不做展开。2.3 桥接层opencode-telegram-bot 是怎么把两边黏起来的opencode-telegram-bot 不是一个官方项目它属于社区开源的个人/团队工具这一类。它的核心逻辑分成三块第一块是 Telegram 消息接收器。它会通过 Long Polling 方式持续监听 Telegram 服务器看有没有新消息发到你的 Bot。这个监听是长连接式的不需要你提供公网 HTTPS 地址。第二块是命令解释器。它接收到 Telegram 消息后会根据预设规则判断这是一条需要直接执行的 bash 命令是一条要转给 OpenCode 的指令还是查看任务状态的查询把它理解成一个弱化版的路由器也行。第三块是 OpenCode 执行器与反馈回路。它会调用你本地的 OpenCode 能力把输出的结果抓出来再通过 Telegram 发回给你的手机。这里我补充一个我实际的判断如果你要直接用这个开源项目它的功能边界跟你的需求可能会有出入。比如你可能希望它支持多会话或者希望它的消息格式能更适配某些模型的输出。遇到这些情况不要急着说服自己“能用就行”你要看清楚项目有没有提供扩展机制或者配置开关。如果实在不行fork 一份自己改也不复杂因为核心桥接逻辑就那么几百行。3. 安装与接入的完整实操记录3.1 环境准备清单在开始安装 opencode-telegram-bot 之前我建议先把环境梳理一遍。虽然不一定每项都用到但不至于到后面手忙脚乱。一台能跑 OpenCode 的电脑建议是 Linux 或者 macOS。Windows 虽然能跑但在本地会话和路径处理上会有额外的坑。OpenCode CLI 已经安装好并且确认在非交互模式下能正常输出。一个 Telegram 账号并且你创建好了一个 Bot拿到了 Token。如果你要把 Bot 部署到系统服务里最好有 systemd 的基本知识如果只是临时跑起来测试有 Node.js 或者 Python 环境就够了根据你 clone 的仓库代码语言而定。Git用于拉取项目代码。我自己的环境是 macOS Node.js 20 LTSOpenCode 跑在本地 PATH 里Telegram Bot 是全程私聊。这个组合比较省事。3.2 拉取项目并安装依赖项目本身的安装我分成了三步走。第一步拉取源码。你用git clone把项目拉到本地某个目录我习惯放在~/tools/opencode-telegram-bot而不是项目代码目录因为它是工具不是项目的一部分隔离了比较好。第二步安装依赖。这个要看项目是用什么语言写的。如果项目是 Node.js 的那在根目录执行npm install就行。如果是 Python 的那就是pip install -r requirements.txt。第三步确认配置文件模板。大多数类似的 bot 项目都会提供一个.env.example或者config.example你需要复制一份改名成实际的配置文件然后填入自己的参数。这里是最容易出错的地方因为不同的作者对配置项的命名习惯不同。有的叫TELEGRAM_BOT_TOKEN有的叫BOT_TOKEN有的用ALLOWED_USER_IDS有的可能定义成AUTHORIZED_CHAT_ID。你不看清楚直接套网上的教程很容易填错位置。这也是我为什么说自己的项目自己先读一遍 README 是最靠谱的。3.3 配置里的几个关键参数剖析以我接过的几个类似项目来看核心配置参数一般绕不开这几项BOT_TOKEN你的 Bot 密钥相当于这个远程控制器的钥匙。不能泄露也不能提交到 Git。ALLOWED_CHAT_ID或类似字段限定谁能控制你的 OpenCode通常是你的个人 chat_id。获取 chat_id 的方式也简单直接给 Bot 发条消息然后去 Telegram API 的getUpdates接口看就行了。OPENCODE_BIN或COMMAND_PREFIX指定 OpenCode 的可执行文件路径或者是否需要加前缀执行。WORKING_DIRECTORYOpenCode 默认在哪个目录下执行任务。这个要格外小心因为远程命令是在这个目录层面跑的。如果你把工作目录设置成/又不小心让 AI 执行了什么清理命令后果会很麻烦。建议单独建一个项目目录或者明确到你希望 AI 操作的某个仓库名下。LANGUAGE或LOCALE如果你希望 bot 回复的语言统一有些项目支持配语言包。这里我想重点展开一个小点就是ALLOWED_CHAT_ID和白名单的关系。由于 Telegram Bot 不像 SSH 那样天然有账号体系每一个给 bot 发消息的人只要拿到了 bot 的链接都能在 Telegram 里跟它对话。如果 bot 不校验用户的身份那任何发现你这个 bot 用户名的人都可以向你的本地 OpenCode 下发指令——包括让它执行 shell 命令。那这个 Bot 就相当于一个没有密码的远程控制端口任何人都能通过 Telegram 往你的机器上下发操作指令。所以白名单不是可选优化项而是安全底线。你自己是唯一用户的话白名单里就一个 chat_id如果是团队使用那就把核心开发者的 chat_id 都塞进去。3.4 测试启动先让它跑起来再说依赖装好、配置填好后我建议先不要直接后台运行而是在终端前台启动 bot这样能看到日志。node index.js # 假设这是入口文件 # 或者 python main.py # 或者按项目 README 里写的启动命令来启动成功的标志是能看到类似 “Bot started” 或 “polling…” 的日志。这时候在 Telegram 里找到你的 Bot点 Start给它发一条最简单的消息看看有没有响应。我第一次测试的时候犯了个低级错误启动 bot 的终端窗口是在我前一个 SSH 会话里我人已经不在那个终端了结果 bot 进程随着 SSH 会话断开被系统杀掉我发了消息完全没反应。排查了半天才发现是自己把它跑在了不持久的会话里。后来我改用了 systemd 服务来托管才彻底解决。如果你测试时发现 bot 没有任何反应优先排查三件事Bot Token 是否复制错了尤其是末尾有没有多空格网络层是否能正常访问 Telegram APIbot 是否真的在持续运行不报错。三件事按顺序查基本能解决大部分问题。4. 实际用起来之后的体验与调优4.1 一条指令从 Telegram 到 OpenCode 的完整旅程现在假设白名单配置完成bot 也在稳定运行我来追踪一条指令的完整执行链路。我通过 Telegram 给我的 bot 发一句帮我看看项目里有没有未使用的 import。这条消息经过 Telegram 服务器通过 Long Polling 被本地的 bot 进程接收。bot 进程识别出这条消息不是内建的快捷命令于是把它作为一条任务下发到 OpenCode。OpenCode 接收到任务后会在你设定的工作目录里开始分析代码、执行搜索。处理完之后bot 进程把结果整理成文本发回我的手机。这套链路里最花时间的环节基本都出在 OpenCode 那一层因为模型推理需要时间如果你叠加了比较大的代码扫描任务那可能是几十秒甚至几分钟。Telegram 的消息传输本身是秒级的基本可以忽略不计。所以如果一条指令发出去之后超过两分钟没动静大概率不是链路断了而是 OpenCode 那侧还在处理。这时我一般会再发一条“status”或者“进度如何”之类的内置查询看能不能拿到中间状态。4.2 什么任务适合交给远程 OpenCode什么不适合用了几个星期之后我形成了一个经验性判断。适合远程操控的场景有这几类跑 CI 前先让 AI 静态检查一下代码风格休息前丢一个“重构 xxx 模块并补充测试”的长任务出门在外临时让 AI 查一个配置在哪个文件里让 AI 把一个大文件的函数拆成多个模块并逐个验证。这些任务的共性是目标明确、不需要太频繁的人工确认、失败了重跑成本不算太高。不适合远程操控的场景则包括需要多轮深度交互、依赖你实时给出大量设计决策的任务——AI 连续问你五个问题你在手机上逐条打字回答效率反而比坐电脑前低很多。还有就是涉及敏感密钥操作的任务比如让 AI 修改部署凭证、云服务密钥任何一步失误都可能造成比本地操作更大的损失。这一点值得展开讲一下因为它是远程控制 AI 编程代理的核心风险判断。本地使用 OpenCode 时你和 AI 在同一台机器上你随时能看到它执行了什么命令CtrlC 也能强制中断它。远程使用就完全不同了你隔着一个 Telegram 通道消息是异步的执行是滞后的。如果 AI 误判了你的意图执行了破坏性命令你可能过几分钟才收到报错通知。因此我给自己定了一个规矩任何涉及 git 强制推送、文件删除、大规模替换的任务默认不在远程模式下交给 AI 去跑。换个直观的说法远程操控 AI 编程代理就像通过手机遥控扫地机器人——你能让它去扫地但别让它在你不在家的时候执行可能把猫砂打翻的复杂操作。4.3 消息格式与可读性的二次优化原版 opencode-telegram-bot 的消息格式设计在我看来只能打 70 分。它把 OpenCode 的主要输出直接转为文本发出来好处是信息完整、不丢细节坏处是太长了。想象一下你手机收到一条一万字的代码分析报告滑动阅读是一件很消耗耐心的事情。我自己琢磨了一套优化方案核心思路是“结果导向、控制详略”。第一步在 bot 的适配层增加一层输出摘要逻辑。让模型在生成任务回复时要求它先给结论再给依据。比如 “共发现 7 个文件包含未使用的 import重点文件是 src/utils.js、src/api/client.js”然后再附上具体的行号和内容片段。这样一来我在手机上 30 秒能掌握核心信息如果需要对某个文件深入处理再单独发指令让它展开。第二步对超长输出做折叠处理。Telegram 的消息虽然没有强制的长度上限但超过一定长度之后手机端查看历史记录非常卡。我一般的做法是超过 3000 字符就把完整内容写入本地日志文件Telegram 里只给一个简短摘要和日志路径。第三步给固定的高频状态配置默认回复模板。比如任务开始、任务完成、任务失败这三种情况使用一致的消息格式任务名、执行时间、结果状态、下一步建议。这样在手机上扫一眼就能对当前任务情况心里有数不用每次都去翻上下文。4.4 多任务并发别让它成为一匹脱缰的野马OpenCode 作为一个交互式代理默认其实是单会话的。你通过 bot 传进去一条任务它正在执行的时候如果你又发了第二条任务进去到底会发生什么这取决于项目的设计。有的实现会做队列把第二条任务排在待办区等第一条结束了再执行有的实现则直接报错或者丢消息。我自己的使用习惯是不并发。虽然有队列的实现能兜底但 OpenCode 的执行本来就是上下文敏感的两个任务之间如果操作的是同一个 repo容易互相污染。比如任务 A 在重构文件任务 B 也在改同一个文件最后结果很容易变成一场灾难。如果真的有多任务并存的需求正确做法是开多个工作目录配合容器或者虚拟机隔离不同的执行环境然后用不同前缀区分指令把任务路由到对应的 OpenCode 会话里。这是进阶玩法等你把单会话用成熟了再尝试也不迟。5. 部署层优化从“跑起来”到“跑得稳”5.1 用 systemd 把它变成开机自启的后台服务前面提到我最初把 bot 跑在前台终端里一个 SSH 断开它就死了。这个方法只适合做连通性测试不适合做真实服务。我后来选择了用 systemd 托管。一个最小化的 systemd service 文件长这样[Unit] DescriptionOpenCode Telegram Bot Afternetwork-online.target [Service] Typesimple User你的系统用户名 WorkingDirectory/home/你的用户名/tools/opencode-telegram-bot EnvironmentFile/home/你的用户名/tools/opencode-telegram-bot/.env ExecStart/usr/bin/node /home/你的用户名/tools/opencode-telegram-bot/index.js Restartalways RestartSec5 [Install] WantedBymulti-user.target这里我踩过一个坑必须单独提一下EnvironmentFile这个字段如果你的.env文件里某个值包含了特殊字符例如#或空格systemd 的解析方式可能跟你预期的不同。所以如果发现进程起不来先检查.env文件里的值有没有需要转义的字符。另一个建议是给 bot 单独创建一个低权限系统用户不要直接用它跑在你的主用户下尤其是在远程控制场景下。如果 bot 进程被攻破一个低权限用户能把破坏范围限制在它自己的工作目录里不至于让你整个账号沦陷。配置好之后执行sudo systemctl daemon-reload sudo systemctl enable opencode-telegram-bot sudo systemctl start opencode-telegram-bot后续的查看日志、重启服务就用journalctl -u opencode-telegram-bot -f和systemctl restart opencode-telegram-bot。这两个命令我会用得非常频繁尤其是改完代码或配置之后。5.2 日志与审计远程控制必须有迹可循远程操控本地 AI 代理除了便利性还有一个安全和审计问题。本地敲命令终端里天然有历史记录通过 Telegram 远程控制命令的发出和执行过程都应该有持久化的日志。我的建议是在 bot 的日志输出中至少记录以下字段消息来源 chat_id、收到时间、消息全文脱敏后、路由到的处理函数、执行结果状态、耗时。这样万一哪次 AI 做了什么异常动作你可以回溯到是哪一个用户、在哪一条指令里触发的。我自己是把日志接入到了系统日志里由journald统一管理然后配合定时任务做日志轮转防止长期运行把磁盘吃掉。如果你有服务端日志采集的习惯也可以直接往日志系统里扔。核心原则只有一条这个系统要能回答“谁在什么时候让本地 AI 做了什么”的问题。5.3 断线重连与异常自愈机制Telegram Bot 的 Long Polling 模式本质上是一条长连接。它最大的问题是如果网络掉线或者 Telegram 服务器端连接超时bot 进程可能不会自动恢复表现在外面就是“Bot 失联了”。虽然很多 Bot 框架自带了重连机制但实现程度良莠不齐。为了提升稳定性我在 systemd 里配置了Restartalways让进程崩溃后自动拉起。但这还不够因为进程没有退出只是它的长轮询循环卡死了systemd 是不会知道需要重启的。这种情况下需要一种“看门狗”思路。我采用的方案是定时健康巡检用一个 cron 任务每隔 5 分钟通过getMe接口检查 bot 是否正常响应如果连续两次失败就调用 systemd 重启服务。这个巡检本身不复杂但能很有效地避免“进程还在、服务实际不可用”的假死状态。类似的思路你如果不想自己写也可以在进程管理器层面解决比如 pm2 的max_memory_restart配合 cron 重启能缓解一部分问题。不过必须承认这类机器人服务要做到 99.9% 的可用性是需要花不少心思在运维上的。如果只是个人使用我认为做到“进程崩溃能自动拉起 手动重启足够熟练”就已经超过大多数人能接受的稳定线了。6. 常见问题与排查技巧实录6.1 Bot 收不到任何消息这是最长遇到的一个问题。我的排查路径是按照这个顺序来的第一步确认 bot 进程还活着。查看日志看有没有报错尤其是权限类的错误。第二步确认你的消息确实发给了正确的 Bot。Telegram 私聊界面里如果出现的是一个类似网页预览的窗口而不是聊天输入框说明你可能打开的不是真正的 Bot 聊天。第三步查看getUpdates。有时候 bot 进程崩溃后重新启动会丢失掉之前已经拉取过的事件导致你的测试消息被跳过。手动通过浏览器访问https://api.telegram.org/bot你的TOKEN/getUpdates看看里面有没有你发的消息记录。第四步检查网络连通性。如果在服务器上直接 curl Telegram API 超时那问题就出在网络层。6.2 OpenCode 任务执行成功但 Telegram 没收到结果这个问题的典型表现是bot 能收到命令OpenCode 也确实执行了但结果没有推送回来。我之前遇到过一次原因让我印象很深刻OpenCode 进程在输出时使用了 ANSI 转义码bot 原样捕获并试图通过 Telegram 发送导致消息里包含大量不可见字符。一部分聊天客户端在解析异常字符时会直接不显示。解决方案就是在 bot 捕获 OpenCode 输出之后做一次清洗去掉 ANSI 控制序列再发送。如果你直接用 shell 管道重定向输出也可以考虑加上--no-color或类似参数让 OpenCode 以纯文本模式输出。遇到消息变成空白或乱码时优先检查这一环。6.3 白名单失效非授权用户依然能触发命令我实测时遇到过白名单逻辑有缺陷的情况项目里的白名单校验只发生在处理特定命令时对于某些不以斜杠开头的普通消息根本没有进入校验分支任何用户都能直接给 OpenCode 发指令。这个漏洞很隐蔽因为表面看起来你已经配置好了ALLOWED_CHAT_ID。排查方法是翻看 bot 的源码从消息入口处追踪校验逻辑到底被放到了哪个环节。如果项目太老或者作者没有考虑周全稳妥的做法是自己加一道全局拦截所有非白名单 chat_id 发来的消息一律在入口处直接丢弃不进入后续处理流程。6.4 一条指令触发两次执行Telegram Bot 的消息确认机制里有一个细节如果你的 bot 处理一条消息的耗时超过了 Long Polling 的超时时间或者处理过程中进程意外重启了Telegram 服务器会认为这条消息没有被成功接收于是在下次连接时重新推送同一条消息。结果就是你的 OpenCode 可能把同一任务跑了两遍。解决思路有两个层面。应用层面给每条消息做去重记录最近处理过的 message_id如果新收到的消息 id 已经存在就直接忽略。这需要在 bot 里维护一个小型缓存或 Redis对个人工具来说缓存在内存里就够了。操作层面避免执行特别耗时且不可并行的任务如果任务本身就要跑十几分钟那就要有“它可能执行了两次”的心理预期。6.5 安全加固的经验补充最后聊几句容易被新手忽略的安全配置。第一不要把敏感信息通过 Telegram 明文发送到手机Telegram 的私聊有端到端加密但 Bot API 属于另外一套机制Bot 和服务器之间的传输并不默认端到端加密代码片段、API 密钥这类内容要谨慎。第二定期轮换你的 Bot Token。如果换了 Token旧 Token 会立即失效可以避免因为 token 泄露导致的被控制风险。第三如果你在多人协作环境里使用同一个 OpenCode 实例建议给 OpenCode 增加独立的系统账号和目录权限不让它裸奔在你的主目录中。在远程控制场景里多一道权限栅栏就多一分安心。写在最后的一点个人经验这套 opencode-telegram-bot 方案我实际跑了两周之后最明显的变化不是代码效率提升了多少而是“能离开电脑”的安全感提升了。以前我开一个长时间运行的 OpenCode 任务基本就要守在电脑前刷手机打发时间现在我可以把任务交给它自己去处理别的杂事有结果了手机上会收到推送。真正的价值不在于你把 AI 编程代理搬到了口袋里而在于它给了你一个可以随时问一句“现在项目什么状态”的远程窗口。如果这个项目后续还能继续扩展我建议可以关注两个方向一是集成更多的 AI Agent 事件推送比如把 git 提交、CI 构建状态也接入到同一条 Telegram 通道里让工作信息流聚合成一个单一入口另一个方向是支持通过 Telegram 语音消息下发任务让语音转文字后直接变成 OpenCode 的指令。对于一个懂行的开发者来说这些方向实现起来难度都不大但它们带来的便利度会是台阶式的提升。希望这篇记录能给你一些可以直接落地的经验少走几个我走过的弯路。