开源教程：用飞书长连接把本地 Codex CLI 接入机器人，支持进度心跳和可见过程

1. 项目是什么

Feishu Codex Bridge 是一个开源的本地桥接服务。它的作用很简单：你在飞书里给机器人发需求，本地电脑上的 Codex CLI 负责执行任务，然后桥接服务把进度和结果发回飞书。

项目地址：

• GitHub：https://github.com/lutianding118-cmd/feishu-codex-bridge
• Gitee：https://gitee.com/luotianding/feishu-codex-bridge2

适合这些场景：

• 在手机飞书里远程调用本地 Codex。
• 长任务执行时，不想一直盯着电脑屏幕。
• 团队群里需要看到 Codex 当前是否还在运行。
• 不想配置公网回调地址，希望使用飞书长连接模式。

2. 整体架构

整体链路是：

飞书用户 -> 飞书开放平台长连接 -> Bridge 服务 -> 本地 Codex CLI

这里容易误解的一点是：飞书长连接只解决"飞书消息实时推给你的桥接程序"，并不会自动知道 Codex 在做什么。Codex 的进度来自本地 Codex CLI 的 JSON 事件输出，Bridge 会把这些可见事件转发到飞书。

如果 Codex 暂时没有新事件，Bridge 会按心跳间隔发送：

Codex 仍在运行
暂无新的可见过程，Codex 进程仍在运行

这样用户就不会误以为断线或卡死。

3. 准备环境

需要准备：

1. Windows 电脑。
2. Node.js 18 或更高版本。
3. Codex CLI，并且已经完成登录。
4. 一个飞书企业自建应用。

检查 Node：

node -v
npm -v

检查 Codex：

codex --version

如果 codex --version 失败，请先安装并登录 Codex CLI。

4. 下载源码并安装依赖

GitHub：

git clone https://github.com/lutianding118-cmd/feishu-codex-bridge.git
cd feishu-codex-bridge
npm install

Gitee：

git clone https://gitee.com/luotianding/feishu-codex-bridge2.git
cd feishu-codex-bridge2
npm install

5. 配置飞书应用

飞书开放平台里需要做这些：

1. 创建企业自建应用。
2. 在"凭证与基础信息"里复制 App ID 和 App Secret。
3. 在"应用能力"里启用机器人。
4. 在"事件订阅"里使用长连接模式。
5. 订阅接收消息事件，例如 im.message.receive_v1。
6. 发布或安装应用。
7. 把机器人拉进群聊，或者直接私聊机器人。

6. 配置 .env

复制配置模板：

copy .env.example .env

编辑 .env：

FEISHU_APP_ID=你的飞书 App ID
FEISHU_APP_SECRET=你的飞书 App Secret
FEISHU_VERIFICATION_TOKEN=
BRIDGE_PORT=3457
BRIDGE_AUTH_CODE=123456
DEFAULT_WORKSPACE_DIR=D:\workspace
CODEX_COMMAND=codex
TASK_HEARTBEAT_MS=60000
FEISHU_MESSAGE_MODE=direct

关键字段说明：

字段	作用
FEISHU_APP_ID	飞书应用 App ID
FEISHU_APP_SECRET	飞书应用 App Secret
DEFAULT_WORKSPACE_DIR	Codex 默认工作目录
CODEX_COMMAND	Codex 命令，通常填 codex
TASK_HEARTBEAT_MS	飞书进度心跳，默认 60 秒
BRIDGE_AUTH_CODE	管理页登录授权码

不要提交 .env，里面有密钥。

7. 启动服务

npm run start

打开管理页：

http://127.0.0.1:3457

健康检查：

http://127.0.0.1:3457/health

正常时应看到：

{
  "status": "ok",
  "codex": true
}

8. 设置页说明

设置页地址：

http://127.0.0.1:3457/settings

可以修改：

• 飞书 App ID
• 飞书 App Secret
• 默认工作区
• Codex 命令
• 飞书消息模式
• 默认心跳间隔
• 回复长度

App ID / Secret 修改后建议重启服务。

9. 飞书端怎么用

飞书里先发：

/status

如果链路正常，会返回运行状态。

常用命令：

/status
/heartbeat
/heartbeat 30s
/mode
/mode direct
/mode bridge
/run 帮我检查这个项目为什么启动失败
/list
/td
/workspace D:\workspace\demo
/reset

10. 长任务进度心跳

当 Codex 执行时间比较长时，飞书端会看到：

【Codex 已收到】
【Codex 开始处理】
【Codex 进展】
【Codex 仍在运行】
【Codex 已完成】

心跳示例：

【Codex 仍在运行】
内容: 帮我修复项目构建失败
模式: 直连模式
已运行: 5分0秒
可见过程: 正在执行工具: shell_command
队列: 当前会话没有等待项
建议: 当前会话忙，新指令会排队

飞书里可以动态改心跳：

/heartbeat 30s

11. Windows 服务部署

先准备服务包装器：

powershell -ExecutionPolicy Bypass -File .\scripts\prepare-service-wrapper.ps1

管理员 PowerShell 里安装：

.\install-service.ps1

查看状态：

.\status-service.ps1

停止：

.\stop-service.ps1

卸载：

.\uninstall-service.ps1

注意：Codex 登录态通常在当前 Windows 用户目录。服务如果用 LocalSystem 运行，可能读不到 Codex 登录态。

12. 总结

Feishu Codex Bridge 的核心价值是把"本地 Codex 执行能力"和"飞书移动端协作"连起来。长任务不再是黑盒，飞书里能看到当前是否在运行、最近可见过程、队列状态和最终结果。

项目地址：

• GitHub：https://github.com/lutianding118-cmd/feishu-codex-bridge
• Gitee：https://gitee.com/luotianding/feishu-codex-bridge2