你知道吗，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 LTS，OpenCode 跑在本地 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_DIRECTORY：OpenCode 默认在哪个目录下执行任务。这个要格外小心，因为远程命令是在这个目录层面跑的。如果你把工作目录设置成/，又不小心让 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 API；bot 是否真的在持续运行不报错。三件事按顺序查，基本能解决大部分问题。
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 在同一台机器上，你随时能看到它执行了什么命令，Ctrl+C 也能强制中断它。远程使用就完全不同了，你隔着一个 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] Description=OpenCode Telegram Bot After=network-online.target [Service] Type=simple 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 Restart=always RestartSec=5 [Install] WantedBy=multi-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 里配置了Restart=always，让进程崩溃后自动拉起。但这还不够，因为进程没有退出，只是它的长轮询循环卡死了，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 的指令。对于一个懂行的开发者来说，这些方向实现起来难度都不大，但它们带来的便利度会是台阶式的提升。希望这篇记录能给你一些可以直接落地的经验，少走几个我走过的弯路。
