Codex

Operational Steps

1. 确认输入参数完整
2. 执行核心操作（参考本目录下的 scripts/ 或 references/）
3. 验证输出符合契约
4. 保存结果并报告

IO_CONTRACT

• input: request: str, context: dict — 用户请求描述、上下文信息
• output: result: dict — 技能执行结果（结构因技能而异）

对应原则：P2（机械原子暴露输入输出规范）

Codex CLI — 主力编码代理

⚡ Codex CLI 是 Synthos 的主力编码代理。所有编码任务优先走 Codex。

When to use

• Building features (⚡ 默认选择)
• Refactoring
• PR reviews
• Batch issue fixing
• 复杂编码任务（多文件、多步骤、需自主规划）

OpenCode 仅用于极轻量的一键脚本，复杂任务一律走 Codex。

Prerequisites

• Codex installed: npm install -g @openai/codex
• Must run inside a git repository — Codex refuses to run outside one
• Use pty=true in terminal calls for interactive mode
• Config at ~/.codex/config.toml

⚠️ tmux Interaction — 指令与回车必须分开发送

CRITICAL: 通过 tmux 与 Codex 交互时，send-keys 的指令和 Enter 必须是两条独立的调用。

# ✅ 正确：分两次发送
tmux send-keys -t codex-session "检查代码质量并优化"
sleep 0.5
tmux send-keys -t codex-session Enter

# ❌ 错误：合在一起发送
tmux send-keys -t codex-session "检查代码质量并优化" Enter
# Codex 不会收到回车触发，指令会卡住不响应

根因：Codex CLI 的 TUI 需要 Enter 键作为独立的 keypress 来触发提交。send-keys 在同一调用中一起发送时，Enter 被当作普通字符而非 key event，Codex 不会处理。

调试信号：如果 tmux capture-pane 看到 › 提示符后指令显示但无响应，说明 Enter 没发出去。重新发送 Enter 即可恢复。

Multi-Node Profile Architecture

Codex CLI 通过 -p <profile> 支持多节点并行：

Profile 文件位于 ~/.codex/<name>.config.toml。每个文件独立配置 model、model_provider、base_url、wire_api。

使用方式

# 主力节点（默认）
codex exec "task description" --yolo

# 备用节点并行
codex -p hermes exec "task description" --yolo
codex -p amax exec "task description" --yolo
codex -p fallback exec "task description" --yolo

并行任务策略

不同任务分配到不同 profile 节点，实现多节点并行负载：

# Task 1 → 主力节点
codex exec "task A" --yolo

# Task 2 → hermes 节点（后台）
codex -p hermes exec "task B" --yolo &

# Task 3 → amax 节点（后台）
codex -p amax exec "task C" --yolo &

# 等待全部完成
wait

Key Flags

One-Shot Tasks (interactive PTY mode)

# 主力节点（默认）
terminal(command="codex exec 'Add dark mode toggle' --yolo", workdir="~/project", pty=true)

# 备用节点并行
terminal(command="codex -p hermes exec 'Refactor auth' --yolo", workdir="~/project", background=true, pty=true)
terminal(command="codex -p amax exec 'Fix login' --yolo", workdir="~/project", background=true, pty=true)

# Monitor
process(action="poll", session_id="<id>")
process(action="log", session_id="<id>")

For scratch work (Codex needs a git repo):

terminal(command="cd $(mktemp -d) && git init && codex exec 'Build snake game' --yolo", pty=true)

Background Mode (Long Tasks)

terminal(command="codex exec --full-auto 'Refactor auth' --yolo", workdir="~/project", background=true, pty=true)

# 备用节点并行
terminal(command="codex -p amax exec --yolo 'Fix issue #42'", workdir="~/project", background=true, pty=true)

# Monitor progress
process(action="poll", session_id="<id>")
process(action="log", session_id="<id>")
process(action="wait", session_id="<id>", timeout=300)

注意： 长任务或批量任务优先使用 --yolo 模式 + background=true，并分配到不同 profile 实现多节点并行。

PR Reviews

terminal(command="REVIEW=$(mktemp -d) && git clone https://github.com/user/repo.git $REVIEW && cd $REVIEW && gh pr checkout 42 && codex review --base origin/main", pty=true)

Batch PR Reviews with Parallel Worktrees

# Create worktrees
terminal(command="git worktree add -b fix/issue-78 /tmp/issue-78 main", workdir="~/project")
terminal(command="git worktree add -b fix/issue-99 /tmp/issue-99 main", workdir="~/project")

