
> **场景**：在腾讯云 Lighthouse Ubuntu 服务器上，把 CodeBuddy CLI 通过 open-im 桥接到飞书，让"飞书发一句话 → 服务器上 Agent 自动跑起来"。
>
> **难度**：入门到中级 | **阅读时间**：约 10 分钟
>
> **关键词**：CodeBuddy CLI、open-im、飞书机器人、systemd、Node.js、远程办公

---

## 一、为什么折腾这件事

我手里有一台 Lighthouse 云主机（VM-0-11-ubuntu）。出门在外、地铁、带娃的间隙，希望飞书一句话就能让服务器上的 AI Agent 帮我读代码、改文件、起服务、查日志，全程不用 SSH、不用 RDP、不用打开电脑。

CodeBuddy CLI v2.97.1 自带 `gateway` 子命令，专门干这件事——把外部 IM 消息桥接给本地 Agent。但官方文档不会告诉你那些"上线后才会踩到"的坑。这篇就把整个流程和我踩过的 6 个坑完整复盘一遍。

最终架构：

```
飞书机器人 webhook
       ↓
 [公网 IP:xxxx]  CodeBuddy CLI Gateway
       ↓
 [localhost:xxxx] open-im (飞书消息桥接)
       ↓
   CodeBuddy Agent 执行任务
```

---

## 二、第一关：CodeBuddy CLI Gateway 起步

CodeBuddy CLI 直接 npm 全局安装即可：

```bash
npm install -g @tencent-ai/codebuddy-cli
codebuddy --version   # v2.97.1
```

启动 Gateway：

```bash
codebuddy gateway --port xxxx --remote-control feishu
```

关键参数 `--remote-control` 决定接哪种 IM。支持的客户端类型：

| 值 | 用途 |
|----|------|
| `feishu` | 飞书机器人（国内版） |
| `lark` | Lark（飞书国际版） |
| `wecom` | 企业微信群机器人 |
| `dingtalk` | 钉钉群机器人 |

### 第一个坑：默认 local 模式，外网打不进来

直接 `codebuddy gateway` 默认是本地模式，不会建任何 tunnel。想让飞书 webhook 能打进来，要么用 Cloudflare Tunnel，要么自己解决可达性。

我选了**公网 IP + 安全组白名单**，理由：

1. Lighthouse 自带固定公网 IP，免费
2. 飞书 webhook 出口 IP 段固定，可以做精确白名单
3. 配合飞书自带的 Verification Token 双因子防护，安全性可控

放行端口的安全组配置（只允许飞书出口 IP）：

```
方向：入站
协议：TCP
端口：1xxx
来源：飞书 webhook 出口段（飞书开放平台文档提供）
```

---

## 三、第二关：open-im 部署的连环 bug

CodeBuddy 端搞定，但 Gateway 不能直接吃飞书 webhook 的原始消息——需要中间人翻译。这就是 **open-im**：一个 Node 写的桥接服务，把飞书事件协议转成 CodeBuddy Gateway 能消费的 HTTP 调用。

### 3.1 先搞清装在哪

```bash
which open-im
docker ps | grep open-im
npm list -g | grep open-im
```

结果是 npm 全局安装，路径：

```
/root/.nvm/versions/node/v22.22.2/lib/node_modules/@wu529778790/open-im
```

入口脚本 `dist/cli.js dev`。**不是 Docker，不是 systemd**——之前是裸进程跑在 nohup 里，重启服务器就裸奔。第一件事就是把它 systemd 化。

### 3.2 端口冲突 EADDRINUSE

启动报错：

```
Error: listen EADDRINUSE: address already in use 0.0.0.0:39281
```

老进程还在霸占 3xxxx/3xxx。先 kill：

```bash
ss -tnlp | grep 3xxxx/3xxx
kill -9 <PID>
```

但根本修复是 systemd 化，让 `ExecStop` 接管生命周期。

### 3.3 systemd 单元的 PATH 陷阱

写好 unit 文件启动失败：

```
nvm: command not found
node: command not found
```

systemd 默认用极简 PATH，nvm 装的 node 完全不在里面。修复：

