Codex 联动 Hermes 方案
目标：让 Hermes 总调度 + Codex 执行编码，形成完整的多 Agent 开发流水线。
一、架构总览
用户指令
↓
Manas (总调度 / 任务分解)
├── 简单编码 → 直接 terminal(codex exec)
├── 复杂任务 → delegate_task(acp_command="codex")
├── PR 审查 → codex review
└── Kanban 任务 → Kanban Codex Lane (完整生命周期管理)
二、调用方式
2.1 直接调用
# 终端调用（exec 为非交互模式，不要求 PTY）
terminal(command="codex exec '任务描述'", workdir="~/project", pty=true)
# 后台模式（长时间任务）
terminal(command="codex exec '任务'", workdir="~/project", background=true, pty=true)
# 标准执行；不因性能跳过审批或沙箱
terminal(command="codex exec '任务'", workdir="~/project", pty=true)2.2 子 Agent 派发
# delegate_task 通过 ACP 协议派发到 Codex
- goal: "实现功能 X"
acp_command: "<经核验的 Codex ACP adapter 可执行文件>"
acp_args: [] # 外部 adapter 的参数须另行核验；codex 本身没有这两项旗标2.3 Kanban Codex Lane
适用：Kanban 工单中需要编码的任务，Hermes 全程管控。
流程：
- Hermes 从 Kanban 取任务
- 创建 git worktree 隔离工作区
- 启动 Codex 执行编码
- Hermes 审查 diff + 运行测试
- 通过则合并，拒绝则回滚
- 更新 Kanban 状态
安全规则：
- Codex 不持有 Kanban 写权限
- Codex 提交视为未信任 patch
- 测试必须在 Hermes 侧重新执行
- 涉密/生产任务禁止走此通道
三、前置条件
3.1 环境要求
- Codex CLI 已安装：
npm install -g @openai/codex - Codex 认证已配置：按 Codex 官方登录方式；Hermes 的 provider 认证不自动等同于 Codex CLI 已登录
- 默认在 git 仓库内运行；非仓库任务可用
codex exec --skip-git-repo-check codex exec是非交互执行，不要求pty=true
3.2 配额说明 (OpenCode Go)
- 当前主 provider：opencode-go/deepseek-v4-flash
- 首月 10/月
- 每5小时上限 30，每月 $60
四、协作模式
4.1 单次编码
codex exec '在 src/utils.ts 中实现 debounce 函数，带单元测试'4.2 并行多分支修 Bug
git worktree add -b codex/fix-issue-78 /tmp/issue-78 main
cd /tmp/issue-78
codex exec '修复 issue #78'
git push -u origin codex/fix-issue-78
gh pr create --title 'fix: ...' --body '...'
git worktree remove /tmp/issue-784.3 PR 自动审查
git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'
codex exec '审查 PR #86: git diff origin/main...origin/pr/86'
gh pr comment 86 --body '<审查结果>'4.4 批量任务（Kanban + Codex Lane）
Kanban 工单 → Hermes worker → 分配 Codex Lane → 执行 → 审查 → 合并/回滚 → 更新 Kanban
五、已知风险
5.1 GPT-5.5 质量退化
- 症状：reasoning token 聚类（516/1034/1552 固定阈值），复杂任务错误率上升
- 监测：检查
reasoning_output_tokens是否集中在 516 的倍数 - 应对：配置多 provider fallback，检测到退化自动切 Claude/本地模型
5.2 Codex 沙箱兼容性
- 从 Hermes gateway 调用时，bubblewrap/user-namespace 可能失败
- 应对：使用
--sandbox danger-full-access，并明确接受该模式不提供 OS 文件系统沙箱隔离；普通进程边界不是权限边界
5.3 TypeScript 工具链兼容性（与 Codex SDK 分开）
- 原生 TypeScript 编译器与 TypeScript 6 及以前的编程 API 存在兼容差异；这不影响 Codex 提供独立的官方 TypeScript SDK。
- 依赖编译器 API 的工具应按自身支持版本选择依赖，不能断言所有工具都必须安装某个兼容包。
六、相关资源
| 资源 | 用途 | 位置 |
|---|---|---|
| codex skill | Codex CLI 调用指南 | skills/autonomous-ai-agents/codex |
| kanban-codex-lane skill | Kanban + Codex 集成 | skills/devops/kanban-codex-lane |
| opencode-go-provider | 当前主 provider 配额 | skills/…/references/opencode-go-provider.md |
| codex-keysmith (⭐223) | 安全安装 Codex 指令 | github.com/Jia-Ethan/codex-keysmith |
| CodexPro (⭐284) | ChatGPT → 本地 Agent MCP | github.com/rebel0789/codexpro |
| Codex 橙皮书 (⭐327) | 中文使用指南 | github.com/bozhouDev/codex-orange-book |
七、快速开始
# 1. 确认 Codex 可用
codex --version
# 2. 简单测试
codex exec '输出 "Hello Codex"' --sandbox danger-full-access
# 3. Hermes 中调用（当前环境）
terminal(command="codex exec '你的编码任务'", pty=true)
# 4. 验证结果
git diff关联
- codex-hermes-integration — Codex + Hermes 研究全览
- omnigent-meta-harness — meta-harness 方案
- loop-engineering-patterns — 循环工程
2026-10-09 Codex 审阅说明
已按本机 codex-cli 0.161.0 的 codex --help 与 codex exec --help 修正：exec 不要求 PTY，支持跳过 git 仓库检查，没有示例中的 —acp/—stdio；ACP 联动需外部 adapter。本版本帮助没有 —full-auto/—yolo，例子已回到标准 exec。terminal(…) 为 Hermes 工具调用示意，不是 shell 命令。
OpenAI 提供官方 @openai/codex-sdk TypeScript SDK，不能因 TypeScript 编译器话题断言 Codex 无 JS API。OpenCode Go 额度属于另一个产品，与 Codex 权益/认证分开。reasoning token 计数出现倍数聚类不证明质量退化，须对比实测任务；danger-full-access 不构成权限隔离。所有 push、PR 评论和合并示例只作方案资料，本次没有执行。
核验依据：Codex CLI 官方说明；Codex 官方 TypeScript SDK。
补充核验（2026-10-10）：Microsoft 编译器 API 说明当前描述 TypeScript 6 及以前，并说明 TypeScript 7.1 将有不同 API；据此限定本节的兼容性结论。未核实 typescript-eslint 当前具体版本的安装要求。