开源教程：用飞书长连接把本地 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. 整体架构

整体链路是：

text 复制代码

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

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

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

text 复制代码

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

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

3. 准备环境

需要准备：

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

检查 Node：

powershell 复制代码

node -v
npm -v

检查 Codex：

powershell 复制代码

codex --version

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

4. 下载源码并安装依赖

GitHub：

powershell 复制代码

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

Gitee：

powershell 复制代码

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

5. 配置飞书应用

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

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

6. 配置 `.env`

复制配置模板：

powershell 复制代码

copy .env.example .env

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

powershell 复制代码

npm run start

打开管理页：

text 复制代码

http://127.0.0.1:3457

健康检查：

text 复制代码

http://127.0.0.1:3457/health

正常时应看到：

json 复制代码

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

8. 设置页说明

设置页地址：

text 复制代码

http://127.0.0.1:3457/settings

可以修改：

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

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

9. 飞书端怎么用

飞书里先发：

text 复制代码

/status

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

常用命令：

text 复制代码

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

10. 长任务进度心跳

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

text 复制代码

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

心跳示例：

text 复制代码

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

飞书里可以动态改心跳：

text 复制代码

/heartbeat 30s

11. Windows 服务部署

先准备服务包装器：

powershell 复制代码

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

管理员 PowerShell 里安装：

powershell 复制代码

.\install-service.ps1

查看状态：

powershell 复制代码

.\status-service.ps1

停止：

powershell 复制代码

.\stop-service.ps1

卸载：

powershell 复制代码

.\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

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

1. 项目是什么

2. 整体架构

3. 准备环境

4. 下载源码并安装依赖

5. 配置飞书应用

6. 配置 .env

7. 启动服务

8. 设置页说明

9. 飞书端怎么用

10. 长任务进度心跳

11. Windows 服务部署

12. 总结

6. 配置 `.env`