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

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

一键配置

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

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

OpenClaw

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

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

CLI 会自动探测 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 集成）

产物结构

result.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 的事件流里。

常见场景

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

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

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

只要凭证，不发布

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

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

脚本 / 管道消费

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

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

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

写入 OpenClaw 配置

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

如果本机有 openclaw CLI，工具会自动探测 OpenClaw 的配置路径，把飞书渠道填进 openclaw.json。详见 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 [email protected],[email protected]（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 时间戳>。

如果写坏了想回滚:

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 会自动把飞书侧的敏感权限也一起申请:

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

等价于:

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

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

常见问题

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

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

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

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

本地开发

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