# Codex CLI 集成任务路线图

## 当前结论

XWorkmate 当前唯一可交付的 Codex 集成路径是 **external CLI**：

- 通过 `CodexRuntime.startStdio()` 拉起外部 `codex app-server`
- 通过 `CodexConfigBridge` 把 AI Gateway 写入 `~/.codex/config.toml`
- 通过 `CodeAgentNodeOrchestrator` 把 XWorkmate 固定为 `app-mediated cooperative node`
- 通过 `RuntimeCoordinator` 保留多外部 Code Agent CLI 的统一 registry surface

Rust FFI / built-in Codex 已退役，不应再作为当前实现宣传。

## 能力补全清单（按需求项）

1. 内置 Code Agent（built-in）：
   - 已提供运行时模式接入位与桥接流程编排（AI Gateway / OpenClaw 协同元数据）
   - 当前仍属于 experimental，且 Rust FFI 路径已退役
2. 外部依赖 Codex CLI：
   - 已作为稳定主路径接入
   - 保持与内置模式相同的桥接能力和模式切换语义
   - 写入 `~/.codex/config.toml` 时不覆盖原有非托管配置
3. 其他外部 Code Agent CLI：
   - 已通过 `ExternalCodeAgentProvider` 保留统一注册契约
   - capability metadata 与调度扩展点在 runtime 层收口

## 交付顺序

### Phase 1: 外部 Codex CLI 协同模式

目标：

1. 用户显式启用 bridge
2. XWorkmate 先启动外部 Codex CLI 进程
3. 若 OpenClaw Gateway 已连接，则将 XWorkmate 注册为协同 code-agent bridge
4. AI Gateway 继续作为同一套模型桥接入口
5. App 发送到 Gateway 的 chat 请求带上 node / provider / bridge dispatch metadata

交付范围：

- `SettingsSnapshot.codeAgentRuntimeMode`
- `SettingsSnapshot.codexCliPath`
- Codex bridge control panel
- Gateway `agent/register` 协同注册
- `chat.send` 的 app-mediated node metadata
- 本地降级：Gateway 不可用时，外部 Codex 仍可运行
- `CodexConfigBridge` 对 `~/.codex/config.toml` 采用非破坏性写入（仅更新 XWorkmate 托管块，保留原有配置）

非目标：

- 不自动开机拉起 Codex
- 不新增 Gateway 后端 API
- 不做 provider chooser

### Phase 2: 其他外部 Code Agent CLI 预留

目标：

- 保留统一注册、能力 metadata 和调度扩展点
- Codex 自身也通过同一 registry surface 暴露 provider 身份

交付范围：

- `ExternalCodeAgentProvider` 继续作为唯一 provider contract
- provider metadata / capability discovery 继续收口在 runtime 层
- runtime 层提供统一发现/调度入口（`discoverExternalCodeAgents` / `selectExternalCodeAgent`）
- App 侧通过 `CodeAgentNodeOrchestrator` 统一生成 Gateway dispatch envelope
- 文档明确：当前 active provider 只有 `codex`

非目标：

- 不做第二个 provider 之前的通用 UI
- 不做复杂调度策略

### Phase 3: 内置 Codex / Rust FFI（历史）

目标：

- 这一路径仅作历史记录保留，不再推进为当前交付面

前置条件：

- 历史文档中的 Rust FFI TODO 不再作为当前实现目标
- 能复用与 external CLI 相同的 coordinator / registry 契约

## truth 收口

- Scheduled Tasks 当前只消费 `cron.list`，是只读展示
- Memory 当前只消费 `memory/sync`，是 sync-only
- `.env` 仍是 prefill-only，不是运行时真值源
- 远程网关仍必须保持 TLS 显式配置
- OpenClaw Gateway 只看到 `XWorkmate App node`，不会直接连接外部 CLI

## 本轮验收

- External Codex bridge 可显式启用/停用
- 已配置 AI Gateway 时可导出/写入 Codex bridge 配置
- OpenClaw 已连接时，XWorkmate 会执行一次 `agent/register`
- Gateway 不可用时，Bridge 退化为本地运行，不中断外部 Codex 进程
- 外部 Codex 集成不会覆盖用户已有 `~/.codex/config.toml` 非托管内容