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应用内完成。

1. 找到BotFather：在Telegram中搜索并打开 @BotFather 这个官方机器人。
2. 创建新机器人：向它发送/newbot命令。
3. 设置名称：根据提示，为你的机器人设置一个显示名称（比如My OpenCode Assistant）和一个唯一的用户名（必须以bot结尾，例如my_opencode_assistant_bot）。
4. 获取令牌：创建成功后，BotFather会回复给你一串重要的信息，其中包含类似1234567890:ABCdefGhIJKlmNoPQRsTUVwxyZ的Bot Token。请立即妥善保存这串令牌，它相当于你机器人的密码，后续配置会用到。任何人获得这个令牌都能控制你的机器人。
5. 获取你的用户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-bot@latest

第一次运行时会启动一个交互式的配置向导。向导会依次询问以下信息：

1. 界面语言：选择你熟悉的语言，例如zh（简体中文）。
2. Bot Token：粘贴你从 @BotFather 那里获得的令牌。
3. 用户ID：粘贴你从 @userinfobot 那里获得的数字ID。
4. OpenCode API地址：通常直接回车使用默认值http://localhost:4096即可，除非你的OpenCode服务运行在其他地址或端口。
5. 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支持众多模型，如何快速切换是影响效率的关键。机器人的模型选择器设计得非常聪明。

当你需要切换模型时，只需在聊天中输入“/”然后选择“模型”（或直接点击相关按钮），机器人会弹出一个内联菜单。这个菜单的排序逻辑是：

1. 收藏夹优先：首先列出你在OpenCode TUI中标记为“收藏”（Favorite）的模型。在TUI中，在模型列表上按Cmd+F(Mac) 或Ctrl+F(Windows/Linux) 即可收藏。
2. 近期使用：然后列出你最近使用过的模型。
3. 去重与标记：已收藏的模型不会在“最近使用”中重复出现。当前正在使用的模型前面会有一个✅标记。

这个设计极大地减少了滚动查找的时间。我的习惯是在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_URL=https://api.openai.com/v1 STT_API_KEY=sk-your-openai-api-key-here STT_MODEL=whisper-1

  配置好后，你就可以在Telegram里直接发送语音消息。机器人会调用STT API将其转成文字，显示在聊天中，然后作为普通提示词发送给OpenCode。你甚至可以通过STT_NOTE_PROMPT环境变量，为所有语音转文字附加一个前缀提示，例如[来自语音输入]，让AI更好地理解上下文。
• 语音输出（TTS）：如果你也配置了TTS（文本转语音），例如使用OpenAI的TTS API，你还可以用/tts命令开启语音回复。开启后，AI的文本回复会被合成语音并发送给你。这在开车、散步等不方便看屏幕的场景下非常有用。

避坑指南：语音和文件功能依赖于外部API，会产生费用。对于STT，OpenAI的Whisper API价格非常低廉。建议在.env文件中配置好API密钥和URL后，先发送一条简短的语音或一个小文件进行测试，确保功能正常，避免因配置错误导致意外的大量调用。

3.4 计划任务：将AI编码自动化

/task命令打开了一个自动化的大门。你可以创建一个在将来某个时间点运行，或者按固定周期重复运行的任务。

创建过程：使用/task后，机器人会引导你：

1. 输入任务描述（即给AI的提示词）。
2. 选择运行模式（单次运行 或 重复运行）。
3. 设置具体的日期、时间或间隔（重复任务的最小间隔是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/.env
• Linux:~/.config/opencode-telegram-bot/.env
• Windows:%APPDATA%\opencode-telegram-bot\.env

以下是一些值得调整的高级选项：

4.2 安全模型深度剖析

这个机器人的安全设计值得称道，它遵循了“最小权限”和“纵深防御”原则。

