把 OpenAI Codex 的能力装进飞书。在手机端 @ 机器人，远程驱动本地 codex CLI 完成代码编写、文件改动、命令执行；流式进度、工具审批、多会话并发一应俱全。
一个常驻在你电脑上的 Windows 单 exe：通过飞书开放平台的 ws 长连接接收你在手机或 PC 端发的消息，转交给本机的 codex CLI 执行，再把模型推理、命令执行、文件改动等过程实时回传成飞书卡片。无需公网 IP、无需回调 URL，下载即用。
- 零依赖单文件：Go 编译的单个 exe，无 CGO、无运行时依赖，解压双击即跑
- 手机即终端：出差、通勤、躺床上，用手机 @ 机器人就能驱动家里/公司工作站写代码
- 第三方 API 友好：专为用不了 OpenAI 官方账号、走第三方 API 中转的开发者复刻"手机控制电脑"体验
本项目的诞生与稳定运行，离不开 opus5 API 中转站 的全力支持。
OpenAI 官方的 "Codex 桌面 App" 仅向官方付费账号开放，国内大多数开发者使用第三方 API 中转，因此享受不到"手机控制电脑写代码"的体验。opus5 的存在让 codex CLI 在国内得以真正可用，本项目正是为这部分用户复刻官方体验而生。
| 维度 | 说明 |
|---|---|
| 🌐 国内直连 | 不需要任何代理或魔法，直接 HTTPS 访问 |
| 🎯 codex 原生适配 | 支持 wire_api = "responses"，零改动接入 codex CLI |
| 🤖 全系模型 | OpenAI 全家桶（GPT-4o / GPT-5 / o1 / o3）、Anthropic Claude（Opus / Sonnet / Haiku）、Gemini、国产模型 |
| 💰 按量计费 | 价格友好，无套餐绑定，用多少付多少 |
| ⚡ 稳定低延迟 | 国内多节点，对长上下文 / 流式响应优化良好 |
编辑 ~/.codex/config.toml：
model = "gpt-5.5"
model_provider = "opus5"
[model_providers.opus5]
name = "Opus5"
base_url = "https://api.opus5.xyz/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"设置环境变量 OPENAI_API_KEY 为你在 opus5 控制台申请的 key 即可。
OpenAI 在 2025 年底为官方 Codex 桌面 App 引入了"手机端控制电脑端 codex"的能力 —— 用户在 ChatGPT 移动端发送 prompt，桌面端的 codex 会接管本机文件、命令、工具调用，并把流式进度回传到手机端。
但该能力强绑定 OpenAI 官方账号体系，第三方 API 用户无法使用。本项目以 codex CLI 0.125+ 暴露的 app-server JSON-RPC 协议为底层，以飞书开放平台 ws 长连接为前端通道，复刻这一体验，目标用户为：
- 已有 codex CLI + 第三方 API 工作流，希望加入移动端控制层的开发者
- 团队基于飞书办公，需要把 AI 编程助手带入协作场景的研发组
- 出差/远程办公场景下，希望以手机驱动家中或办公室工作站完成开发任务的工程师
┌─────────────────┐ 长连接 ┌──────────────────┐
│ 手机/PC 飞书 ───┼───────── ws ───────────▶│ 飞书开放平台 │
└─────────────────┘ └────────┬─────────┘
│
▼
┌──────────────────────┐
│ bridge.exe (本机常驻) │
│ - 飞书事件路由 │
│ - 会话/线程映射 │
│ - CardKit 流式渲染 │
│ - 审批回包 │
└──────┬───────────────┘
│ stdio JSON-RPC
▼
┌──────────────────────┐
│ codex app-server │
│ (官方协议) │
└──────┬───────────────┘
│ HTTPS
▼
┌──────────────────────┐
│ opus5 / 第三方 API │
└──────────────────────┘
技术选型：
- Go 1.25 +
gioui.org：单 exe、零 CGO、原生 Windows GUI oapi-sdk-go/v3：飞书官方 SDK，长连接模式无需公网 IP / 回调 URL- codex
app-server：官方暴露的 stdio JSON-RPC，协议字段对照仓库research/ts/（由codex app-server generate-ts --experimental生成） - CardKit Schema 2.0：流式卡片元素增量更新，默认 200ms 合并一次补丁（~5 次/秒，稳稳压在飞书 5 QPS / 消息上限内），并用 1.5s 心跳防止飞书 5s 静默自动关闭流式；单卡接近 10 分钟硬上限前自动旋转到新卡续写
- Windows DPAPI：App Secret / API Key 落盘前用当前用户密钥加密，配置文件只保留引用
| 能力 | 说明 |
|---|---|
| 文本指令 | @ 机器人发任意 prompt，即开始一个 codex turn |
| 流式进度 | 模型 reasoning、文件读写、shell 命令实时通过 CardKit 卡片逐字回传，无需等整段答案 |
| 执行计划 | codex 更新任务计划时，飞书侧同步渲染计划卡（步骤状态 + 完成进度 N/M） |
| 工具审批 | 危险命令 / 文件改动出现时，飞书侧弹"允许 / 本会话内允许 / 拒绝"按钮，点击即回包给 codex（默认 30 分钟超时） |
| 最终结果 | turn 结束后另发一张结果卡，把流式过程与最终答案分离，便于回看 |
| 图片输入 | 直接发图，bridge 自动下载并以 localImage 形式喂给 codex |
| 多会话并发 | 群聊"话题模式"下每个话题一个独立 codex thread，互不干扰 |
| 会话恢复 | /sessions 可列出本聊天历史会话和 Codex 桌面端历史，一键继续之前的上下文 |
| 运行中插话 | /steer 在当前 turn 不中断的前提下追加指令，纠偏 / 补充需求 |
| 中断 | /stop 立即取消当前 turn |
| 命令 | 作用 |
|---|---|
/new [cwd] |
群聊根：开新话题新建会话；话题内：替换当前会话 |
/sessions |
列出本聊天会话 + Codex 桌面历史，附"继续/结束"按钮 |
/end |
结束当前会话（仍可在 /sessions 里恢复） |
/cd <绝对路径> |
切换工作目录（重启会话） |
/model [id] |
列出可用模型；带 id 时切换模型（重启会话） |
/approval <untrusted|on-failure|on-request|never> |
切换审批模式 |
/sandbox <read-only|workspace-write|danger-full-access> |
切换沙箱级别 |
/steer <补充指令> |
当前 turn 运行中追加指令（插话，不打断） |
/compact |
压缩当前会话上下文 |
/diff |
查看相对远端基线的 Git 改动 |
/review |
对未提交改动发起代码审查 |
/stop |
中断当前 turn |
/status |
查看当前会话 cwd / 模型 / 策略 |
/diag |
查看轻量诊断信息 |
/help |
帮助 |
命令大致分三类：会话类（
/new/sessions/end/steer/compact/stop）管理对话生命周期；配置类（/cd/model/approval/sandbox）调整当前会话的运行参数，执行时会重启会话，且若上一条还在响应会被拦下提示先/stop；工具类（/diff/review/status/diag）查看状态与代码改动。发普通文本则直接作为 prompt 开始新一轮。
原生 Windows 界面，自绘标题栏，无浏览器内核。主要面板：
- 概览：连接状态、配置摘要、快速操作；可一键复制脱敏诊断摘要发给维护人员
- 引导：4 步首次启动向导 —— ① 飞书应用（App ID/Secret）→ ② Codex 配置（可执行路径、默认工作目录）→ ③ 安全策略（审批 + 沙箱）→ ④ 连接测试
- 配置：完整配置编辑，高风险审批 / 沙箱组合显著标红，避免误选危险默认值
- 日志：实时滚动输出，支持"只看问题"过滤，复制时自动脱敏常见密钥
- 关于 / 设置：版本信息与界面偏好
内置飞书自建应用全量开通文档：8 步图文指引（建应用 → 配权限 → 订阅事件 → 发版 → 加入会话），权限清单（含 cardkit:card、im:resource 等 8 项）与事件订阅清单（im.message.receive_v1 + card.action.trigger）全部支持一键复制，并提供「打开飞书开放平台」「复制完整开通清单」快捷按钮。
连接测试（5 项自检）：① codex 可执行文件可用 → ② initialize 握手（10s）→ ③ 端到端跑通一个 turn（最长 90s）→ ④ 飞书凭证有效 → ⑤ 机器人能力就绪；任一失败都会给出对应修复建议，并跳转到引导页相应步骤。
托盘最小化：服务运行中点关闭默认走最小化，避免误关导致服务中断；需退出请先点「停止服务」。
- 同样的
runtime.Service内核，纯命令行启动 - 适合 systemd / NSSM / 任务计划自动启动场景
- 支持
-config指定配置文件路径
bridge 用 routeKey 把飞书侧的聊天/话题映射到一个独立的 codex thread：
- 主会话：聊天根（非话题）里的对话，
routeKey = chatID - 话题会话：飞书话题内的对话，
routeKey = chatID:threadID，每个话题对应一个并行的 codex thread
/new 的行为取决于发起位置：在群聊根发 /new，bridge 用 reply_in_thread 回卡片，飞书会自动新建一个话题，话题里就是一个全新的独立会话，可与主会话并行跑；在已有话题里发 /new 则替换该话题当前会话。单聊（P2P）没有话题概念，/new 等价于重置主会话。
串行护栏：同一会话里上一条还没回完时再发消息，会被回"当前会话还在响应，请等完成或 /stop 后再发"——避免同一 thread 上并发起 turn。要并行就开新话题。
持久化：会话映射写入 state.json（默认 bridge-state.json，原子写入），记录每个会话的 cwd / 审批 / 沙箱 / 模型 / 标题等。会话标题自动取首条用户消息（截 40 字）。重启 bridge 后仍可在 /sessions 里看到历史会话并继续，也能列出 codex 桌面端的历史会话一并恢复。
- Windows 10 / 11 x64
- 已安装 codex CLI 0.125+（
codex --version可执行） ~/.codex/config.toml已正确配置[model_providers.<name>]- 飞书企业账号 + 自建应用开发权限
- 下载 —— Releases 页面下载
feishu-codex-bridge-windows-amd64-*.zip，解压到任意目录 - 运行 —— 双击
bridge-gui.exe - 配置 —— 按 GUI 引导填写 App ID / App Secret / Codex 路径，点"启动"
- 登录 https://open.feishu.cn/app → 创建企业自建应用
- 「凭证与基础信息」获取 App ID / App Secret
- 「应用能力」开启「机器人」+「消息卡片」（含 CardKit / 卡片 2.0）
- 「权限管理」勾选：
im:message、im:message:send_as_bot、im:message.group_at_msg、im:message.p2p_msg、im:resource、cardkit:card（读/写权限分别申请） - 「事件与回调」切到 长连接 标签，订阅
im.message.receive_v1与card.action.trigger - 「版本管理与发布」创建版本 → 提交审核
- 把机器人加入目标群（建议开启「话题模式」以支持多会话并发）
长连接模式无需配置回调 URL、Encrypt Key、Verification Token；GUI 引导页提供「打开飞书开放平台」「复制完整开通清单」一键操作。
GUI 的「保存配置」会生成此文件；想直接手写或用 CLI 运行也可以。完整字段：
[feishu]
app_id = "cli_xxx" # 必填
app_secret_ref = "secret:feishu_app_secret" # 推荐：DPAPI 加密引用，明文用 app_secret
log_level = "info" # debug | info | warn | error
[codex]
binary = "codex" # codex 可执行路径，默认在 PATH 里找
default_cwd = "C:\\work\\myproject" # 必填：默认工作目录，可被 /cd 覆盖
profile = "" # 可选：对应 ~/.codex/config.toml 的 [profiles.xxx]
model = "" # 可选：覆盖默认模型，可被 /model 覆盖
provider = "" # 可选：覆盖 model_provider
[codex.extra_env_ref] # 透传给 codex 子进程的环境变量（加密引用）
OPENAI_API_KEY = "secret:openai_key"
[codex.extra_config] # 等价于 codex -c key=value 覆盖
# "model_reasoning_effort" = "high"
[bridge]
default_approval_policy = "on-request" # untrusted | on-failure | on-request | never
default_sandbox = "workspace-write" # read-only | workspace-write | danger-full-access
state_file = "bridge-state.json"
approval_timeout_minutes = 30 # 审批按钮多久无人点击算超时凡是
*_ref字段都接受secret:<key>形式的引用，真实值经 Windows DPAPI 加密后单独落盘，配置文件本身不含明文。
- 凭证：App Secret / OPENAI_API_KEY 通过 Windows DPAPI 以当前用户密钥加密落盘，配置文件仅保留
secret:xxx形式引用；GUI 复制日志/诊断时自动脱敏 - 审批：默认
on-request审批 +workspace-write沙箱；任何danger-full-access/never组合在 GUI 中显著警告；审批按钮默认 30 分钟无人点击即超时 - 沙箱限制：codex 在 Windows 上无 seccomp / landlock 等内核级隔离能力，
workspace-write实际等价于无沙箱 —— 审批是唯一的有效防线，请谨慎选择默认策略 - 网络：飞书走 ws 长连接（出站），codex 走子进程 stdio，不监听任何端口
- 数据流：用户 prompt → 飞书 → 本机 bridge → codex → 第三方 API；除 API 调用外不上传任何遥测数据
- 飞书 PATCH 卡片限频 5 QPS / 消息；CardKit 元素流式 ~50 QPS / 卡片。bridge 默认 200ms 节流合并增量，并以 1.5s 心跳保活、近 10 分钟时旋转卡片
- codex protocol 不承诺稳定，更换 codex 版本前建议在测试机回归
internal/codex单测 - 一个飞书 App 默认仅允许 1 个长连接，多机部署同 App 会互踢；分发场景请每台机器单建应用
- 多会话并发依赖群「话题模式」；未启用时
/new会退化为替换主会话 - Windows 上 codex 沙箱能力受限，详见上文"安全模型"
机器人不回消息？ 先确认应用已「创建版本 → 提交审核 → 通过」，未发布的应用收不到事件；再确认事件订阅在 长连接 标签下、且 bridge 正在运行（GUI 日志面板会显示长连接状态）。
群里 @ 了没反应？
检查是否已把机器人加入该群，以及是否申请了 im:message.group_at_msg 权限。单聊则需要 im:message.p2p_msg。
/new 没开出新话题，还是在主会话里回？
该群没开「话题模式」。群管理员到群设置里开启后，/new 才会另开话题实现并发；否则 /new 退化为替换主会话。
多台机器想共用一个飞书应用？ 不行。一个飞书 App 默认只允许 1 个长连接，多机部署同 App 会互相挤掉。请为每台机器单独创建飞书应用。
发了配置类命令（/cd、/model 等）报"还在响应"？
这些命令会重启会话，bridge 不允许在 turn 运行中执行，先 /stop 中断当前回应再发。
怎么在后台无窗口运行？
先用 GUI 配好并保存 config.toml，再改用 bridge.exe -config config.toml 配合 NSSM / 任务计划托管，CLI 与 GUI 共用同一内核与配置。
每次 codex 升级后请重新生成类型定义并复核：
codex app-server generate-ts --out research\ts --experimental
codex app-server generate-json-schema --out research\schema --experimental→ 前往 Releases 下载最新的 feishu-codex-bridge-windows-amd64-*.zip，解压双击 bridge-gui.exe 即可。
闭源软件。仅授权个人 / 团队内部使用，禁止反编译、再分发或用于商业产品集成。商业授权请通过 GitHub Issues 联系。