18 March, 2026

用 Telegram 远程操控本地 OpenCode：opencode-telegram-bot 实战指南

笔记 AI

TL;DR

用 opencode-telegram-bot，把 Telegram 变成本地 OpenCode 的远程终端。配置不超过 10 分钟，无需开放端口，代码不离开本地。适合个人电脑长期在家、需要随时远程驱动本地 AI 编码环境的场景。

引言

两种场景，同一个痛点。

场景一：手机拿在手，脑子里突然蹦出一个想法——「这个 bug 该怎么改？」打开电脑，启动终端，切换目录，输入 prompt……等你坐下来，思路早散了一半。

场景二：个人项目只放在家里的电脑上，工作机碰不到。灵感在公司突然来了，只能先记到备忘录，回家再处理——但等到家，状态早就不一样了。

opencode-telegram-bot 解决的就是这个摩擦。它不是一个云端 AI 服务，而是一座桥——把 Telegram，和家里本地运行的 OpenCode CLI 直接连接起来。本地的算力、本地的代码、本地的上下文，全部通过一条消息驱动，随时随地，无需等到坐在电脑前。

不需要开放任何端口，不需要把代码推到云端。安全，轻量，随时可用。

这篇文章记录完整的安装配置流程，以及实际跑通后的使用体验。

工具介绍

opencode-telegram-bot 是一个开源的 Node.js 项目，核心逻辑很简单：监听 Telegram Bot 的消息，转发给本地的 OpenCode API，再把结果返回到 Telegram。

整个通信链路如下：

Telegram App → Telegram Bot API（云端） → opencode-telegram-bot → OpenCode Server（本地）

消息经由 Telegram 的服务器中转，但代码、项目文件、执行环境全部留在本地。Bot 以轮询方式主动拉取 Telegram 消息，无需开放任何入站端口，也不需要公网 IP。

主要特性：

发送文字 prompt，实时查看执行状态
支持发送图片、PDF、文件作为上下文
支持语音 prompt（通过 Whisper 转录）
支持切换模型和工作模式（Plan / Build）
会话管理：创建、切换、重命名会话
项目切换：在多个 OpenCode 项目间切换
定时任务：预设 prompt，定时或周期执行
自定义命令：从 Telegram 触发 OpenCode 的自定义命令
交互式审批：通过 inline 按钮回答 Agent 提问、审批权限
上下文控制：上下文过大时可一键压缩
界面多语言支持（含简体中文）
通过 npx 运行，无需全局安装

依赖环境：

依赖	说明
Node.js 20+	运行环境
OpenCode CLI	本地 AI 编码引擎
Telegram Bot Token	从 @BotFather 获取

唯一的前提：OpenCode 需要在本地持续运行。Bot 只是控制层，真正干活的还是本地的 OpenCode。

前置准备

开始之前需要准备两样东西：确认 OpenCode 已安装，以及创建一个 Telegram Bot。

确认 OpenCode 已安装

which opencode && opencode --version

输出类似以下内容即为正常（路径和版本号以实际为准）：

/Users/你的用户名/.opencode/bin/opencode
1.x.x

如果尚未安装，参考 OpenCode 官方文档完成安装。

创建 Telegram Bot

打开 Telegram，搜索 @BotFather
发送 /newbot，按提示设置 Bot 名称和 username
创建成功后，BotFather 会返回一个 Bot Token，格式如下：
```
123456789:AAxxxxxxxxxxxxxxxxxxxx
```
妥善保存，后续配置需要用到。

获取自己的 Telegram User ID

Bot 需要知道只响应哪个用户的消息，因此要提供你的 User ID：

搜索 @userinfobot
发送任意消息，它会返回你的数字 ID

安装与配置

opencode-telegram-bot 通过 npx 运行，无需全局安装。首次运行时会自动进入配置向导：

npx @grinev/opencode-telegram-bot

也可以随时通过 config 子命令重新配置：

npx @grinev/opencode-telegram-bot config

向导会依次询问以下配置项：

配置项	说明	示例
界面语言	选择 `6` 即简体中文	`6`
Bot Token	从 BotFather 获取的 Token	`123456789:AAxx...`
Telegram User ID	你的数字 ID	`664478408`
OpenCode API URL	默认本地地址，直接回车	`http://127.0.0.1:4096`
服务器用户名	默认 `opencode`，直接回车	`opencode`
服务器密码	可选，暂不设置直接回车跳过	（留空）
模型 Provider	你使用的模型提供商	`github-copilot`
模型 ID	默认模型 ID	`claude-opus-4.6`

配置完成后，文件保存至：

macOS：~/Library/Application Support/opencode-telegram-bot/.env
Linux：~/.config/opencode-telegram-bot/.env

语言等设置保存在同一目录下的 settings.json：

macOS：~/Library/Application Support/opencode-telegram-bot/settings.json
Linux：~/.config/opencode-telegram-bot/settings.json

启动 OpenCode Server

Bot 依赖本地的 OpenCode API，需要先把它跑起来：

opencode serve &

默认监听 http://127.0.0.1:4096。& 让它在后台运行，不占用当前终端。