1. 第一道防线：用户ID白名单。这是最核心的机制。机器人启动时读取TELEGRAM_ALLOWED_USER_ID，任何非此ID用户发送的消息都会被静默忽略，并在日志中记录为未授权访问尝试。这意味着即使有人偶然发现了你的机器人链接，他也无法与之进行任何交互。
2. 第二道防线：本地化部署。机器人进程和OpenCode服务都运行在你的本地机器上。它们之间的通信 (http://localhost:4096) 不经过公网。攻击者无法直接从互联网访问到你的OpenCode API。
3. 第三道防线：Telegram API加密。机器人与Telegram服务器之间的所有通信都使用HTTPS加密。你的指令和AI的回复在传输过程中是安全的。
4. 无状态设计：机器人本身不存储任何敏感的会话密钥或聊天历史（除了用于运行的计划任务）。所有状态都维持在OpenCode服务端。

因此，整个系统的安全边界就缩小为：保护你的.env文件（特别是Bot Token）以及运行机器人的主机本身的安全。只要你的电脑不被入侵，这个设置就是非常安全的。

重要提醒：绝对不要将.env文件提交到Git等版本控制系统。项目提供的.env.example是模板，你的真实配置应始终保持在本地。可以考虑将.env加入你的全局.gitignore文件。

4.3 常见问题与排查实录

即使配置正确，在实际使用中也可能遇到一些小问题。下面是我遇到过的典型情况及其解决方法。

问题一：机器人完全无响应

• 症状：发送消息后，机器人长时间不回复，甚至不显示“已读”状态。
• 排查步骤：
  1. 检查进程：首先确认机器人进程是否在运行。在终端运行opencode-telegram status（全局安装）或查看你启动它的终端窗口。
  2. 检查Token和User ID：这是最常见的问题。用opencode-telegram config重新运行配置，或直接检查.env文件，确保TELEGRAM_BOT_TOKEN和TELEGRAM_ALLOWED_USER_ID完全正确，没有多余的空格或换行。再次通过 @userinfobot 确认你的用户ID。
  3. 查看日志：日志文件通常位于配置目录下的logs/文件夹内。查看最新的日志，寻找错误信息。常见的错误包括ETELEGRAM: 404 Not Found（Token错误）或Unauthorized（User ID不匹配）。

问题二：提示“OpenCode server is not available”

• 症状：机器人回复无法连接到OpenCode服务。
• 排查步骤：
  1. 确认服务运行：在终端执行curl http://localhost:4096/health或直接在浏览器打开该地址。应返回{"status":"ok"}。如果没有，说明opencode serve没有运行或运行在别的端口。
  2. 检查端口和URL：确认机器人的OPENCODE_API_URL配置与OpenCode服务实际监听的地址和端口一致。如果你用opencode serve --port 5000启动了服务，那么URL就应该是http://localhost:5000。
  3. 检查认证：如果你为OpenCode服务设置了密码，请确保在机器人的.env文件中正确配置了OPENCODE_SERVER_USERNAME和OPENCODE_SERVER_PASSWORD。

问题三：模型选择器为空或缺少模型

• 症状：使用模型切换功能时，列表是空的，或者看不到你想要的模型。
• 排查步骤：
  1. 添加收藏：机器人的模型列表来源于OpenCode的“收藏夹”和“最近使用”。你需要先在OpenCode的TUI界面中，进入模型选择列表，将常用模型通过Ctrl+F添加到收藏夹。
  2. 检查默认模型配置：确保.env中的OPENCODE_MODEL_PROVIDER和OPENCODE_MODEL_ID指向一个你本地可用的、有效的模型。这个模型会始终出现在收藏夹列表顶部。
  3. 重启机器人：有时OpenCode的模型列表更新后，需要重启机器人进程才能同步到最新的收藏状态。

问题四：计划任务没有按时执行

• 症状：创建的计划任务到了时间没有运行，或者没有输出结果。
• 排查步骤：
  1. 检查机器人是否运行：计划任务的调度依赖于持续运行的机器人进程。如果机器人进程退出了，任务自然无法触发。
  2. 检查系统时间：确保运行机器人的服务器系统时间、时区设置正确。
  3. 查看任务日志：计划任务的执行详情会输出到机器人的主日志文件中。查看日志中在任务预定时间点附近是否有相关记录，可能包含执行失败的错误信息。
  4. 注意任务隔离：计划任务在独立的上下文中运行，其输出不会直接发送到你的聊天窗口。你需要通过查看机器人的日志，或者让任务本身通过生成文件、发送通知等外部方式告知你结果。

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 dev

npm 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之前，请务必：

1. 阅读项目根目录的CONTRIBUTING.md文件，了解代码提交和发布说明的规范。
2. 确保代码通过ESLint检查（npm run lint）。
3. 为新增的功能添加相应的测试。
4. 可以先在项目的 GitHub Discussions 发起讨论，描述你的想法。

我个人在使用过程中，就曾因为需要更精细地控制消息推送频率而查阅了相关代码，并理解了SERVICE_MESSAGES_INTERVAL_SEC参数的设计初衷。这种开源项目的好处在于，当你需要时，你总有机会让它变得更适合自己。

最后一点体会：这个工具最大的魅力在于它“润物细无声”地融入到了工作流中。它没有试图创造一个全新的复杂界面，而是巧妙地利用了大家最熟悉的通讯工具——Telegram，将强大的AI编码能力延伸到了移动场景和异步场景。从最初的简单命令转发，到现在的状态追踪、文件语音处理、计划任务，它已经成长为一个相当成熟的“AI编码伴侣”。如果你已经是OpenCode的用户，花上半小时配置一下，它很可能会成为你开发工具箱中又一个“用了就回不去”的利器。