OpenCode Telegram Bot：打造本地化AI编码伴侣，实现远程异步开发

1. 项目概述一个本地化的AI编码伴侣如果你和我一样经常在命令行里用opencode这个AI编码工具那你肯定遇到过这样的场景正坐在沙发上用手机刷着消息突然灵光一现想到一个代码优化点或者一个需要调试的Bug。这时候你是选择起身去开电脑还是掏出手机打开一个专门的远程控制App再费劲地输入命令或者你正在运行一个耗时的构建或测试任务但又不想一直守在电脑前希望能随时查看进度。OpenCode Telegram Bot 就是为了解决这些痛点而生的。简单来说它是一个运行在你本地机器上的Telegram机器人。它充当了你手机上的Telegram和你电脑上运行的OpenCode服务器之间的安全桥梁。通过它你可以直接在Telegram聊天窗口里向OpenCode发送编码任务、切换模型、管理会话、查看实时状态甚至安排定时任务。最核心的优势在于它完全运行在本地不暴露任何公网端口或API所有通信都经过加密的Telegram Bot API和你的本地网络安全性有保障。你可以把它理解为一个轻量级的、专为OpenCode设计的“OpenClaw”替代方案让你能随时随地、以一种更轻松的方式与你的AI编码助手互动。1.1 核心价值与适用人群这个工具的核心价值在于“无缝的远程与异步编码体验”。它不是为了替代OpenCode强大的终端用户界面TUI而是对其功能进行移动端和异步场景的延伸。对频繁进行上下文切换的开发者当你离开工位或者在会议间隙想快速给AI布置一个小的代码审查或重构任务用手机发条消息是最自然的方式。对需要监控长时间运行任务的开发者比如让AI进行大型代码库的分析或生成。你可以通过机器人随时查看任务进度、子代理状态而无需保持SSH连接或不断刷新终端。对希望自动化例行编码工作的开发者通过其“计划任务”功能你可以让机器人在特定时间例如凌晨自动运行代码质量检查、依赖更新或生成日报实现一定程度的自动化。对多语言开发者项目支持包括简体中文在内的多种界面语言降低了非英语用户的使用门槛。它本质上是一个生产力工具将OpenCode从“必须坐在电脑前使用的工具”变成了一个“随时可用的编码伙伴”。接下来我会带你从零开始完整地搭建并使用这个机器人并分享我在配置和使用过程中积累的一些实战经验和避坑技巧。2. 环境准备与初始化配置在开始敲命令之前我们需要确保三样东西就位Node.js运行环境、一个正常工作的OpenCode服务以及一个属于你自己的Telegram机器人。这个过程大约需要10分钟。2.1 前置条件检查首先确认你的系统满足最低要求。这个机器人基于Node.js因此你需要安装Node.js 20或更高版本。在终端执行node --version即可查看。如果版本过低或未安装请前往 Node.js官网 下载安装LTS版本。其次你需要已经安装并配置好OpenCode。如果你还没安装可以参照 OpenCode官方指南 进行安装。关键是确保你能在终端成功运行opencode命令。本机器人需要与OpenCode的服务端opencode serve通信所以OpenCode是必须的。2.2 创建你的Telegram机器人这是整个设置中最关键的一步但别担心过程非常简单全程在Telegram应用内完成。找到BotFather在Telegram中搜索并打开 BotFather 这个官方机器人。创建新机器人向它发送/newbot命令。设置名称根据提示为你的机器人设置一个显示名称比如My OpenCode Assistant和一个唯一的用户名必须以bot结尾例如my_opencode_assistant_bot。获取令牌创建成功后BotFather会回复给你一串重要的信息其中包含类似1234567890:ABCdefGhIJKlmNoPQRsTUVwxyZ的Bot Token。请立即妥善保存这串令牌它相当于你机器人的密码后续配置会用到。任何人获得这个令牌都能控制你的机器人。获取你的用户ID为了确保安全机器人只响应你一个人的指令。你需要获取自己的Telegram用户ID。打开另一个机器人 userinfobot 向它发送任意消息它会立刻回复你的数字ID例如12345678。同样记下这个数字。安全提示Bot Token和你的用户ID是最高机密。千万不要泄露给他人也不要提交到任何公开的代码仓库。后续的配置向导会引导你将它们安全地存储在本地配置文件中。2.3 启动OpenCode服务端机器人需要连接到一个正在运行的OpenCode服务实例。打开你的终端运行以下命令opencode serve默认情况下OpenCode服务会启动在http://localhost:4096。你可以通过访问http://localhost:4096/health来验证服务是否正常运行应该返回一个简单的JSON健康状态。请保持这个终端窗口运行或者将其放入后台例如使用tmux或screen。实操心得在生产环境中我推荐使用tmux或systemd来管理opencode serve进程确保其长期稳定运行。因为如果服务意外终止Telegram机器人将无法工作。机器人后续也提供了/opencode_start和/opencode_stop命令可以直接在Telegram里控制本地服务非常方便。2.4 安装并运行机器人最快捷的方式是使用npx直接运行最新版本无需全局安装。打开一个新的终端窗口执行npx grinev/opencode-telegram-botlatest第一次运行时会启动一个交互式的配置向导。向导会依次询问以下信息界面语言选择你熟悉的语言例如zh简体中文。Bot Token粘贴你从 BotFather 那里获得的令牌。用户ID粘贴你从 userinfobot 那里获得的数字ID。OpenCode API地址通常直接回车使用默认值http://localhost:4096即可除非你的OpenCode服务运行在其他地址或端口。OpenCode服务认证如果你的OpenCode服务设置了用户名和密码默认用户名为opencode密码在首次运行opencode serve时生成则需要在此处填写。如果只是本地使用且未设置密码可以留空。配置完成后机器人会自动启动。现在打开Telegram找到你刚创建的机器人通过其用户名发送/start或任何消息你应该能收到回复了注意事项使用npx运行的方式适合快速体验。如果你打算长期使用我建议进行全局安装这样管理起来更规范npm install -g grinev/opencode-telegram-bot opencode-telegram start全局安装后你可以使用opencode-telegram config命令随时重新配置使用opencode-telegram start --daemon在后台运行并使用status和stop命令进行管理。3. 核心功能深度解析与实战应用机器人成功运行后它的强大之处才真正展现出来。它不仅仅是一个命令转发器而是对OpenCode工作流进行了深度集成和优化。下面我们来拆解几个最核心的功能模块。3.1 会话管理与实时状态追踪这是机器人最基础也最重要的功能。在OpenCode TUI中你通过会话Session来组织工作。机器人完美复刻了这一概念。创建与切换会话使用/new命令可以立即创建一个全新的编码会话。使用/sessions命令会以一个内联键盘菜单的形式列出你最近的会话记录数量由SESSIONS_LIST_LIMIT控制你可以一键切换回任何一个历史会话。这比在TUI里翻找要直观得多。实时状态面板一旦你拥有一个活跃会话机器人会在聊天窗口置顶一条消息。这条消息是动态更新的它会实时显示当前项目你正在工作的项目路径。工作树如果项目是Git仓库且你切换了工作树这里会显示。当前模型正在使用的AI模型。上下文使用量当前会话消耗的Tokens情况帮助你把握上下文窗口是否紧张。变更文件列表AI在上次任务中修改了哪些文件一目了然。这个状态面板是你监控任务进度的“仪表盘”。我经常在让AI执行一个大型重构时时不时看一眼Telegram就能知道它已经改动了哪些文件上下文用了多少心里非常踏实。实战技巧追踪现有TUI会话一个非常实用的场景是“接力”。假设你已经在电脑的终端里用opencode --port 4096启动了一个TUI会话并开始工作。之后你想离开电脑用手机继续。你只需要确保机器人配置的API地址OPENCODE_API_URL也是http://localhost:4096然后在机器人里使用/sessions选择你刚才在TUI中创建的那个会话。选择后机器人就会开始“追踪”这个会话。此后这个会话在TUI里的所有输出包括你手动在TUI输入的内容都会同步显示在Telegram中你也可以在Telegram里继续发送指令实现无缝衔接。3.2 模型切换与智能提示OpenCode支持众多模型如何快速切换是影响效率的关键。机器人的模型选择器设计得非常聪明。当你需要切换模型时只需在聊天中输入“/”然后选择“模型”或直接点击相关按钮机器人会弹出一个内联菜单。这个菜单的排序逻辑是收藏夹优先首先列出你在OpenCode TUI中标记为“收藏”Favorite的模型。在TUI中在模型列表上按CmdF(Mac) 或CtrlF(Windows/Linux) 即可收藏。近期使用然后列出你最近使用过的模型。去重与标记已收藏的模型不会在“最近使用”中重复出现。当前正在使用的模型前面会有一个✅标记。这个设计极大地减少了滚动查找的时间。我的习惯是在TUI里把最常用的2-3个模型比如一个主力编码模型和一个长上下文分析模型加入收藏夹这样在手机上切换就是一键之事。3.3 文件处理与语音输入机器人打破了纯文本交互的限制让信息输入更加多元。文件附件你可以直接向机器人发送图片、PDF、文本文件如.log,.json,.py等。机器人会读取文件内容并将其作为上下文的一部分发送给OpenCode。例如你可以拍一张错误日志的照片或者发送一个需求文档的PDF让AI直接基于这些材料开始工作。对于代码文件如果文件大小超过CODE_FILE_MAX_SIZE_KB默认100KB的限制机器人会将其作为Telegram文档发送你可以在客户端直接下载查看。语音输入这是真正解放双手的功能。你需要配置一个兼容Whisper的语音转文本STT服务。以使用OpenAI的Whisper为例在机器人的配置文件.env中添加STT_API_URLhttps://api.openai.com/v1 STT_API_KEYsk-your-openai-api-key-here STT_MODELwhisper-1配置好后你就可以在Telegram里直接发送语音消息。机器人会调用STT API将其转成文字显示在聊天中然后作为普通提示词发送给OpenCode。你甚至可以通过STT_NOTE_PROMPT环境变量为所有语音转文字附加一个前缀提示例如[来自语音输入]让AI更好地理解上下文。语音输出TTS如果你也配置了TTS文本转语音例如使用OpenAI的TTS API你还可以用/tts命令开启语音回复。开启后AI的文本回复会被合成语音并发送给你。这在开车、散步等不方便看屏幕的场景下非常有用。避坑指南语音和文件功能依赖于外部API会产生费用。对于STTOpenAI的Whisper API价格非常低廉。建议在.env文件中配置好API密钥和URL后先发送一条简短的语音或一个小文件进行测试确保功能正常避免因配置错误导致意外的大量调用。3.4 计划任务将AI编码自动化/task命令打开了一个自动化的大门。你可以创建一个在将来某个时间点运行或者按固定周期重复运行的任务。创建过程使用/task后机器人会引导你输入任务描述即给AI的提示词。选择运行模式单次运行 或 重复运行。设置具体的日期、时间或间隔重复任务的最小间隔是5分钟。核心逻辑任务基于创建时的当前项目和模型。这意味着你可以在项目A下创建一个任务切换到项目B后任务依然会在项目A中执行。任务使用build代理运行与你在聊天中的交互式会话隔离互不干扰。机器人会为每个任务运行设置超时默认120分钟防止失控任务无限运行。系统有默认的任务数量上限10个防止滥用可以在.env中通过TASK_LIMIT调整。应用场景每日代码审查设定每天上午9点让AI自动检查主分支的新提交并生成一份简短的代码变更报告。依赖更新检查每周一凌晨自动运行npm outdated或pip list --outdated分析并报告可升级的依赖及其可能的影响。定时数据备份与处理对于有定时生成数据的项目让AI在数据生成后自动执行清洗、分析和归档操作。我常用它来让AI在夜间为我运行项目的完整测试套件并在第二天早上通过Telegram查看测试结果和任何失败的日志相当于一个智能的、可编程的CI机器人。3.5 技能与命令库快速调用OpenCode支持自定义命令Custom Commands和技能Skills。机器人的/commands和/skills命令将这些功能做成了可浏览的菜单。自定义命令 (/commands)这会列出你在当前项目中定义的所有自定义命令以及init,review等内置命令。点击一个命令机器人会询问你是否确认执行或者是否需要附加参数。这比在TUI里输入命令全名要快得多尤其适合那些有复杂参数但频繁使用的命令。技能库 (/skills)以分页菜单的形式展示OpenCode的技能库。你可以浏览技能描述并直接运行它们。选择技能后机器人会提示你输入所需的参数。这大大降低了技能的使用门槛你不需要记住技能的确切名称和语法。这个功能将OpenCode从“需要记忆命令的工具”变成了“可探索的工具箱”特别适合新手或者想尝试新技能的开发者。4. 高级配置、安全与故障排查要让机器人更贴合你的工作习惯或者解决运行中遇到的问题就需要深入了解其配置和内部机制。4.1 环境变量详解与优化配置机器人的行为由环境变量控制。虽然安装向导帮你生成了基本的.env文件但理解关键变量能让你用得更好。配置文件通常位于macOS:~/Library/Application Support/opencode-telegram-bot/.envLinux:~/.config/opencode-telegram-bot/.envWindows:%APPDATA%\opencode-telegram-bot\.env以下是一些值得调整的高级选项变量名建议值与说明SERVICE_MESSAGES_INTERVAL_SEC默认5。这是机器人发送“思考中...”和“工具调用...”等状态消息的最小间隔。调低如设为2会提高实时性但可能触发Telegram API频率限制。除非你非常需要即时反馈否则保持默认即可。RESPONSE_STREAMING默认true。强烈建议开启。AI生成回复时内容会像流一样一段段发送到Telegram而不是等全部生成完再发送。这提供了更好的交互感尤其对于长回复。MESSAGE_FORMAT_MODE默认markdown。AI的回复会以Markdown格式渲染加粗、代码块等。如果某些模型回复的Markdown格式混乱导致显示问题可以设为raw禁用格式。BASH_TOOL_DISPLAY_MAX_LENGTH默认128。当AI执行bash命令时在Telegram中显示的命令会被截断到此长度。如果你需要查看完整的超长命令可以适当调大这个值。HIDE_THINKING_MESSAGES/HIDE_TOOL_CALL_MESSAGES默认false。如果你觉得“ Thinking...”这类状态消息干扰了聊天记录可以将其设为true来隐藏。我个人喜欢保留因为它让我清楚AI当前在做什么阶段。4.2 安全模型深度剖析这个机器人的安全设计值得称道它遵循了“最小权限”和“纵深防御”原则。第一道防线用户ID白名单。这是最核心的机制。机器人启动时读取TELEGRAM_ALLOWED_USER_ID任何非此ID用户发送的消息都会被静默忽略并在日志中记录为未授权访问尝试。这意味着即使有人偶然发现了你的机器人链接他也无法与之进行任何交互。第二道防线本地化部署。机器人进程和OpenCode服务都运行在你的本地机器上。它们之间的通信 (http://localhost:4096) 不经过公网。攻击者无法直接从互联网访问到你的OpenCode API。第三道防线Telegram API加密。机器人与Telegram服务器之间的所有通信都使用HTTPS加密。你的指令和AI的回复在传输过程中是安全的。无状态设计机器人本身不存储任何敏感的会话密钥或聊天历史除了用于运行的计划任务。所有状态都维持在OpenCode服务端。因此整个系统的安全边界就缩小为保护你的.env文件特别是Bot Token以及运行机器人的主机本身的安全。只要你的电脑不被入侵这个设置就是非常安全的。重要提醒绝对不要将.env文件提交到Git等版本控制系统。项目提供的.env.example是模板你的真实配置应始终保持在本地。可以考虑将.env加入你的全局.gitignore文件。4.3 常见问题与排查实录即使配置正确在实际使用中也可能遇到一些小问题。下面是我遇到过的典型情况及其解决方法。问题一机器人完全无响应症状发送消息后机器人长时间不回复甚至不显示“已读”状态。排查步骤检查进程首先确认机器人进程是否在运行。在终端运行opencode-telegram status全局安装或查看你启动它的终端窗口。检查Token和User ID这是最常见的问题。用opencode-telegram config重新运行配置或直接检查.env文件确保TELEGRAM_BOT_TOKEN和TELEGRAM_ALLOWED_USER_ID完全正确没有多余的空格或换行。再次通过 userinfobot 确认你的用户ID。查看日志日志文件通常位于配置目录下的logs/文件夹内。查看最新的日志寻找错误信息。常见的错误包括ETELEGRAM: 404 Not FoundToken错误或UnauthorizedUser ID不匹配。问题二提示“OpenCode server is not available”症状机器人回复无法连接到OpenCode服务。排查步骤确认服务运行在终端执行curl http://localhost:4096/health或直接在浏览器打开该地址。应返回{status:ok}。如果没有说明opencode serve没有运行或运行在别的端口。检查端口和URL确认机器人的OPENCODE_API_URL配置与OpenCode服务实际监听的地址和端口一致。如果你用opencode serve --port 5000启动了服务那么URL就应该是http://localhost:5000。检查认证如果你为OpenCode服务设置了密码请确保在机器人的.env文件中正确配置了OPENCODE_SERVER_USERNAME和OPENCODE_SERVER_PASSWORD。问题三模型选择器为空或缺少模型症状使用模型切换功能时列表是空的或者看不到你想要的模型。排查步骤添加收藏机器人的模型列表来源于OpenCode的“收藏夹”和“最近使用”。你需要先在OpenCode的TUI界面中进入模型选择列表将常用模型通过CtrlF添加到收藏夹。检查默认模型配置确保.env中的OPENCODE_MODEL_PROVIDER和OPENCODE_MODEL_ID指向一个你本地可用的、有效的模型。这个模型会始终出现在收藏夹列表顶部。重启机器人有时OpenCode的模型列表更新后需要重启机器人进程才能同步到最新的收藏状态。问题四计划任务没有按时执行症状创建的计划任务到了时间没有运行或者没有输出结果。排查步骤检查机器人是否运行计划任务的调度依赖于持续运行的机器人进程。如果机器人进程退出了任务自然无法触发。检查系统时间确保运行机器人的服务器系统时间、时区设置正确。查看任务日志计划任务的执行详情会输出到机器人的主日志文件中。查看日志中在任务预定时间点附近是否有相关记录可能包含执行失败的错误信息。注意任务隔离计划任务在独立的上下文中运行其输出不会直接发送到你的聊天窗口。你需要通过查看机器人的日志或者让任务本身通过生成文件、发送通知等外部方式告知你结果。5. 开发与贡献指南如果你对Node.js/TypeScript开发感兴趣或者想为这个项目添加新功能可以尝试从源码运行和贡献。5.1 从源码运行# 克隆仓库 git clone https://github.com/grinev/opencode-telegram-bot.git cd opencode-telegram-bot # 安装依赖 npm install # 复制环境变量模板并配置 cp .env.example .env # 使用文本编辑器编辑 .env 文件填入你的Bot Token、User ID等 # 编译并运行开发模式 npm run devnpm run dev命令会先编译TypeScript代码然后启动机器人。需要注意的是项目没有使用文件监视和自动重启因为机器人维持着与Telegram和OpenCode的持久连接自动重启会导致连接中断。因此修改代码后需要手动停止并重新运行npm run dev。5.2 项目结构与技术栈理解项目结构有助于定位代码和进行修改src/主要的TypeScript源代码目录。bot/Telegram机器人相关的逻辑使用grammY框架。opencode/与OpenCode API交互的客户端封装。services/核心业务服务如会话管理、任务调度、状态跟踪等。locales/多语言翻译文件。docs/额外的文档如Linux systemd服务配置指南。项目使用vitest进行单元测试坚持“零警告”的代码规范npm run lint。5.3 如何贡献如果你发现了Bug或者有一个很棒的功能想法欢迎贡献。在提交Pull Request之前请务必阅读项目根目录的CONTRIBUTING.md文件了解代码提交和发布说明的规范。确保代码通过ESLint检查npm run lint。为新增的功能添加相应的测试。可以先在项目的 GitHub Discussions 发起讨论描述你的想法。我个人在使用过程中就曾因为需要更精细地控制消息推送频率而查阅了相关代码并理解了SERVICE_MESSAGES_INTERVAL_SEC参数的设计初衷。这种开源项目的好处在于当你需要时你总有机会让它变得更适合自己。最后一点体会这个工具最大的魅力在于它“润物细无声”地融入到了工作流中。它没有试图创造一个全新的复杂界面而是巧妙地利用了大家最熟悉的通讯工具——Telegram将强大的AI编码能力延伸到了移动场景和异步场景。从最初的简单命令转发到现在的状态追踪、文件语音处理、计划任务它已经成长为一个相当成熟的“AI编码伴侣”。如果你已经是OpenCode的用户花上半小时配置一下它很可能会成为你开发工具箱中又一个“用了就回不去”的利器。