# feishu-bot-bootstrap

**Repository Path**: hackerwjz/feishu-bot-bootstrap

## Basic Information

- **Project Name**: feishu-bot-bootstrap
- **Description**: https://github.com/Hoper-J/feishu-bot-bootstrap
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-13
- **Last Updated**: 2026-05-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">
  <img src="./build/icon.png" alt="feishu-bot-bootstrap" width="128" height="128" />

  <h1>飞书机器人引导工具</h1>

<strong>为 OpenClaw 等下游 AI 应用一次性配好飞书自建应用</strong>

  <p>
    <a href="https://www.npmjs.com/package/feishu-bot-bootstrap"><img src="https://img.shields.io/npm/v/feishu-bot-bootstrap?color=cb3837&logo=npm" alt="npm version" /></a>
    <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/feishu-bot-bootstrap?color=43853d&logo=node.js&logoColor=white" alt="node" /></a>
    <a href="./LICENSE"><img src="https://img.shields.io/npm/l/feishu-bot-bootstrap?color=blue" alt="license" /></a>
  </p>

  <p>
    <a href="./README-EN.md">English</a>
    · <a href="#一键配置">一键配置</a>
    · <a href="#使用流程详细">使用流程</a>
    · <a href="#openclaw-集成">OpenClaw 集成</a>
    · <a href="#常见问题">FAQ</a>
  </p>
</div>

---

`feishu-bot-bootstrap` 自动化飞书开放平台上**创建应用 → 开机器人能力 → 导入权限 → 订阅事件和回调 → 发布版本 → 提取凭证**这整套手动流程。扫一次码登录，跑完拿到可用的 `App ID` / `App Secret` 交给下游 AI 应用使用。

## 一键配置

```bash
npx feishu-bot-bootstrap --headless --app-name "MyBot"
```

扫码登录 → CLI 自动化点完所有步骤 → 30-60 秒后终端打印 `App ID` / `App Secret`，结果写入 `~/.feishu-bot-bootstrap/runs/<timestamp>/result.json`。

![演示](./assets/demo.gif)

### OpenClaw

如果下游是 OpenClaw，加 `--write-openclaw` 让 CLI 顺手把飞书渠道写进本机的 `openclaw.json`:

```bash
npx feishu-bot-bootstrap --headless --write-openclaw --app-name "MyBot" --preset open-group
```

