Opencode-Feishu 使用手册

本文档说明如何配置和启动 opencode-feishu 服务，实现通过飞书控制本地开发机上的 Opencode 实例。

和openclaw 不同，本工具只有一个功能：通过飞书管理、启动本地的opencode实例。所以安全性比openclaw高很多。

1. 前置要求

在运行本项目之前，请确保开发机已安装以下软件：

• Node.js (推荐 LTS 版本，v18+)
• Tmux (用于管理后台会话，必须在系统 PATH 中)
• Opencode (用于启动 AI 编程助手，必须在系统 PATH 中)

配合本工具工作需要一个云端的飞书机器人。配置方法请参考openclaw配合的机器人的配置方法： https://www.volcengine.com/docs/6396/2189942?lang=zh

注意，得按照上述文档中步骤三：创建飞书机器人并获取配置 所描述的一样：先配置好飞书机器人的初始版本并发布，拿到AppID、AppSecret和基础的权限；然后启动 opencode-feishu 初始化配置（见下一节的onboard内容） 连接飞书服务器；最后再回到飞书机器人的配置，进行事件配置 并发布新版。这个时候，opencode-feishu就可以正常工作了。

2. 安装与构建

方式一：全局安装（推荐）

# 在项目根目录运行
npm install
npm run build
npm link

安装完成后，opencode-feishu 命令会添加到系统 PATH，可直接在任意目录运行。

方式二：直接运行

npm install
npm run build
node bin/opencode-feishu

3. 配置说明

交互式配置（推荐）

运行 onboard 命令，按提示填写配置：

opencode-feishu onboard

配置文件将保存到 ~/.config/opencode-feishu/config.json。

手动配置

如需手动配置，创建配置文件：

mkdir -p ~/.config/opencode-feishu

编辑 ~/.config/opencode-feishu/config.json：

{
  "appId": "cli_a1b2c3...",
  "appSecret": "your_secret...",
  "encryptKey": "your_key...",
  "verificationToken": "your_token...",
  "uiMode": "text",
  "allowedUserIds": [
    "ou_123456...",
    "ou_789012..."
  ],
  "rateLimit": {
    "messagesPerSecond": 1,
    "maxMessageLength": 2000
  }
}

配置项详解

配置项	必填	说明	获取方式
appId	是	飞书应用的唯一标识	飞书开发者后台 -> 凭证与基础信息
appSecret	是	飞书应用的密钥	飞书开发者后台 -> 凭证与基础信息
encryptKey	是	用于解密事件内容	飞书开发者后台 -> 事件订阅 -> 加密策略
verificationToken	是	用于验证请求来源	飞书开发者后台 -> 事件订阅
uiMode	否	消息显示模式：text 发送文本摘要，img 发送终端截图	默认 text
allowedUserIds	否	允许控制机器人的用户白名单。留空则允许所有用户。	需要获取用户的 Open ID (可通过日志或调试获取)
rateLimit	否	消息发送频率控制	默认为 5条/秒，超过限制会排队或合并

配置文件路径优先级

启动时按以下顺序查找配置文件：

1. 命令行指定：opencode-feishu start -c /path/to/config.json
2. 环境变量：OPENCODE_FEISHU_CONFIG=/path/to/config.json
3. 默认路径：~/.config/opencode-feishu/config.json
4. 当前目录：./config.json

4. 启动服务

基本启动

opencode-feishu
# 或
opencode-feishu start

指定配置文件

opencode-feishu start -c /path/to/config.json

通过环境变量

OPENCODE_FEISHU_CONFIG=/path/to/config.json opencode-feishu

开发模式

如果正在开发或调试代码，可使用热重载模式：

npm run dev

查看帮助

opencode-feishu --help
opencode-feishu onboard --help

5. 飞书后台配置指南

为了让机器人能收到消息，你需要在飞书开发者后台进行如下配置：

1. 权限管理：

   • 开启 im:message (获取用户发给机器人的单聊消息)
   • 开启 im:message:send_as_bot (以应用身份发送消息)
   • 发布版本以生效权限。

2. 事件订阅：

   • 请求网址 URL：配置为你部署该服务的公网地址（如果本地开发，需使用内网穿透工具如 frp/ngrok）。
   • 事件类型：添加 接收消息 (im.message.receive_v1)。

6. 使用说明

启动服务后，在飞书上给机器人发送消息即可：

命令	说明
ocfn [path]	创建新的 Opencode 会话，可选指定工作目录
ocfl	列出当前所有会话
ocfa {index}	连接到指定序号的会话
ocfd	断开当前会话（会话继续运行）
ocfx [index]	退出并终止当前会话，或终止指定会话
ocfk/{key0}/{key1}/...	发送键盘按键到 Opencode
ocfh	查看帮助信息

连接会话后： 你发送的任何文本都会被转发到 Opencode 的终端中。Opencode 的输出会根据 uiMode 配置：

• text 模式：输出经过智能摘要后以文本形式发送回飞书
• img 模式：输出以终端截图形式发送回飞书（需要系统安装 Chrome）

关于 img 模式

img 模式会将 Opencode 的 TUI 界面渲染为图片发送，提供更好的视觉体验。

前置要求：

• macOS: 确保已安装 Google Chrome (/Applications/Google Chrome.app)
• Linux: 确保已安装 Chrome (/usr/bin/google-chrome)

关于 ocfk 命令

ocfk 命令用于模拟键盘按键，适用于在 Opencode 界面中进行导航、选择等操作。

按键映射：

符号	按键
u	上方向键 (Up)
d	下方向键 (Down)
l	左方向键 (Left)
r	右方向键 (Right)
t	Tab 键
e	Enter 键
esc	Escape 键
ctrl{x}	Ctrl + x 键 (如 ctrlc 表示 Ctrl+C)

使用示例：

命令	说明
ocfk/e	发送回车键
ocfk/d	发送下方向键
ocfk/d/d/d	连续发送三次下方向键
ocfk/t/e	先发送 Tab，再发送 Enter
ocfk/ctrlc	发送 Ctrl+C