# Launch Codex in each (parallel, different profiles)
terminal(command="codex --yolo exec 'Fix issue #78: <description>. Commit when done.'", workdir="/tmp/issue-78", background=true, pty=true)
terminal(command="codex -p hermes --yolo exec 'Fix issue #99: <description>. Commit when done.'", workdir="/tmp/issue-99", background=true, pty=true)

# Monitor
process(action="list")

# After completion, push and create PRs
terminal(command="cd /tmp/issue-78 && git push -u origin fix/issue-78", pty=true)
terminal(command="cd /tmp/issue-99 && git push -u origin fix/issue-99", pty=true)

# Cleanup
terminal(command="git worktree remove /tmp/issue-78", workdir="~/project")

Cron Integration — Script Pattern

Codex exec works in no-agent cron scripts when prompt is passed as CLI argument (no PTY needed):

#!/bin/bash
# my-cron-task.sh
set -euo pipefail
cd /path/to/project

# Use a specific profile, no PTY needed
codex -p hermes exec "## Task description\n\nSteps:\n1. ...\n2. ...\n\nOutput requirements:\n- ...\n" --yolo 2>&1

验证： 运行 bash script.sh 而非 pty=true。Codex 在无 PTY 环境下正常执行，输出到 stdout。

Cron 迁移清单

将 cron agent 任务迁移到 Codex 脚本的步骤：

1. 将 agent 的 prompt 内容提取为 shell 脚本中的 codex exec 参数
2. 设置 script: <filename> 在 cron job update
3. 脚本用 #!/bin/bash + set -euo pipefail 开头
4. 用 cd 进入正确的工作目录
5. 选择合适 profile（hermes 用于代码任务，amax 用于进化相关）

• Cron 集成 — 脚本模式通过 bash script.sh 执行，codex exec prompt 作为命令行参数传递，完全兼容
• 多模型多节点 — 通过 -p profile 切换不同 vLLM 节点
• 无 PTY 运行 — codex exec 在 cron/脚本环境中无需 PTY

Cron 脚本模板（内联参考）

#!/bin/bash
# 复制此模板到 ~/.hermes/scripts/<task>.sh
set -euo pipefail
WORKDIR="/media/yakeworld/sda2/Synthos"
PROFILE="-p hermes"
cd "$WORKDIR"
codex $PROFILE exec "
## [任务名称]

[任务描述]

### 执行步骤
1. [步骤1]
2. [步骤2]

### 输出要求
- [输出格式]
- [输出位置]

## 参考文件

- `ref/codexec-npm-removal.md` — npm 卸载旧版 Codex CLI
- `ref/opencode-as-codex-fallback.md` — OpenCode 作为 Codex 降级
- `ref/codex-vllm-404-troubleshooting.md` — vLLM 404 排查
- `ref/codex-process-diagnosis-2026-06-21.md` — 进程诊断
- `references/codex-tmux-troubleshooting.md` — tmux 交互、多节点路由、故障排查
- 只输出关键结果
" --yolo 2>&1

模型兼容性警告

Codex CLI 仅支持 OpenAI Responses API (wire_api = "responses")。 不兼容 Chat Completions API 的供应商（DeepSeek、OpenRouter 等）。

详情见 references/deepseek-compatibility.md。

Pitfalls

-

-

Verification

-

-

1. Codex needs a git repo — 在非 git 目录运行会直接失败。用 cd $(mktemp -d) && git init 创建临时仓库
2. PTY required for interactive mode — codex（不带 subcommand）需要 PTY，但 codex exec 不需要
3. Model metadata warning — qwen3.6-35b-nvfp4 可能报 metadata 缺失警告，但不影响运行
4. Cron scripts run without PTY — cron 的 no_agent 模式通过 bash script.sh 执行，Codex exec 需要 prompt 作为 CLI 参数（非 stdin）
5. Profile files are independent — 每个 profile 文件完全独立，不要期望 profile 之间共享配置
6. --yolo has NO sandbox — 完全访问文件系统，确保只用于可信任务
7. Multiple profiles = multiple processes — 不同 profile 是独立进程，不共享 session/memory
8. Shell quoting in cron scripts — Cron 脚本中 prompt 用双引号包裹，内部换行直接写。过长 prompt 注意 shell 命令长度限制（建议 < 4096 字符）
9. DeepSeek 不兼容 Codex — Codex wire_api 只接受 responses（OpenAI Responses API 格式），DeepSeek 仅提供 OpenAI 兼容的 chat/completions 端点。尝试将 DeepSeek 接入 Codex 会失败（401 + /v1/responses 端点不存在）。解决方案：DeepSeek 通过 cron agent provider 配置或 OpenCode 使用，不要尝试通过 Codex CLI 调用。

