Feishu Codex Connector

Feishu Codex Connector 是一个非官方的飞书 / Lark 机器人和本地桥接服务，用来在飞书或 Lark 聊天里运行 OpenAI Codex。你可以从私聊、群聊或文档评论发送编程任务，让 Codex 在本机受控工作区执行，并把进度和结果通过富文本卡片、消息和文档评论回传。

适合这些场景：给自己搭建飞书 Codex 机器人、把 OpenAI Codex 接入 Lark、远程驱动本地代码仓库、保留 Codex session、切换 workspace，并把飞书 App Secret 和 OpenAI API Key 放在 profile 级加密 keystore 中。

快速信息

| 项目 | 内容 | | --- | --- | | npm 包 | feishu-codex-connector | | CLI 命令 | feishu-codex | | Node.js | >=20.12.0 | | 平台 | 飞书、Lark | | Codex 认证 | OpenAI API Key、本机 Codex 状态、继承用户认证 | | 本地状态目录 | ~/.feishu-codex |

主要功能

• 从飞书 / Lark 私聊、群聊、文档评论里运行 OpenAI Codex。
• 首次运行提供 PersonalAgent 扫码向导，在终端显示二维码创建或绑定应用。
• 使用飞书 / Lark 开放平台长连接接收消息和卡片回调。
• 用富文本交互卡片展示 Codex 运行进度、命令完成状态和操作按钮。
• 在聊天里管理 workspace alias、session reset/resume、timeout、doctor 诊断和本机进程。
• App Secret 和 Codex API Key 以 profile-scoped secret reference 保存，不明文写入普通配置。
• 支持 owner、admin、user、group allow list 控制访问范围。

安装

通过 npm 安装：

npm install -g feishu-codex-connector
feishu-codex run

从源码运行：

pnpm install
pnpm build
node bin/feishu-codex.mjs run

首次启动

第一次运行会进入 PersonalAgent 扫码向导：

1. 终端渲染二维码。
2. 用飞书 / Lark App 扫码。
3. 选择或创建 PersonalAgent 应用。
4. connector 初始化 Codex agent profile。
5. 配置写入 ~/.feishu-codex/config.json，profile 状态写入 ~/.feishu-codex/profiles/<profile>/。

如果环境里有 OPENAI_API_KEY，首次初始化会使用 API key 模式；否则会优先复用本机 Codex 登录状态。

如果已有 PersonalAgent app，可以跳过扫码：

feishu-codex run \
  --app-id cli_xxx \
  --app-secret "$FEISHU_APP_SECRET"

手动创建 Profile

如果已经知道飞书 / Lark 应用凭证和目标代码目录，可以直接创建 profile：

feishu-codex profile create default \
  --tenant feishu \
  --app-id cli_xxx \
  --app-secret "$FEISHU_APP_SECRET" \
  --codex-auth api-key \
  --codex-api-key "$OPENAI_API_KEY" \
  --workspace /absolute/project/path

feishu-codex run --profile default

普通 profile config 只保存 secret 引用。App Secret 和 Codex API Key 会写入 profile-local encrypted keystore，不会明文写进 config.json。

飞书 / Lark 长连接

默认运行方式使用飞书 / Lark 开放平台长连接：

feishu-codex run --profile default

启动成功后，终端会看到 ws client ready。然后在机器人私聊或已授权群聊里发送 /status 测试消息接收。

如果 WebSocket 已连接但收不到消息，请在飞书 / Lark 开放平台检查当前应用的「事件与回调」：

1. 事件配置的订阅方式为「使用长连接接收事件」。
2. 已订阅 im.message.receive_v1。
3. 回调配置的订阅方式为「使用长连接接收回调」。
4. 如需卡片按钮，已订阅 card.action.trigger。

--poll-chat <chat_id> 只作为诊断或事件订阅尚未配置时的兜底方式。

CLI 命令

feishu-codex profile list
feishu-codex profile export default
feishu-codex run --profile default
feishu-codex start --profile default
feishu-codex status --profile default
feishu-codex stop --profile default
feishu-codex ps
feishu-codex doctor --profile default --json

飞书内命令

| 命令 | 作用 | | --- | --- | | /help | 查看帮助卡片 | | /status | 查看当前 profile、workspace、session、队列 | | /new, /reset | 重置当前 scope 的 Codex session | | /new group [name] | 创建新的飞书 / Lark 群聊并继承当前 workspace | | /resume, /resume use <nonce> | 列出并恢复当前 workspace 下的历史 session | | /cd <path> | 切换当前 scope 的 workspace | | /ws list | 查看 workspace 别名 | | /ws save <name> | 保存当前 workspace 为别名 | | /ws add <name> <path> | 保存指定路径为 workspace 别名 | | /ws use <name> | 切换到 workspace 别名 | | /ws remove <name> | 删除 workspace 别名 | | /stop | 停止当前 scope 的运行 | | /timeout <minutes\|off\|default> | 设置当前 scope 的 idle timeout | | /config, /config show | 修改或查看配置 | | /invite user @name, /invite admin @name, /invite group | 管理访问控制 | | /remove user @name, /remove admin @name, /remove group | 移除访问控制 | | /doctor, /doctor detail | 诊断当前 connector 状态 | | /ps, /exit <id>, /reconnect | 查看、停止或重连本机 connector 进程 |

安全说明

• 普通 profile 配置不会明文保存 App Secret 或 OpenAI API Key。
• 敏感信息通过 profile-scoped secret reference 解析。
• 输出渲染会对常见 API key 和 app secret 模式做脱敏。
• connector 会显式提示 Codex 不要读取或泄露桥接服务的 secret 文件。
• 当前设计以个人本地运行为主；给群聊授权前，请确认 workspace 权限和 allow list。

常见问题

这是飞书、Lark 或 OpenAI 官方项目吗？
不是。这是一个独立的 Feishu/Lark + OpenAI Codex connector。

同时支持飞书和 Lark 吗？
支持。创建 profile 时使用 --tenant feishu 或 --tenant lark。

必须使用 OpenAI API Key 吗？
API-key 模式最适合稳定远程运行。也可以按配置使用本机 Codex 状态或继承用户认证。

本地文件存在哪里？
默认状态目录是 ~/.feishu-codex。

文档

• Architecture
• Functional Specification
• Feature Parity Specification
• Command Completion Specification
• Feishu/Lark Permissions

License

MIT