xworkmate-app/docs/codex-integration/tasks.md

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 仍是 future placeholder，不应宣传为已完成。

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

1. 内置 Code Agent（built-in）：
   • 已提供运行时模式接入位与桥接流程编排（AI Gateway / OpenClaw 协同元数据）
   • 当前仍属于 experimental，受 Rust FFI TODO 约束
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 具备真实可用能力后，再开放 built-in 交付承诺

前置条件：

• rust/src/lib.rs 的消息发送 / 轮询 TODO 完成
• rust/src/runtime.rs 的进程启动 / 停止 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 非托管内容