# Codex Server 协议与 Boss 执行进度卡接入记录

更新时间：`2026-05-08`

## 1. Codex 最新开放协议结论

当前可作为 Boss 稳定集成入口的是 Codex CLI MCP server：

- 启动命令：`codex mcp-server`
- Inspector 调试：`npx @modelcontextprotocol/inspector codex mcp-server`
- 官方 MCP 工具：
  - `codex`：启动一个 Codex 会话，入参包含 `prompt / approval-policy / base-instructions / config / cwd / include-plan-tool / model / profile / sandbox`
  - `codex-reply`：继续一个 Codex 会话，入参包含 `prompt / threadId`，`conversationId` 只是兼容别名
- 线程续写应使用 `tools/call` 返回里的 `structuredContent.threadId`
- 现代 MCP 客户端主要读取 `structuredContent`；`content` 只作为旧客户端兼容输出

本机当前检测结果：

- 本机 `codex --version`：`codex-cli 0.114.0`
- npm 最新稳定包：`@openai/codex 0.129.0`
- npm alpha：`0.130.0-alpha.5`
- 本机 `0.114.0` 已支持 `codex mcp-server --help`，但落后于当前 `0.129.0` 的 app-server / protocol 拆分、ThreadStore、MCP turn metadata、plugin sharing 等新能力

## 2. Boss 当前采用的接入策略

短期不直接依赖 Codex Desktop 私有 UI 结构，也不把 Codex CLI 原始 stderr/stdout 泄露给 APP。

当前实现采用 Boss 自有结构化消息：

- 新消息类型：`execution_progress`
- 服务端字段：`Message.executionProgress`
- 触发范围：
  - 普通单线程对话：用户在 Boss APP 指定线程里发消息
  - 主 Agent 托管线程：托管消息实际派到目标 Codex 线程时
  - 群聊确认下发：后续目标线程执行单会复用同一张卡
- 生命周期：
  - 任务入队：创建进度卡
  - local-agent 认领：更新为 running
  - local-agent 完成：更新同一张卡为 completed / failed

APP 展示结构对齐截图：

- `进度`：步骤列表，显示已完成 / 进行中 / 待处理 / 失败
- `分支详情`：变更行、Git 操作、GitHub CLI 可用状态
- `生成结果`：从执行结果里提取文件、图片、APK、文档等产物名
- `后台智能体`：预留 OMX / Hermes / explorer 等多智能体来源展示

## 3. 安全边界

进度卡只允许展示用户可见摘要：

- 不展示系统提示词
- 不展示完整执行 prompt
- 不展示设备 token、账号密钥、内部工作目录调度说明
- 不展示 Codex CLI 启动 envelope、sandbox、approval、session id、MCP 启动日志
- `RemoteRuntimeAdapter` 仍会先拦截只读环境提示和 Codex envelope 泄漏，再进入消息账本

## 4. 历史引用项目最新状态

本次按 GitHub 最新元数据核对过的项目：

| 项目 | 最新状态 | 对 Boss 的可借鉴点 |
| --- | --- | --- |
| `openai/codex` | `rust-v0.129.0`，2026-05-07 发布；main 在 2026-05-08 仍有提交 | 后续优先补 `codex mcp-server` 长驻适配器；参考 ThreadStore、turn metadata、app-server protocol v3 方向，不再只靠 `codex exec resume` |
| `Yeachan-Heo/oh-my-codex` | `v0.16.2`，2026-05-08 发布 | `$ultragoal` 聚合目标、commit-shared wiki / compaction、state/session isolation、Codex native hook setup 值得同步到 Boss 的任务目标与进度卡 |
| `ultraworkers/claw-code` | main 最新提交 2026-05-06；原 `instructkr/claw-code` 已指向该仓库；暂无 GitHub release | 继续保留抽象后端，不写死版本；重点观察 skills help routing、push_output_block、Rust harness 更新 |
| `NousResearch/hermes-agent` | `v2026.5.7 / v0.13.0`，Tenacity Release | Durable Multi-Agent Kanban、heartbeat / reclaim / zombie detection、goal lock、checkpoints v2 可作为 Boss 主 Agent 长任务可靠性升级参考 |
| `iflytek/skillhub` | `v0.2.6`，2026-04-29 发布；main 2026-05-08 仍更新 | Skill 订阅通知、OIDC 登录、S3 IAM、namespace CSV 批量成员导入，适合 Boss 企业 Skill 治理后台后续吸收 |
| `openclaw/openclaw` | `v2026.5.7`，2026-05-07 发布；main 2026-05-08 仍更新 | Telegram allowlist、polling watchdog、deliverySucceeded、Codex approval 去重、provider/model callback 修复，可用于 Boss Telegram 网关和远程审批 |
| `goldmar/openclaw-code-agent` | `v4.2.3`，2026-05-08 发布 | OpenClaw + Codex coding agent 的 session lifecycle、wake routing、worktree/PR policy，可作为 Boss “聊天控制桌面 Codex 开发”的旁路参考 |

## 5. 下一步建议

第一阶段已经落地：

- Boss 消息账本新增 `execution_progress`
- Android 原生聊天页新增结构化进度卡
- local-agent 完成回写会补 Git diff、GitHub CLI 状态和产物名

后续建议按两步继续：

1. 新增 `CodexMcpBackendAdapter`：让 `codex mcp-server` 成为 `ExecutionBackend` 的可选实现，先 feature flag 默认关闭，保留 `codex exec resume` 作为生产主链。
2. 增加任务级 live progress API：`POST /api/v1/master-agent/tasks/[taskId]/progress`，让本地 agent 在执行中也能实时刷新进度卡，而不是只在 claim / complete 两个节点更新。