# Codex

> codex

- Skill: `yakeworld/codex` (Agent Skill, multi-file: 13 files)
- Install (CLI): `npx skillmds@latest add yakeworld/codex`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yakeworld/codex/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: yakeworld (https://skillmd.com/u/yakeworld)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/yakeworld/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 必须是**两条独立的调用**。

```bash
# ✅ 正确：分两次发送
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 | 节点 | 模型 | 用途 |
|---------|------|------|------|
| 默认(无-p) | 100.82.27.51:8000 | qwen3.6-35b-nvfp4 | 主力节点 |
| -p amax | 100.82.27.51:8000 | Qwen3.6-35B-A3B-GPTQ-Int4 | AMAX 备用 |
| -p hermes | 100.125.10.93:8000 | qwen3.6-35b-nvfp4 | Hermes 节点 |
| -p fallback | 100.100.252.99:8000 | qwen3.6-35b-nvfp4 | 第三备用 |

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

### 使用方式

```bash
# 主力节点（默认）
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 节点，实现多节点并行负载：

```bash
# 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

| Flag | Effect |
|------|--------|
| `exec "prompt"` | One-shot execution, exits when done |
| `--full-auto` | Sandboxed but auto-approves file changes in workspace |
| `--yolo` | No sandbox, no approvals (fastest, most dangerous) |
| `-p <profile>` | Load specific config profile |
| `-c key=value` | Override a config value (CLI-only) |
| `--strict-config` | Error on unrecognized config fields |

## One-Shot Tasks (interactive PTY mode)

```bash
# 主力节点（默认）
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):
```bash
terminal(command="cd $(mktemp -d) && git init && codex exec 'Build snake game' --yolo", pty=true)
```

## Background Mode (Long Tasks)

```bash
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

```bash
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

```bash
# 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):

```bash
#!/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 脚本模板（内联参考）

```bash
#!/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
9. **Shell quoting in cron scripts** — Cron 脚本中 prompt 用双引号包裹，内部换行直接写。过长 prompt 注意 shell 命令长度限制（建议 < 4096 字符）
10. **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 恢复）