codex-orchestrator

Codex Orchestrator

为专注的开发任务启动专用 Codex CLI 子 Agent。每个配置档都会注入自定义的 AGENTS.md 角色设定，用于塑造 Agent 的行为、关注领域和输出格式。

架构

Claude Code (orchestrator)
    ↓ invokes skill
codex-orchestrator scripts
    ↓ spawns via Bash
Codex CLI with AGENTS.md
    ↓ executes
Specialized subagent task

前置条件

确认 Codex CLI 已安装并完成配置：

~/.claude/skills/codex-orchestrator/scripts/codex-status.sh

必需项：

• Codex CLI：npm install -g @openai/codex
• API 密钥：export OPENAI_API_KEY=sk-...

自动更新

此技能会在每次调用时自动检查 Codex CLI 更新，并在需要时进行更新。这可以避免过时的 CLI 版本导致的问题。

手动检查／更新：

# Check version only
~/.claude/skills/codex-orchestrator/scripts/codex-version-check.sh

# Check and auto-update if needed
~/.claude/skills/codex-orchestrator/scripts/codex-version-check.sh --auto-update

可用配置档

配置档	用途	适用场景
reviewer	代码质量、错误、性能	提交前审查、PR 评估
debugger	根因分析、修复	调查错误、追踪问题
architect	系统设计、组件边界	规划变更、评估架构
security	OWASP、漏洞、密钥	安全审计、合规性检查
refactor	代码清理、现代化改造	减少技术债、改进结构
docs	API 文档、README、注释	文档任务
planner	ExecPlan 设计文档	数小时的任务、复杂功能、重大重构
syseng	基础设施、DevOps、CI/CD、监控	部署、容器、可观测性、生产运维
builder	从零开始的实现、新功能	根据规格创建新代码、增量式功能开发
researcher	只读问答、代码库分析	问题、分析、比较（不修改文件）
adjudicator	只读的比较证据权衡	模糊假设、相互竞争的解释、语料比较、符号值裁定
chat	开放式对话	一般问题、头脑风暴、讨论（只读、临时）
goal	用于 /goal 运行的目标规格	为自主的多小时 Codex 会话起草结构化目标

快速执行

使用指定配置档执行一次性任务：

~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh <profile> "<prompt>"

示例：

# Code review
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh reviewer "Review src/auth.ts for security issues"

# Debug investigation
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh debugger "Debug the login timeout on slow networks"

# Architecture design
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh architect "Design a caching layer for the API"

# Security audit
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh security "Audit the payment module for vulnerabilities"

# Write profiles auto-approve by default (uses -a never + --sandbox workspace-write)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh reviewer "Fix all lint errors"

# Create execution plan for complex feature
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh planner "Create an ExecPlan for adding WebSocket support"

# Build new feature from spec
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh builder "Implement user authentication with JWT"

# Continue from previous builder session
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh builder "continue"

# Open-ended conversation (read-only, ephemeral, gpt-5.6-terra via subscription)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh chat "What are the tradeoffs of event sourcing vs CRUD?"

# Conversation via API billing (gpt-5.6-sol, bypasses Codex subscription)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh chat "Explain quantum error correction" --api --model gpt-5.6-sol

# Multi-turn API chat with session file
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh chat "What is the tallest mountain?" --api --session /tmp/chat.json
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh chat "And the deepest ocean?" --api --session /tmp/chat.json

# Streaming API response
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh chat "Tell me about CQRS" --api --model gpt-5.6-sol --stream

# Ask a question about the codebase (read-only, no file changes)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh researcher "Explain the authentication flow in this project"

# Weigh rival hypotheses or ambiguous evidence (read-only, high reasoning)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh adjudicator "With Linear B and Linear A inscriptions side-by-side, weigh candidate values for the missing sound and rank the hypotheses."

# Research with Exa web search (injects Exa guide into AGENTS.md)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh researcher "What are the latest React Server Component patterns?" --web-search

# Research with native Codex web search (model-level tool, works in all sandboxes)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh researcher "What are the latest React patterns?" --search

# Review a screenshot (vision input)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh reviewer "Review this mockup for UX issues" --image screenshot.png

# Resume previous builder session
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh builder "continue" --resume

# JSONL output for structured capture
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh researcher "What is 2+2?" --json | head -5

