codex-worker 优化与 CPA/YT 模型路由调试复盘

codex-worker 优化与 CPA/YT 模型路由调试复盘

背景

本轮工作源于对 TreeX-X/WorkFlowX 的综合评估。评估结论不是吸收它的 agent/plugin 壳，而是局部吸收其中对 Hermes 有价值的 workflow discipline，尤其是：

• Whole / Local / Unit 任务路由；
• coder 输出不等于 completed；
• 单一写入者原则；
• 结构化 AC 报告；
• subagent/context packet 压缩字段。

这些能力更适合增强本机 codex-worker 的受控执行纪律，而不是把 codex-worker 升级为类似 search-worker 的独立 agent。

关键判断

判断一：codex-worker 不是独立 agent，而是受控 execution lane

search-worker 适合独立化，是因为它承担重型公网 research、多来源证据整合、长耗时和高 token 隔离。codex-worker 当前的核心价值则是：

• task contract 校验；
• prompt 编译；
• allowed/forbidden 文件边界；
• diff / acceptance / branch / receipt 审计；
• ready / blocked 决策回执。

因此本轮收口为：独立 profile / execution lane，不升独立 agent。

判断二：worker 的 ready 不是用户侧完成

本轮明确写入 runbook 和 receipt 语义：

• decision.status=ready 只表示 ready for review；
• 最终 completed 必须由 Hermes 主代理或 reviewer 判定；
• worker receipt 是审查输入，不是完成宣告。

判断三：模型默认值不应硬编码在 runner 内

早期 runner 默认传 --model gpt-5.4，这会在 CPA 模型路由调整后导致 worker 卡死。优化后 runner 逻辑变为：

• 不设 CODEX_WORKER_MODEL 且不传 --model 时，runner 不给 codex exec 加 --model；
• Codex CLI 自己读取 ~/.codex/config.toml；
• 只有显式传 --model 或设置 CODEX_WORKER_MODEL 时才覆盖。

这让 worker 跟随 Codex CLI 当前默认模型，而不是跟随 Hermes WebUI 主模型或写死旧模型名。

实施内容

runner 优化

修改文件：

主要变化：

• 新增 profile-aware 默认值：
• CODEX_WORKER_PROFILE
• CODEX_WORKER_MODEL
• CODEX_WORKER_CODEX_BIN
• CODEX_WORKER_RECEIPT_DIR
• CODEX_WORKER_SANDBOX_MODE
• CODEX_WORKER_CODEX_TIMEOUT
• CODEX_WORKER_ACCEPTANCE_TIMEOUT
• 新增 Codex 执行超时与 acceptance check 超时；
• 新增 evaluator_summary；
• receipt 中新增 execution_profile 与更清晰的 model 记录；
• 默认不再传 --model，显示为 codex-cli-default；
• 保留显式 model override 能力。

shell wrapper 优化

修改文件：

同步 runner 参数说明，补齐：

• --profile-name
• --receipt-dir
• --default-sandbox-mode
• --codex-timeout
• --acceptance-timeout
• --enforce-branch
• --prepare-branch

profile runbook

新增文件：

写入正式定位：

• codex-worker 是受控 coding execution profile；
• 不替代主代理；
• 不拥有 final completion authority；
• 推荐用于 Local / Unit 小型明确边界任务；
• 不建议用于 Whole、复杂跨模块 feature、大范围重构。

模板与 smoke 资产

修改或新增：

task-smoke-readonly.json 用于只读验活；codex_worker_smoke.sh 会自动创建临时 git repo、生成 smoke task、执行 runner 并打印 receipt 摘要。

skill 同步

更新 skill：

同步内容包括：

• CODEX_WORKER_MODEL 改为可选覆盖；
• 留空则跟随 Codex CLI 当前默认 model；
• ready != completed 的完成口径；
• profile / execution lane 定位。

调试过程

第一阶段：框架 smoke 通过，但底层模型失败

最初 smoke 证明 runner 框架可工作：

• task 可读取；
• receipt 可落盘；
• boundary check 可产出；
• acceptance results 可产出；
• evaluator summary 可产出。

但 Codex CLI 经 CPA 调用失败：

这说明 blocker 在 CPA/Codex 模型路由，不在 worker 框架。

第二阶段：去掉 runner 硬编码模型

将 runner 改为默认不传 --model。验证后 receipt 中显示：

但当时 ~/.codex/config.toml 仍然写着：

因此 Codex CLI 仍实际使用 gpt-5.4，继续失败。

第三阶段：错误尝试 custom:yt/gpt-5.5

曾将 ~/.codex/config.toml 改为：

直跑和 worker smoke 都失败：

结论：custom:yt/gpt-5.5 是 Hermes provider 风格推断，不是 CPA /v1/responses 可识别的 Codex model id。

第四阶段：核对本地 CPA 实际模型 alias

读取本机 CPA 配置：

关键配置：

查询 CPA /v1/models，确认实际暴露：

随后分别验证：

• --model 'YT-GPT-5.5(high)'：通过；
• --model 'gpt-5.5'：失败，unknown provider。

第五阶段：写入 Codex CLI 默认配置并复验

最终将：

设置为：

再跑：

验证通过：

最终 receipt：

当前稳定配置

Codex CLI

当前关键项：

codex-worker 调用模型规则

默认：

由 Codex CLI 读取默认模型：

如需临时覆盖：

但常规不建议设置，避免再次写死旧模型。

验证证据

直跑 Codex CLI

使用：

结果：

codex-worker smoke

最终 smoke 结果：

receipt 关键字段：

文件清单

风险与边界

风险一：把 Hermes provider 字符串误当 CPA model id

custom:yt/gpt-5.5 对 Hermes 语义可能成立，但 CPA /v1/responses 并不识别。Codex CLI 走 CPA 时应使用 /v1/models 暴露的 alias，例如：

风险二：裸 gpt-5.5 在当前 CPA responses 路由不可用

虽然 CPA 配置里存在：

但实际 /v1/responses 路由可用的是 alias，不是裸 name。直跑 gpt-5.5 已验证失败。

风险三：worker ready 仍不等于最终完成

即使 smoke ready，也只说明 execution lane 正常。真实任务仍要由主代理或 reviewer 根据 diff、acceptance、业务目标做最终完成判断。

后续建议

1. 后续所有 codex-worker 任务默认不设置 CODEX_WORKER_MODEL，跟随 Codex CLI 默认模型。
2. 如果 CPA 模型调整，先查：

```bash

curl -H "Authorization: Bearer <CPA_KEY>" http://127.0.0.1:8317/v1/models

```

以返回的 id 为准。

1. 每次模型路由变更后跑：

```bash

/home/ht/knowledge/scripts/codex_worker_smoke.sh

```

1. 真实 coding 任务继续按 task contract v0.8：

• 明确 allowed_files；
• 明确 forbidden_files；
• 明确 acceptance_checks；
• 必要时加 diff_policy；
• 不把 Whole 任务直接塞进单个 worker。

完整记录摘要

本轮最终完成了三件事：

1. 将 codex-worker 从受控脚本升级为有 profile/runbook/smoke/evaluator summary 的 execution lane；
2. 将模型选择从 runner 硬编码改为跟随 Codex CLI 默认配置；
3. 通过核对 CPA 实际 alias，将 Codex CLI 默认模型修正为 YT-GPT-5.5(high)，并用 codex-worker smoke 验证全链路 ready。