macOS 提示：用 & 后台运行的进程在关闭终端后会退出。如需持久运行，推荐使用 launchd，见下方「macOS 开机自启」章节。

启动与使用

启动 Bot

npx @grinev/opencode-telegram-bot start

看到以下输出说明启动成功：

[INFO] Bot @your_bot_username started!

同样可以后台运行：

npx @grinev/opencode-telegram-bot start &

常用管理命令

# 查看运行状态
npx @grinev/opencode-telegram-bot status

# 停止 Bot
npx @grinev/opencode-telegram-bot stop

# 重新配置
npx @grinev/opencode-telegram-bot config

不要提交到 Git 仓库
不要分享给他人
配置文件路径见上方「安装与配置」章节，权限保持默认即可，不要放到公共目录

OpenCode Server 默认无密码

opencode serve 启动后不设密码，API 完全开放。由于只监听 127.0.0.1，本机以外无法直接访问，日常本地使用是安全的。

如果你的机器有公网 IP 或处于共享网络环境，建议设置密码：

export OPENCODE_SERVER_PASSWORD=your_password
opencode serve &

配置 Bot 时对应填入服务器密码即可。

两个进程都需要保持运行

Bot 正常工作依赖两个进程同时在线：

opencode serve — 本地 AI 引擎
opencode-telegram-bot start — Telegram 消息桥

电脑重启后需要重新启动两者。推荐使用系统服务管理（macOS 用 launchd，Linux 用 systemd），实现开机自启和崩溃自动重启。

macOS 开机自启（launchd）

macOS 通过 Launch Agent 管理用户级后台服务，登录后自动启动，进程崩溃自动重启。

1. 创建 OpenCode Server 服务

创建文件 ~/Library/LaunchAgents/ai.opencode.serve.plist：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>ai.opencode.serve</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/你的用户名/.opencode/bin/opencode</string>
        <string>serve</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/你的用户名/Library/Logs/opencode-serve.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/你的用户名/Library/Logs/opencode-serve.log</string>
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Users/你的用户名/.opencode/bin</string>
        <key>HOME</key>
        <string>/Users/你的用户名</string>
    </dict>
</dict>
</plist>

将 你的用户名 替换为实际的 macOS 用户名。可通过 whoami 命令查看。 opencode 的路径可通过 which opencode 确认。如果通过官方脚本安装，通常位于 ~/.opencode/bin/opencode。

2. 创建 Telegram Bot 服务

创建文件 ~/Library/LaunchAgents/com.grinev.opencode-telegram-bot.plist：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.grinev.opencode-telegram-bot</string>
    <key>ProgramArguments</key>
    <array>
        <string>/opt/homebrew/bin/npx</string>
        <string>@grinev/opencode-telegram-bot</string>
        <string>start</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/你的用户名/Library/Logs/opencode-telegram-bot.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/你的用户名/Library/Logs/opencode-telegram-bot.log</string>
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Users/你的用户名/.opencode/bin</string>
        <key>HOME</key>
        <string>/Users/你的用户名</string>
    </dict>
</dict>
</plist>

npx 的路径可通过 which npx 确认。Intel Mac 上通常是 /usr/local/bin/npx。

3. 加载服务

注意：两个服务的启动顺序不固定，Bot 启动时若 OpenCode Server 尚未就绪会自动重试，属正常现象。

launchctl load ~/Library/LaunchAgents/ai.opencode.serve.plist
launchctl load ~/Library/LaunchAgents/com.grinev.opencode-telegram-bot.plist

加载后立即启动，后续每次登录也会自动启动。

4. 常用管理命令

# 查看运行状态
launchctl list | grep -E 'opencode|telegram'

# 停止服务
launchctl unload ~/Library/LaunchAgents/ai.opencode.serve.plist
launchctl unload ~/Library/LaunchAgents/com.grinev.opencode-telegram-bot.plist

# 重启服务（卸载 + 加载）
launchctl unload ~/Library/LaunchAgents/ai.opencode.serve.plist && \
launchctl load ~/Library/LaunchAgents/ai.opencode.serve.plist

# 查看日志
tail -f ~/Library/Logs/opencode-serve.log
tail -f ~/Library/Logs/opencode-telegram-bot.log

配置说明：

RunAtLoad：登录时自动启动
KeepAlive：进程崩溃后自动重启
日志文件位于 ~/Library/Logs/，方便排查问题

总结

opencode-telegram-bot 本质上是一个很轻的工具，没有复杂的架构，没有额外的云服务依赖。它做的事情很克制：把 Telegram 变成本地 OpenCode 的远程终端。

这种设计的价值在于它解决的场景足够真实——不是所有人都随时坐在开发机前，但好的想法不会等你回家。

适合的场景：

个人项目只在家里的电脑上，需要远程驱动
移动办公，手机随时发 prompt 给本地环境处理
不想把代码或 API Key 托管到任何云端服务

整体配置耗时不超过 10 分钟，门槛很低。如果你本地已经在用 OpenCode，不妨花几分钟把这座桥搭起来。