CLI 会自动探测 OpenClaw 配置路径（前提是 `openclaw` 命令可用）。详细参数见 [OpenClaw 集成](#openclaw-集成)。

---

## 使用流程

以 headless 模式（`--headless`）为例。命令启动后，终端会打印二维码:

```
[feishu-bot-bootstrap] 等待登录并准备控制台
[feishu-bot-bootstrap] 请使用飞书移动端扫描下方二维码登录：
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
█ ▄▄▄▄▄ █▄▄███▄▄█ ▀█▄█ ▄ ▄█ ▄▄▄▄▄ █
█ █   █ █ ▀█ ▄▄▄█▀▀▀ ▀███▄█ █   █ █
█ █▄▄▄█ █▄ ▄▄▀▄ ▄ █▀  ▀▄███ █▄▄▄█ █
...
```

打开飞书 App → 消息 → 右上角 + → 点开扫一扫，对着终端扫一下，然后在手机上确认登录，之后的权限配置都会自动完成：

```
[feishu-bot-bootstrap] 创建或打开应用
[feishu-bot-bootstrap] 启用机器人能力
[feishu-bot-bootstrap] 配置权限
[feishu-bot-bootstrap] 权限：打开权限页面
[feishu-bot-bootstrap] 权限：打开批量导入/导出弹窗
[feishu-bot-bootstrap] 权限：切换到导入页签
[feishu-bot-bootstrap] 权限：粘贴权限 JSON
[feishu-bot-bootstrap] 权限：确认导入的权限
[feishu-bot-bootstrap] 权限：提交开通申请
[feishu-bot-bootstrap] 提取凭证
[feishu-bot-bootstrap] 配置事件订阅
[feishu-bot-bootstrap] 启动临时飞书长连接客户端
[feishu-bot-bootstrap] 事件：打开添加事件弹窗
[feishu-bot-bootstrap] 事件：选择 消息与群组 / 接收消息
...
[feishu-bot-bootstrap] 配置回调订阅
[feishu-bot-bootstrap] 校验凭证
[feishu-bot-bootstrap] App ID：cli_xxxxxxxxxxxxxxxx
[feishu-bot-bootstrap] App Secret：xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
[feishu-bot-bootstrap] 结果已写入 /Users/you/.feishu-bot-bootstrap/runs/<timestamp>/result.json
```

你可以直接复制的 `App ID` / `App Secret` 贴到下游配置或者给 AI 自己填。如果下游是 OpenClaw，也可以加 `--write-openclaw` 让 CLI 直接帮你写（见 [OpenClaw 集成](#openclaw-集成)）

## 产物结构

`result.json` 的主要字段:

```json
{
  "status": "succeeded",
  "app": { "name": "MyBot", "description": "MyBot 的描述" },
  "credentials": {
    "appId": "cli_xxxxxxxxxxxxxxxx",
    "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  "subscriptions": {
    "eventDeliveryMode": "long-connection",
    "callbackDeliveryMode": "long-connection",
    "events": [
      /* 消息被 reaction / 接收消息 等 */
    ],
    "callbacks": [
      /* 卡片回传交互 等 */
    ]
  },
  "publish": { "enabled": true, "version": "0.0.1" },
  "validation": { "ok": true, "code": 0, "expire": 7185 }
}
```

默认路径 `~/.feishu-bot-bootstrap/runs/<timestamp>/result.json`，想改位置用 `--output-dir`。

> [!note]
> `App Secret` 会同时出现在 stdout、`result.json`、`--events-jsonl` 的事件流里。

## 常见场景

### 想看浏览器操作（本地调试）

```bash
npx feishu-bot-bootstrap --app-name "MyBot"
```

去掉 `--headless` 会弹出一个 Chrome 窗口（仅图形化界面可用），然后会完整展示整个 bootstrap 流程。登录二维码会显示在浏览器，同样用手机扫码登录即可。

### 只要凭证，不发布

```bash
npx feishu-bot-bootstrap --headless --app-name "MyBot" --no-publish
```

应用会停在开发前的状态。

### 脚本 / 管道消费

```bash
npx feishu-bot-bootstrap --headless --app-name "MyBot" --json
```

`--json` 模式下 stdout 只输出 result JSON，过程日志默认静默，错误走 stderr + 非零退出码。脚本里直接取字段:

```bash
APP_SECRET=$(npx feishu-bot-bootstrap --headless --app-name "MyBot" --json | jq -r '.credentials.appSecret')
```

### 写入 OpenClaw 配置

```bash
npx feishu-bot-bootstrap --headless --app-name "MyBot" --write-openclaw
```

如果本机有 `openclaw` CLI，工具会自动探测 OpenClaw 的配置路径，把飞书渠道填进 `openclaw.json`。详见 [OpenClaw 集成](#openclaw-集成)。

## 参数速查

完整列表走 `npx feishu-bot-bootstrap --help`。下面是最常用的:

| 参数                                          | 说明                                                                      |
| --------------------------------------------- | ------------------------------------------------------------------------- |
| `--app-name <name>`                           | 飞书应用名称（默认 `OpenClaw`）                                           |
| `--app-description <text>`                    | 应用描述（默认 `OpenClaw`）                                               |
| `--output-dir <path>`                         | `result.json` 和 artifacts 写入目录                                       |
| `--events-jsonl <path>`                       | 进度事件 NDJSON 输出                                                      |
| `--headless`                                  | 无界面模式，登录二维码打到终端                                            |
| `--no-publish`                                | 跳过发布步骤                                                              |
| `--json`                                      | stdout 只输出 result JSON，过程日志静默                                   |
| `--keep-browser-open`                         | 完成后不关浏览器，方便人工检查                                            |
| `--enable-sensitive-group-message-permission` | 申请飞书敏感权限：非 @ 群消息                                             |
| `--lang zh\|en`                               | 切换 CLI 语言（默认中文）                                                 |
| `--print-spec`                                | 不执行，只打印解析后的运行配置                                            |
| `--save-spec <path>`                          | 保存本次参数为 spec 文件，便于复用                                        |
| `--spec <path>`                               | 从 spec 文件加载配置                                                      |
| `--user-data-dir <path>`                      | 指定浏览器 profile 路径（默认 `~/.feishu-bot-bootstrap/browser-profile`） |
| `--browser-path <path>`                       | 指定 Chromium 系浏览器可执行文件                                          |

## OpenClaw 集成

`--write-openclaw` 开启后，CLI 在 bootstrap 成功后把飞书渠道的配置写进 OpenClaw 的 `openclaw.json`。相关参数都以 `--openclaw-` 开头。

### 渠道行为 preset

飞书渠道有四个主要行为字段（`dmPolicy` / `groupPolicy` / `requireMention` / `streaming`），预设了三组常用组合:

| preset        | `dmPolicy` | `groupPolicy` | `requireMention` | `streaming` |
| ------------- | ---------- | ------------- | ---------------- | ----------- |
| `mention-bot` | `pairing`  | `open`        | `true`           | `true`      |
| `dm-first`    | `pairing`  | `disabled`    | `true`           | `true`      |
| `open-group`  | `pairing`  | `open`        | `false`          | `true`      |

- `mention-bot` —— 群聊开放，但只回 @ 的消息（**默认**）
- `dm-first` —— 关闭群聊，只用私聊
- `open-group` —— 群聊开放，任何消息都回

传 `--write-openclaw` 不指定 `--preset`，走 `mention-bot`。

### 单独覆盖字段

不想用 preset，可以直接写字段:

- `--openclaw-dm-policy {pairing|allowlist|open}`
- `--openclaw-group-policy {allowlist|open|disabled}`
- `--openclaw-allow-from a@example.com,b@example.com`（`dmPolicy=allowlist` 时生效）
- `--openclaw-group-allow-from chat-id-a,chat-id-b`（`groupPolicy=allowlist` 时生效）
- `--openclaw-require-mention {true|false}`
- `--openclaw-streaming {true|false}`
- `--openclaw-reply-in-thread {enabled|disabled}`

显式传的字段覆盖 preset 里的同名字段。

### 备份与恢复

每次写入前会自动备份旧 `openclaw.json`，文件名 `openclaw.json.bak-<ISO 时间戳>`。

如果写坏了想回滚:

```bash
npx feishu-bot-bootstrap --restore-openclaw-backup
```

默认恢复最新的备份。

### 非 @ 群消息

"机器人在群里响应任何消息"需要两层一起开:

- **飞书侧**：默认不把非 @ 的群消息投递给机器人，要申请敏感权限 `im:message.group_msg`（通过 `--enable-sensitive-group-message-permission`）
- **OpenClaw 侧**：`requireMention=false`，由 `--preset open-group` 提供

**传 `--preset open-group` 会自动把飞书侧的敏感权限也一起申请**:

```bash
npx feishu-bot-bootstrap --write-openclaw --preset open-group
```

等价于:

```bash
npx feishu-bot-bootstrap --write-openclaw --preset open-group --enable-sensitive-group-message-permission
```

如果只想单开飞书侧（收全量群消息但只回 @ 消息，比如做日志 / 分析），直接用 `--enable-sensitive-group-message-permission` 加默认 preset 即可。

### 飞书配置

bootstrap 跑完后，还有两步飞书侧的人工操作：

<details>
<summary>1. 配对（必需）</summary>

打开飞书 → 用搜索（或快捷键 `Ctrl+K` / `Command+K`）搜刚刚发布的应用：

![搜索应用](./assets/openclaw/pairing-search.png)

进入单聊后随便发一段文字。OpenClaw 会回一行 `openclaw pairing approve feishu ...` 命令，复制最后这行：

![复制配对命令](./assets/openclaw/pairing-copy-command.png)

回到本地终端执行：

![终端执行配对命令](./assets/openclaw/pairing-run-terminal.png)

至此飞书渠道才真正配通。可以开始和 🦞 对话：

![完成配对后聊天](./assets/openclaw/pairing-success.png)

> [!note]
>
> 配对**必须**做，没配对前从飞书往应用发消息不会有任何回应：
>
> ![未配对时无回应](./assets/openclaw/pairing-no-reply-before.png)
>
> 另外，飞书组织如果没完成**企业法人认证**或**加盖公章授权书认证**，机器人无法对外共享 —— 外部体验群和外部单聊都不支持，对方必须先加进自己的组织：
>
> ![外部共享需要企业认证](./assets/openclaw/pairing-external-org.png)

</details>

<details>
<summary>2. 加群（可选）</summary>

群聊右上角 `...` → 设置 → 群机器人：

![群设置入口](./assets/openclaw/group-bots-menu.png)

点击「添加」：

![添加群机器人](./assets/openclaw/group-add.png)

选刚发布的应用：

![选择机器人](./assets/openclaw/group-select-bot.png)

点击「添加」：

![确认添加](./assets/openclaw/group-confirm-add.png)

群里 `@` 机器人即可对话：

![群里 @ 对话](./assets/openclaw/group-mention-chat.png)

如果用了 `--preset open-group --write-openclaw`，飞书侧 + OpenClaw 侧会配置为「接收 + 响应非 @ 消息」，后期如果想切换为不需要 @，命令行执行：

```bash
openclaw config set channels.feishu.requireMention false --strict-json
openclaw gateway restart
```

</details>

## 常见问题

**Q: 已经有同名应用，会复用吗？**
A: 默认**不复用**，会新建一个。

**Q: 反复测试会在飞书后台留下一堆应用吗？**
A: 会。默认每次新建，不清理。请在开发者后台手动删掉不用的测试应用，避免企业下积累僵尸应用。

**Q: 能指定用已有的 Chrome 而不是托管 Chromium 吗？**
A: `--browser-path /path/to/chrome`，或者让 CLI 自动探测系统 Chrome/Edge。

**Q: 只支持 Chromium 系浏览器吗？**
A: 是的。Safari / Firefox 不支持。

## 本地开发

```bash
pnpm install
pnpm test         # 单元测试
pnpm typecheck    # 类型检查
pnpm check        # lint + format
pnpm cli --help   # 在本仓库内跑 CLI
```