# opencode-feishu

**Repository Path**: ai_59/opencode-feishu

## Basic Information

- **Project Name**: opencode-feishu
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-17
- **Last Updated**: 2026-03-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 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. 安装与构建

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

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

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

### 方式二：直接运行

```bash
npm install
npm run build
node bin/opencode-feishu
```

## 3. 配置说明

### 交互式配置（推荐）

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

```bash
opencode-feishu onboard
```

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

### 手动配置

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

```bash
mkdir -p ~/.config/opencode-feishu
```

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

```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. 启动服务

### 基本启动

```bash
opencode-feishu
# 或
opencode-feishu start
```

### 指定配置文件

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

### 通过环境变量

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

### 开发模式

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

```bash
npm run dev
```

### 查看帮助

```bash
opencode-feishu --help
opencode-feishu onboard --help
```

## 5. 飞书后台配置指南

为了让机器人能收到消息，你需要在[飞书开发者后台](https://open.feishu.cn/app)进行如下配置：

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 |