会话管理

如需更多控制，请使用 Python 会话管理器：

# List available profiles
python3 ~/.claude/skills/codex-orchestrator/scripts/codex-session.py list

# Start non-interactive session
python3 ~/.claude/skills/codex-orchestrator/scripts/codex-session.py start debugger "Trace the null pointer in UserService"

# Start interactive session
python3 ~/.claude/skills/codex-orchestrator/scripts/codex-session.py interactive architect

# Show profile details
python3 ~/.claude/skills/codex-orchestrator/scripts/codex-session.py info security

配置档选择指南

审查任务

• reviewer 用于一般代码质量和错误
• security 用于侧重漏洞的审查
• refactor 用于发现清理机会

调查任务

• debugger 用于调查错误
• architect 用于了解系统行为
• researcher 用于问题和分析（只读，不做修改）
• adjudicator 用于权衡相互竞争的假设、模糊证据和语料级比较（只读，推理能力强）
• chat 用于开放式对话和头脑风暴（只读、临时）

创建任务

• architect 用于设计决策
• builder 用于实现新功能
• docs 用于文档
• refactor 用于改进实现
• planner 用于制定多小时的实施计划
• goal 用于自主 /goal 目标规格

链式调用模式

审查 → 调试 → 修复

# 1. Identify issues
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh reviewer "Review src/api/ for bugs"

# 2. Investigate specific bug
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh debugger "Debug the race condition found in cache.ts"

规划 → 架构设计 → 构建

# 1. Create comprehensive ExecPlan
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh planner "Create ExecPlan for new authentication system"

# 2. Validate architecture
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh architect "Review the auth system ExecPlan for design issues"

# 3. Build (plan guides implementation)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh builder "Implement milestone 1 from the auth ExecPlan"

架构设计 → 构建 → 审查

# 1. Design approach
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh architect "Design a caching layer for the API"

# 2. Build the feature
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh builder "Implement the caching layer from architect's design"

# 3. Review the implementation
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh reviewer "Review the new caching implementation"

架构设计 → 审查 → 重构

# 1. Design approach
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh architect "Design repository layer extraction"

# 2. Validate design
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh reviewer "Review the proposed repository pattern"

# 3. Implement
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh refactor "Extract repository pattern from services"

系统工程 → 架构设计 → 规划

# 1. Assess infrastructure needs
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh syseng "Evaluate current deployment for scaling to 10x traffic"

# 2. Design architecture changes
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh architect "Design infrastructure to support 10x scale"

# 3. Create implementation plan
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh planner "Create ExecPlan for infrastructure scaling"

安全 → 系统工程

# 1. Security audit
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh security "Audit the Kubernetes cluster configuration"

# 2. Infrastructure hardening
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh syseng "Implement security recommendations from audit"

研究 → 架构设计 → 构建

# 1. Understand the problem space
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh researcher "How does the current caching work? What are its limitations?"

# 2. Design the solution
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh architect "Design a new caching layer addressing the limitations"

# 3. Implement
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh builder "Implement the caching layer from architect's design"

后台运行与并行执行

Codex CLI v0.124.0+ 需要控制 TTY。使用 shell & 或 Claude Code 的 run_in_background: true 运行时，TTY 会被分离，Codex 会静默地产生空输出（openai/codex#19945）。提示词越长，失败的可能性越高（经验观察所得）——researcher 配置尤其容易受影响。

codex-exec.sh 和 codex-goal.sh 会自动检测非 TTY 环境，并使用 script(1) 为 codex exec 重新附加伪 TTY。无需用户进行任何操作。

对于直接调用 codex exec（而非通过 codex-exec.sh 调用），请手动包装：

# macOS
script -q /dev/null codex exec --skip-git-repo-check "prompt" </dev/null

# Linux
script -qfc 'codex exec --skip-git-repo-check "prompt" </dev/null' /dev/null

AGENTS.md 备份按 PID 隔离——多个 codex-exec.sh 实例可以安全地在同一目录中运行。

--no-cleanup 标志（仅限 codex-exec.sh）：设置后，退出时会保留输出临时文件，并将其路径打印到 stderr（OUTPUT_FILE=<path>）。当调用方需要异步获取输出文件时使用。

目标运行