```ini
# /etc/systemd/system/open-im.service
[Unit]
Description=open-im (Feishu bridge for CodeBuddy)
After=network-online.target

[Service]
Type=simple
User=root
WorkingDirectory=/root
Environment="PATH=/root/.nvm/versions/node/v22.22.2/bin:/usr/bin:/bin"
Environment="NODE_ENV=production"
ExecStart=/root/.nvm/versions/node/v22.22.2/bin/node \
  /root/.nvm/versions/node/v22.22.2/lib/node_modules/@wu529778790/open-im/dist/cli.js dev
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
```

```bash
systemctl daemon-reload
systemctl enable --now open-im
systemctl status open-im
```

**关键三件套**：完整 PATH、绝对路径 ExecStart、`Restart=on-failure` 自愈。

### 3.4 飞书消息提取的 fallback bug（最隐蔽的一坑）

服务起来了，飞书"能收到我的消息但发不出回复"。`journalctl -u open-im -f` 看到：

```
TypeError: Cannot read properties of undefined (reading 'content')
    at extractText (event-handler.js:42:18)
```

定位到 `event-handler.js`：

```javascript
// 原始有问题的代码
const text = event.message.content?.post ?? event.message.content?.zh_cn;
```

逻辑陷阱：飞书消息有三种主要形态——`post`（富文本）、`zh_cn`（中文卡片）、**普通文本**。原代码只兜底前两种，普通文本两个分支都 `undefined`，下游 `text.trim()` 直接崩。

一行 sed 修复：

```bash
sed -i 's/content?.post ?? content?.zh_cn/content?.post ?? content?.zh_cn ?? content/' \
  /root/.nvm/versions/node/v22.22.2/lib/node_modules/@wu529778790/open-im/dist/handlers/event-handler.js
systemctl restart open-im
```

加 `?? content` 兜底，普通文本走通。

### 3.5 中文文件名扩展名丢失（media-storage.js）

继续测试，飞书发图片、文档时下载失败：

```
ENOENT: no such file or directory, open '/tmp/open-im-images/abc123'
```

两个问题叠加：

**问题 A**：`/tmp/open-im-images` 目录根本不存在。

```bash
mkdir -p /tmp/open-im-images
chmod 755 /tmp/open-im-images
```

**问题 B**：`media-storage.js` 用 `sanitizeName(file.name)` 过滤危险字符时，把中文一并清掉，结果只剩 `.`，**扩展名也连带丢失**。文件存成 `产品规格说明.docx` 后实际落盘是 `_`，后续 MIME 识别失败。

修复思路是**先取扩展名再做清洗**：

```javascript
const path = require('path');
const ext = path.extname(file.name);                          // .docx
const base = sanitizeName(path.basename(file.name, ext));    // 清洗主名
const finalName = `${base || 'file'}${ext}`;                  // 组合回扩展名
```

### 3.6 飞书 ACL：access denied

修完代码消息能进 Gateway，但日志显示：

```
[ACL] reject open_id=ou_77xxx
```

open-im 自带访问控制（很合理，避免被陌生人调用消耗 Token）。配置在 `/root/.open-im/config.json`：

```json
{
  "acl": {
    "allowedOpenIds": [
      "ou_77xxx"
    ]
  }
}
```

把自己的 open_id 加白后 `systemctl restart open-im`。

> **怎么拿 open_id？** 让飞书机器人加你为好友后随便发条消息，从 open-im 日志的 reject 行直接抠出来即可。

---

## 四、第三关：端到端联调

收发链路通了之后我的标准 SOP：

```bash
# 终端 A：盯飞书桥接日志
journalctl -u open-im -f

# 终端 B：盯 CodeBuddy Gateway 日志
codebuddy gateway --port xxx --remote-control feishu --verbose

# 飞书发：帮我看下 /var/log/nginx/error.log 最后 50 行
```

应当看到：

```
open-im:  receive event → forward to gateway
gateway:  task accepted, agent started
gateway:  agent reply sent back to open-im
open-im:  reply delivered to feishu
```

整个链路平均响应时间 4-8 秒（取决于 Agent 模型），可接受。

---

## 五、踩坑总结：systemd + Node 服务化清单

把这次遇到的问题归纳成一张表，下次部署任何 Node 服务都能套用：

