![](https://developer.qcloudimg.com/http-save/yehe-7353521/504e2fc35799c48d056fca8e40693da1.jpg)

## TL;DR

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

---

## 引言

两种场景，同一个痛点。

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

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

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

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

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

---

## 工具介绍

[opencode-telegram-bot](https://github.com/grinev/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 已安装

```bash
which opencode && opencode --version
```

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

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

如果尚未安装，参考 [OpenCode 官方文档](https://opencode.ai) 完成安装。

### 创建 Telegram Bot

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

### 获取自己的 Telegram User ID

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

1. 搜索 [@userinfobot](https://t.me/userinfobot)
2. 发送任意消息，它会返回你的数字 ID

---

## 安装与配置

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

```bash
npx @grinev/opencode-telegram-bot
```

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

```bash
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，需要先把它跑起来：

```bash
opencode serve &
```

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

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

---

## 启动与使用

### 启动 Bot

```bash
npx @grinev/opencode-telegram-bot start
```

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

```
[INFO] Bot @your_bot_username started!
```

同样可以后台运行：

```bash
npx @grinev/opencode-telegram-bot start &
```

### 常用管理命令

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

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

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

### 实际使用

启动后，打开 Telegram 找到你创建的 Bot，直接发消息即可。无论是文字 prompt、代码问题，还是发一张截图让它分析，Bot 都会转发给本地的 OpenCode 处理，并将结果实时返回。

在外面用手机、在公司用办公机——只要家里的电脑保持运行，随时都能接入。

---

## 注意事项

### Bot Token 是敏感信息

Token 相当于 Bot 的密钥，拿到它就能控制你的 Bot。几条基本原则：

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

### OpenCode Server 默认无密码

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

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

```bash
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
<?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
<?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 尚未就绪会自动重试，属正常现象。

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

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

#### 4. 常用管理命令

```bash
# 查看运行状态
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，不妨花几分钟把这座桥搭起来。


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

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

编程语言

开发工具

后端

使用opencode-telegram-bot将Telegram变成远程终端，10分钟快速配置，无需开放端口，代码始终保留在本地。支持文字、图片、语音输入，随时驱动本地AI编码环境，解决灵感闪现却不在电脑前的痛点。适合个人开发者远程办公场景，安全便捷地管理本地项目。

日志文件

服务器

Linux

Agent

4核4G3M云服务器 新用户低至38元/年！

2026采购季 | AI焕新·智启新局

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

用 Telegram 远程操控本地 OpenCode：opencode-telegram-bot 实战指南-腾讯云开发者社区-腾讯云

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

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

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