/goal 命令会设置一个持久目标，让 Codex 自主地持续数小时朝其推进。目标仅限 TUI 使用（在 codex exec 模式下不可用），因此目标运行采用两阶段工作流。

两阶段工作流

阶段 1 — 起草： 使用 goal 配置，通过 codex exec 生成结构化的目标规范文件。

阶段 2 — 运行： 根据规范文件设置 /goal，启动交互式 Codex TUI。

用法

# Draft a goal specification
~/.claude/skills/codex-orchestrator/scripts/codex-goal.sh draft "Add authentication with JWT to the API"

# Draft with custom output path
~/.claude/skills/codex-orchestrator/scripts/codex-goal.sh draft "Migrate to PostgreSQL" --output goals/pg-migration.md

# List existing goals
~/.claude/skills/codex-orchestrator/scripts/codex-goal.sh list

# Launch Codex TUI with a goal
~/.claude/skills/codex-orchestrator/scripts/codex-goal.sh run goals/goal-20260518-143000.md

# Run with custom model
~/.claude/skills/codex-orchestrator/scripts/codex-goal.sh run goals/goal-01.md --model gpt-5.6-sol

目标文件格式

目标规范采用带有 YAML frontmatter 的结构化格式：

---
objective: "One-line summary"
status: draft
created: 2026-05-18
project: /path/to/project
---

# Goal: <objective>

## Objective / Stopping Condition / Context / Constraints / Validation / Checkpoints / Progress Log

少于 3,500 个字符的目标会直接内嵌到 /goal 命令中。较长的目标则通过文件路径引用。

链式流程：规划器 → 目标 → 运行 → 审查者

# 1. Plan the feature
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh planner "Create ExecPlan for caching layer"

# 2. Draft a goal from the plan
~/.claude/skills/codex-orchestrator/scripts/codex-goal.sh draft "Implement caching layer per ExecPlan"

# 3. Launch autonomous goal run
~/.claude/skills/codex-orchestrator/scripts/codex-goal.sh run goals/goal-20260518-143000.md

# 4. Review what Codex built
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh reviewer "Review the caching implementation"

注意事项

• /goal 仅限 TUI 使用——run 子命令会启动交互式 Codex 会话（不会重定向 stdin）
• 需要在 ~/.codex/config.toml 中设置 features.goals = true（或使用 --enable goals 标志，脚本会自动传入）
• 每个线程只能有一个目标——设置不同目标前必须先执行 /goal clear
• /goal 内容限制为 4,000 个字符（起草阶段的目标少于 3,500 个字符，以预留额外空间）

完整的 /goal 命令参考请参见 references/goal-command.md。

脚本选项

codex-exec.sh 选项

选项	说明
--model <model>	覆盖模型（默认值按配置而定，见下文）
--reasoning <level>	覆盖推理强度：minimal、low、medium、high、xhigh
--sandbox <mode>	read-only、workspace-write、danger-full-access
--no-approve	强制使用只读沙箱（不写入文件）
--web-search	启用 Exa 网页搜索（将指南注入 AGENTS.md）
--search	启用 Codex 原生网页搜索（模型级工具，适用于所有沙箱）
--json	输出 JSONL 事件流（可传递给 jq、日志等）
--image <file>	将图像附加到提示词（视觉输入）
--resume	恢复之前的执行会话（builder“继续”工作流）
--with-mcp	（无操作，为兼容性保留；在 ~/.codex/config.toml 中管理 MCP）
--api	直接使用 OpenAI API（按 API 计费，不使用 Codex 订阅）
--session <file>	多轮 API 聊天的会话文件（需要 --api）
--system <prompt>	API 聊天的系统提示词（需要 --api）
--stream	流式输出 API 响应 token（需要 --api）

模型与推理默认值

每个配置都有默认模型和推理强度。用户标志会覆盖这些默认值。

配置类型	配置	模型	推理强度
编码	builder、reviewer、debugger、refactor、syseng、security、docs	gpt-5.6-sol	high
规划	planner、architect、goal	gpt-5.6-sol	high
研究	researcher	gpt-5.6-sol	medium
裁定	adjudicator	gpt-5.6-sol	high
聊天	chat	gpt-5.6-terra	medium

推理强度级别：none < minimal < low < medium < high < max