| 检查项 | 常见错误 | 修复 |
|--------|---------|------|
| PATH 完整 | nvm/local bin 没加 | `Environment="PATH=..."` |
| HOME 设置 | 默认无 HOME | `Environment="HOME=/root"` |
| ExecStart 用绝对路径 | 写 `node` | 写完整 nvm 路径 |
| Restart 自愈 | 服务崩了不重启 | `Restart=on-failure` |
| WorkingDirectory | 相对路径解析错 | 显式声明 |
| 媒体目录 | `/tmp/xxx` 不存在 | 提前 `mkdir -p` |
| 字符串清洗 | 扩展名连带丢失 | `path.extname` 单独保留 |
| 消息 fallback | 普通文本无兜底 | `?? content` 兜底 |
| ACL 白名单 | 默认拒绝 | 把自己 open_id 加进去 |

---

## 六、最终拓扑

```
飞书机器人 webhook
    ↓
[公网 IP:xxx]  codebuddy gateway --remote-control feishu
    ↓
[localhost:xxx] open-im (systemd)
    ↓
CodeBuddy Agent (CLI)
    ↓
本地文件系统 / 终端命令 / npm / git / docker ...
```

启动顺序（systemd `After=` 依赖）：

```
network-online.target → open-im → codebuddy-gateway
```

---

## 七、后续可优化项

1. **多 open_id 协作**：把团队成员的 open_id 都加进 ACL，做协作 AI Agent 群
2. **健康检查 + 告警**：`systemd` 加 `OnFailure=`，挂了往自己飞书推告警
3. **Verification Token 验签**：在 webhook 入口校验飞书签名，防伪造请求
4. **请求审计日志**：把所有飞书指令落 SQLite，方便回溯
5. **多 Agent 并存**：见我下一篇《把 Cursor CLI 也接入飞书》——cc-connect 与 open-im 在同一台机器上共存

---

## 八、写在最后

这次集成踩了 6 个坑，其中 4 个是**第三方默认值留下的隐性陷阱**（systemd 不传 PATH、open-im 的 ACL、media-storage 的 sanitize、event-handler 的 fallback），2 个是**网络拓扑选择**（local vs tunnel、公网 IP 安全组）。

最大的体会：**所有 Node 服务上线前一定要先用 systemd 走一遍冷启动**。nohup 跑得再顺，也是定时炸弹。

如果你也想把 AI Agent 接到 IM，希望这篇能帮你少踩几个坑。下一篇我会写如何把 **Cursor CLI** 通过 cc-connect 也接进来，与 CodeBuddy 共存协作。

---


场景：在腾讯云 Lighthouse Ubuntu 服务器上，把 CodeBuddy CLI 通过 open-im 桥接到飞书，让"飞书发一句话 → 服务器上 Agent 自动跑起来"。

把 CodeBuddy CLI 接入飞书：一台 Lighthouse 上的 AI Agent 远程办公实录

人工智能

本文详细介绍在腾讯云Lighthouse Ubuntu服务器上，将CodeBuddy CLI通过open-im桥接到飞书机器人的完整流程。内容涵盖Gateway配置、open-im部署的systemd服务化、端口冲突、消息提取fallback修复、中文文件名处理及飞书ACL设置等6个关键坑点解决方案。最终实现飞书指令触发服务器Agent自动执行代码阅读、文件修改等任务，提升远程办公效率。适合具备Node.js基础、寻求IM集成AIAgent自动化方案的开发者参考。

文件系统

服务器

云主机

Docker

SQLite

Agent

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

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

lighthouse

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

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

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

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

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

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

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

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

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

社区新版编辑器体验调研

本文详细介绍在腾讯云Lighthouse Ubuntu服务器上，将CodeBuddy CLI通过open-im桥接到飞书机器人的完整流程。内容涵盖Gateway配置、open-im部署的systemd服务化、端口冲突、消息提取fallback修复、中文文件名处理及飞书ACL设置等6个关键坑点解决方案。最终实现飞书指令触...

把 CodeBuddy CLI 接入飞书：一台 Lighthouse 上的 AI Agent 远程办公实录-腾讯云开发者社区-腾讯云

把 CodeBuddy CLI 接入飞书：一台 Lighthouse 上的 AI Agent 远程办公实录

把 CodeBuddy CLI 接入飞书：一台 Lighthouse 上的 AI Agent 远程办公实录

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