feishu-agent-bridge · 快速开始

快速开始

装好 Bridge、打开本机网页控制台，再在控制台里启动服务、添加第一个 Bridge 机器人。全程大约几分钟，命令行部分只有两条命令。

前置要求

  • Node.js ≥ 20（npm 包 engines 声明为 >=20.0.0）。
  • 一个登录好的 AI 后端，二选一：
    • Codex CLI：npm i -g @openai/codex && codex login；
    • Claude Code：SDK 随桥内置、复用本机 claude 登录态，首次按需下载约 265MB。
  • 一个飞书 / Lark 账号（用来扫码创建机器人）。

两步安装

# 前置：Node ≥ 20，本机已装 Codex CLI 或 Claude Code
# 1. 全局安装 Bridge
npm i -g @modelzen/feishu-codex-bridge

# 2. 打开本机网页控制台（启动服务、添加好机器人后即可 Ctrl+C 关闭）
feishu-codex-bridge web
后台常驻服务必须全局安装（npm i -g），别用 npx——服务里硬编码了 CLI 路径，npx 临时缓存会被清理。前台单次运行用 npx 没问题。

扫码建机器人

feishu-codex-bridge web 会打开本机网页控制台（只绑 127.0.0.1，每次启动带随机 token 鉴权）。剩下的步骤全在网页里点：

  1. 启动后台服务。控制台没检测到 daemon 时是只读预览，页面上有「启动」按钮，一键把后台服务跑起来（会注册成系统服务、开机 / 登录自启、崩溃自动拉起）。
  2. 扫码添加机器人。用飞书扫控制台里的二维码创建你的第一个 Bridge 机器人。
  3. 按 checklist 开权限 / 订阅事件。控制台会列出需要开启的权限和事件订阅，逐项点完即可，不用碰命令行。
  4. 建第一个项目。在飞书里私聊机器人 → 控制台菜单「新建项目」→ 绑定一个本地目录 → 选后端（Codex / Claude）→ 机器人自动建好群、置顶命令说明、把你拉进去。
私聊机器人弹出的管理台卡片，全部操作都是按钮
私聊发任意消息 → 弹出管理台卡片：新建项目、项目列表、设置、诊断、重连、版本更新，全程点按钮。
「新建项目」表单：填名字、选群类型
「新建项目」表单：填名字、选群类型，机器人自动建群拉你进去。

建群时选哪种模式？

建群时挑一种模式，它决定了怎么跟它聊、适合什么场景：

群类型会话形态适合
👥 多话题群主群区 @ 它开新话题，每个话题是一条独立会话（各有各的上下文、互不干扰），进了话题后免 @ 连着聊多人协作：每人、每件任务各开各的话题；一个人并行推进几件事也用它
💬 单会话群整个群就是一条连续会话，谁发消息都接着上文、全程免 @个人单线深入，像私聊一样直接说

两种随时能各建一个。后端也一样：Codex 群和 Claude 群可以同时存在，建项目时按需选。

发第一条消息验证

进入机器人建好的项目群，@ 机器人说一句话，比如：

@机器人 看一下这个目录里有什么，给我一份三句话的项目介绍

它会在这个群绑定的目录里跑 Codex / Claude，边跑边把推理、命令、改动、结果更新到一张流式卡片上；卡片上的 ⏹ 可随时终止。看到卡片开始滚动更新，就说明桥已经通了。

流式卡片：代码块、富文本实时输出
代码块、富文本实时输出——不是干等一个最终答复，而是看着它一步步把活干成。

视频教程

更习惯跟着视频装？作者录了一遍完整安装使用流程：

不想自己敲？发给 AI 替你装

把下面这段发给 Codex / Claude 等 AI agent，让它替你装好并跑起来：

帮我在这台电脑上安装并跑起来 feishu-codex-bridge:

1) 先 node -v 确认有 Node.js(≥20)，没有就先装好;
2) 再 codex --version 确认已经安装了 codex CLI，没有就先装好;
3) 全局安装:
   npm i -g @modelzen/feishu-codex-bridge
4) 前台运行，打开本机 Web 控制台:
   feishu-codex-bridge web
   它一启动会打印一个 http://127.0.0.1:xxxx/?token=... 的链接。
5) 把那个链接发给我;
6) 然后用文字告诉我接下来怎么做:
   - 我在浏览器打开这个链接;
   - 点页面上的「启动」按钮，把后台服务跑起来;
   - 启动后页面会自动进入可写控制台，在里面扫码添加我的第一个飞书机器人;
   - 成功创建机器人后，前台那条 feishu-codex-bridge web 就可以 Ctrl+C 关掉，不影响后台服务。

下一步