# Uses profile defaults (builder → gpt-5.6-sol + high)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh builder "Implement auth module"

# Uses profile defaults (planner → gpt-5.6-sol + high)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh planner "Create ExecPlan for caching"

# Override model for quick tasks
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh reviewer "Style check" --model gpt-5.6-luna

# Override reasoning only
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh builder "Quick lint fix" --reasoning medium

# Override both
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh planner "Design distributed cache" --model gpt-5.6-sol --reasoning max

API 模式（直接调用 OpenAI API）

--api 标志会完全绕过 Codex CLI，通过 gpt-api-chat.py 直接调用 OpenAI API。费用由你的 OPENAI_API_KEY 承担，而非 Codex 订阅。

适用场景：

• 使用 Codex 订阅中没有的模型（例如 gpt-5.6-sol）
• 支持会话持久化的多轮对话
• 流式响应
• 自定义系统提示词

# One-shot API query
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh chat "Explain X" --api --model gpt-5.6-sol

# Multi-turn with session file (context carries across calls)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh chat "What is X?" --api --session /tmp/session.json
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh chat "Tell me more" --api --session /tmp/session.json

# Streaming output
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh chat "Describe Y" --api --model gpt-5.6-sol --stream

# Custom system prompt
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh chat "Analyze this" --api --system "You are a security analyst"

# Any profile works with --api (sends raw prompt to OpenAI API, no Codex CLI)
~/.claude/skills/codex-orchestrator/scripts/codex-exec.sh researcher "What are the latest React patterns?" --api --model gpt-5.6-sol

支持的模型： gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna、gpt-5.5、gpt-5.5-pro、gpt-5.4、gpt-5-mini

三方模式（Claude + GPT）： 在 Claude Code 会话中，通过 Bash 调用 gpt-api-chat.py，读取 GPT 的响应，综合各方观点并引导对话。使用 --session 可在多轮对话中保留 GPT 的上下文。

要求： 环境中需设置 OPENAI_API_KEY（从 ~/.config/env/secrets.env 加载）

测试

运行测试套件以验证安装：

~/.claude/skills/codex-orchestrator/scripts/test-codex.sh         # Full tests
~/.claude/skills/codex-orchestrator/scripts/test-codex.sh --quick # Skip API test

参考文档

详细信息请参阅：

• references/codex-cli.md - 完整的 CLI 命令参考
• references/agents-md-format.md - AGENTS.md 语法和最佳实践
• references/subagent-patterns.md - 委派模式和示例
• references/goal-command.md - /goal 命令参考和最佳实践

故障排除

“找不到 Codex CLI”

npm install -g @openai/codex

“身份验证错误”

export OPENAI_API_KEY=sk-...
# or
codex login

“ChatGPT 账户不支持此模型”

旧版模型名称（codex-mini、o3、o4-mini）已弃用。当前模型：gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna、gpt-5.5、gpt-5.5-pro、gpt-5-mini。上一代模型（gpt-5.4、gpt-5.4-pro、gpt-5.3-codex、gpt-5.2）仍可使用，但已被取代。 请改为设置 API 密钥，而不是使用 codex login：

export OPENAI_API_KEY=sk-...

“找不到配置文件”

可用配置文件：reviewer、debugger、architect、security、refactor、docs、planner、syseng、builder、researcher、adjudicator、chat、goal

检查配置文件是否存在：

ls ~/.claude/skills/codex-orchestrator/agents/

“Codex 未生成输出”

researcher/adjudicator/chat 配置文件会将输出写入临时文件。如果 Codex 退出时未写入该文件，脚本会发出警告并以状态码 1 退出。常见原因：

• TTY 分离（最常见）：Codex CLI v0.124.0+ 在没有 TTY 的情况下转入后台时会静默崩溃。codex-exec.sh 会自动使用 script(1) 包装命令 — 请确认你的 Codex 版本（codex --version）。提示词越长，失败率越高。
• Codex 会话太短，无法生成响应
• 模型返回了空响应（请重试）
• 缺少 AGENTS.md（请检查工作目录中是否有过时的 .AGENTS.md.codex-backup.* 文件）

结果不理想

• 缩小任务范围
• 在提示词中提供更多上下文
• 尝试其他配置文件
• 对于复杂任务，使用 --model gpt-5.6-sol --reasoning max