验证清单 · VERIFICATION

• 运行目录是 git 仓库（非 git 目录会直接拒绝）
• tmux 交互时指令与 Enter 分两次独立 send-keys 发送
• 并行任务已分配到不同 -p <profile> 节点
• --yolo（无沙箱）仅用于可信任务/隔离环境
• cron 脚本用 codex exec + prompt 作 CLI 参数（无 PTY）
• 模型供应商仅 OpenAI Responses API（wire_api = "responses"）

约束规则 · RULES

1. 输入约束: 参数类型、范围、格式必须校验
2. 输出约束: 返回值结构、编码、命名必须一致
3. 异常约束: 错误信息必须包含上下文和恢复建议
4. 安全约束: 不执行未验证的任意代码，不暴露内部状态

Golden 集合 · GOLDEN SET

• Golden Input: 标准输入样本（覆盖正常路径）
• Golden Output: 预期输出（精确匹配或格式校验）
• Golden Error: 预期错误信息（覆盖失败路径）

Golden 集合是测试的单一真理来源。所有改进必须通过 golden 测试。

违反规则的操作视为不安全，必须拒绝或隔离。

每项验证必须可执行、可记录、可复现。验证失败时记录原因和修复。

Codex

Genes (策略基因)

紧凑策略表示。条件→策略。需要深度时参考完整文档。

• [CODE-001] 复杂编码任务（多文件/多步骤） → 优先使用 Codex CLI 而非 OpenCode，仅极轻量脚本使用 OpenCode
• [CODE-002] 通过 tmux 交互发送指令 → 指令文本与 Enter 键必须分两次独立调用 send-keys 发送，避免指令卡住
• [CODE-003] 需要并行处理多个独立任务 → 利用 -p <profile> 切换不同节点配置，将任务分配到不同后台进程以实现多节点负载
• [CODE-004] 在非 Git 目录执行 Codex → 必须通过 git init 创建临时仓库或进入现有仓库，否则 Codex 拒绝运行
• [CODE-005] 在 Cron 或无 PTY 脚本环境中执行 → 使用 codex exec 并将 Prompt 作为 CLI 参数传递，无需 PTY 支持
• [CODE-006] 执行高风险或批量自动化任务 → 使用 --yolo 模式以跳过沙箱和审批，但需确保任务可信且环境隔离
• [CODE-007] 配置模型供应商 → 仅支持 OpenAI Responses API (wire_api = "responses")，避免使用仅支持 Chat Completions 的供应商

示例 · EXAMPLES

Example 1 — 主力节点一次性编码任务

• 输入: 任务 "Add dark mode toggle"，工作目录 ~/project（git 仓库）
• 操作: terminal(command="codex exec 'Add dark mode toggle' --yolo", workdir="~/project", pty=true)
• 输出: Codex 完成修改后退出，stdout 含变更摘要
• 验证: git -C ~/project status --porcelain 显示预期文件变更；命令正常退出（无 git 仓库会直接失败）

Example 2 — 多节点并行批量修 Issue

• 输入: 两个独立 issue #78、#99
• 操作: git worktree add 建两个工作树，分别 codex --yolo exec（主力节点）与 codex -p hermes --yolo exec（hermes 节点）后台并行执行，process(action="list") 监控
• 输出: 两个 worktree 各自完成修改并提交到 fix/issue-78、fix/issue-99 分支
• 验证: 两分支各有新 commit；git worktree remove 清理；推送后可建 PR

Example 3 — tmux 交互发送指令

• 输入: 已存在 codex-session 交互会话，需发送 "检查代码质量并优化"
• 操作: tmux send-keys -t codex-session "检查代码质量并优化" → sleep 0.5 → tmux send-keys -t codex-session Enter（两条独立调用）
• 输出: Codex TUI 收到指令并提交，开始执行
• 验证: tmux capture-pane -t codex-session 显示指令后 Codex 有响应（若 › 后指令卡住说明 Enter 未独立发送，重发 Enter 恢复）