codex-orchestrator

用途

Codex Orchestrator 是一套面向 Claude Code 的编排技能（skill），核心思路是把 Claude 定位为“战略编排者”，把 Codex 智能体当作“执行部队”。用户下达任务与愿景，Claude 负责把意图翻译成可执行命令，指挥自己的 Codex 智能体军团完成实际工作。资料描述中，用户可同时运行 4 个以上 Claude 实例，每个 Claude 各自拥有一支 Codex 部队，用于在数天内而非数周内构建大型代码库。

主要能力

默认流水线：对任何需要执行的任务，默认派生 Codex 智能体，而不是 Claude 自己实现，也不使用 Claude 子智能体。
角色分工：Claude 负责战略层（讨论策略、写 PRD 与规格、派生并指挥智能体、综合发现、做决策、沟通进度）；Codex 智能体负责执行层（深度阅读代码库、谨慎实现、自我验证）。
工厂式流水线：构思（Claude+用户）→ 研究（Codex，只读）→ 综合（Claude）→ PRD（Claude+用户）→ 实现（Codex，workspace-write）→ 审查（Codex，只读）→ 测试（Codex，workspace-write）。
回合感知编排：Codex 智能体内置 notify 钩子，智能体完成回合时写入信号文件，await-turn 命令阻塞等待该文件出现，无需手动轮询。
代码库地图：--map 标志把 docs/CODEBASE_MAP.md 注入智能体提示，提供文件用途、模块边界、数据流、依赖、约定与导航指南。
约束提示：为 Codex 智能体提供强制约束块（design_and_scope_constraints、context_loading、plan_first、output_verbosity_spec），防止范围漂移、过度重构与跳过阅读。
推理强度分级：medium、high、xhigh 三档，按任务复杂度选择。
执行模式：exec（默认，自动完成）与 interactive（支持中途 send 纠偏）。

使用方式

前置条件：需安装 tmux（终端复用器）、Bun（JavaScript 运行时）、OpenAI Codex CLI，并完成 OpenAI 认证（codex --login）。

健康检查：

codex-agent health    # checks tmux + codex are available

安装脚本（推荐，不要手动逐步安装）：

bash "${CLAUDE_PLUGIN_ROOT}/scripts/install.sh"

若 ${CLAUDE_PLUGIN_ROOT} 不可用（手动安装技能）：

bash ~/.codex-orchestrator/plugins/codex-orchestrator/scripts/install.sh

认证：

codex --login

标准编排循环：

派生（前台，即时，获取 job ID）：

codex-agent start "Your task prompt here" -r high --map -s read-only

等待（阻塞直到智能体响应），使用 Bash 工具并设置 run_in_background: true：

JOB_ID="abc12345"
codex-agent await-turn "$JOB_ID"
echo "CODEX_AGENT_TURN_COMPLETE=$JOB_ID"
codex-agent status "$JOB_ID"

反应：读取输出后决定下一步——发送后续（codex-agent send $id "Now do X"）、关闭（codex-agent send $id "/quit"）、或继续读取（codex-agent capture $id 200 --clean）。

并行派生多个智能体时，把所有第 1 步调用放在同一条消息中并行执行，再把所有第 2 步调用放在同一条消息中并行执行。

macOS 沙箱兼容：在 macOS 上，Codex CLI（Rust 二进制）需要 Unix socket 访问 configd 以进行 DNS 解析。若 Claude Code 沙箱阻止，codex exec 会因 system-configuration crate 错误而 panic。因此所有 codex-agent 的 Bash 调用都应带 dangerouslyDisableSandbox: true，例如：

Bash(codex-agent start "..." --map, dangerouslyDisableSandbox: true)
Bash(codex-agent await-turn <id>, dangerouslyDisableSandbox: true)
Bash(codex-agent status <id>, dangerouslyDisableSandbox: true)
Bash(codex-agent capture <id>, dangerouslyDisableSandbox: true)

代码库地图由 Cartographer（另一个 Claude Code 插件）生成：

/plugin marketplace add kingbootoshi/cartographer
/plugin install cartographer
/cartographer

这会创建 docs/CODEBASE_MAP.md。

CLI 默认值：模型 gpt-5.4、推理 xhigh、沙箱 workspace-write。常用标志为 --map（包含代码库上下文）、-s read-only（研究任务）、-f（包含特定文件）。

适用场景

多文件改动、需要理解数据流的改动、安全敏感修改、涉及测试的改动。
代码库研究、文件与模式调查、安全审计、测试、多步执行、任何需要文件访问的任务。
需要并行推进的独立任务批次。
需要中途纠偏的多阶段工作（使用 interactive 模式）。

限制与例外

琐碎任务绕过：单文件、少于 50 行、需求明确的改动（改错别字、配置微调、简单重命名）应直接用 Claude 原生工具完成，不要派生 Codex 智能体，否则会为 30 秒的编辑增加 10-20 分钟开销。
Claude 子智能体例外：仅当用户明确要求（“you do it”“don't use Codex”“use a Claude subagent”）或为对话上下文快速读取单个文件时，才使用 Claude 子智能体。
智能体耗时较长属正常：简单研究 10-20 分钟，单功能实现 20-40 分钟，复杂实现 30-60+ 分钟，完整 PRD 实现 45-90+ 分钟。不应因运行 20 分钟就杀掉智能体，也不应在 15 分钟后询问用户是否查看。
安装依赖仅使用官方来源：tmux 来自系统包管理器，Bun 来自 bun.sh，Codex CLI 来自 npm，无需 sudo。
资料未提供收费、价格、平台支持范围等具体信息。

技能介绍

用途

主要能力

使用方式

适用场景

限制与例外