OpenAI Codex Sub Agents

OpenAI Codex CLI 技能

使用 OpenAI Codex CLI（codex）执行各类编码任务，包括代码审查、重构、缺陷修复、CI 修复以及功能实现。Codex CLI 在本地机器上运行，具备完整的文件系统访问权限。

使用场景

• 用户请求代码修改、重构或功能实现
• CI/构建失败需要修复
• 提交/推送前进行代码审查
• 大型代码库的探索或解释
• 需要文件编辑 + 命令执行的任务
• 需要利用 GPT-5-Codex 模型优势的场景（如代码生成、工具调用）

安装与认证

Codex CLI 要求用户拥有 ChatGPT Plus / Pro / Business / Enterprise 订阅。

# 安装
npm i -g @openai/codex

# 认证（打开浏览器进行 OAuth）
codex login

# 或使用 API 密钥
printenv OPENAI_API_KEY | codex login --with-api-key

# 验证认证状态
codex login status

核心命令

交互模式（TUI）

codex                           # 启动交互式终端 UI
codex "解释这个代码库"         # 使用指定提示启动
codex --cd ~/projects/myapp     # 设置工作目录

非交互模式（脚本化调用）

codex exec "修复 CI 失败"                          # 执行后退出
codex exec --full-auto "添加输入校验"              # 自动批准 workspace-write 操作
codex exec --json "列出所有 API 端点"              # 输出 JSON 格式，便于解析
codex exec -i screenshot.png "匹配该设计图"        # 支持图像输入

会话管理

codex resume               # 从最近会话中选择继续
codex resume --last        # 继续最近一次会话
codex resume# 恢复指定会话

斜杠命令（在 TUI 中使用）

审批模式

关键标志（Flags）

Clawdbot 集成模式

模式 1：直接调用 exec 工具

在 Clawdbot 会话中通过 exec 工具调用 Codex 执行编码任务：

# 在 Clawdbot 会话中
exec codex exec --full-auto --cd ~/projects/medreport "修复 src/components 中的 TypeScript 错误"

模式 2：子代理委托

启动一个使用 Codex 的编码子代理：

// 在 agents.defaults 或单个 agent 配置中
{
  agents: {
    list: [
      {
        id: "coder",
        workspace: "~/clawd-coder",
        model: "openai-codex/gpt-5.2",  // 复用 Codex 认证
        tools: {
          allow: ["exec", "read", "write", "edit", "apply_patch", "process"]
        }
      }
    ]
  }
}

模式 3：CLI 后端回退机制

将 Codex 配置为纯文本模式的 CLI 回退后端：

{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "codex",
          args: ["exec", "--full-auto"],
          output: "text",
          sessionArg: null  // Codex 自行管理会话
        }
      }
    }
  }
}

模式 4：MCP Server 模式

以 MCP server 方式运行 Codex，供其他 agent 调用：

codex mcp-server  # 通过 stdio 协议暴露 Codex 工具能力

Clawdbot 配置：OpenAI Codex 提供方

通过 openai-codex 提供方使用您的 ChatGPT Pro 订阅：

{
  agents: {
    defaults: {
      model: { primary: "openai-codex/gpt-5.2" },
      models: {
        "openai-codex/gpt-5.2": { alias: "Codex" },
        "anthropic/claude-opus-4-5": { alias: "Opus" }
      }
    }
  }
}

认证信息将自动从 ~/.codex/auth.json 同步至 Clawdbot 的认证配置文件。

代码审查工作流

# 交互式审查
codex
/review  # 选择：分支、未提交变更或特定 commit

# 非交互式审查
codex exec "针对 main 分支审查此 PR 中的变更"

多目录项目支持

# 在单体仓库（monorepo）中跨 package 工作
codex --cd apps/frontend --add-dir ../backend --add-dir ../shared

# 或在 TUI 中使用
codex --cd ~/projects/myapp --add-dir ~/projects/shared-lib

自定义斜杠命令

在 ~/.codex/prompts/ 下创建可复用的 prompt 模板：

若指定了 $BRANCH，则创建分支 `dev/$BRANCH`。
暂存并提交变更，并附带清晰的提交信息。
以 $TITLE 为标题（或自动生成）创建草稿 PR。

调用方式：/prompts:pr BRANCH=feature-auth TITLE="添加 OAuth 流程"

MCP 集成

添加 MCP server 以扩展 Codex 能力：

# 添加 stdio 类型 server
codex mcp add github -- npx @anthropic/mcp-server-github

# 添加 HTTP 类型 server
codex mcp add docs --url https://mcp.deepwiki.com/mcp

# 列出已配置的 MCP servers
codex mcp list

网络搜索功能

在 ~/.codex/config.toml 中启用：

[features]
web_search_request = true

[sandbox_workspace_write]
network_access = true

启用后，Codex 可检索最新文档、API 规范等内容。

最佳实践

1. 首次使用 /init 创建 AGENTS.md，包含仓库专属指令
2. 提交前使用 /review 进行 AI 辅助代码审查
3. 合理设置 /approvals —— 可信仓库使用 Auto，探索性任务使用 Read Only
4. 多目录项目优先使用 --add-dir，避免启用 danger-full-access
5. 通过 codex resume 恢复会话，维持跨会话上下文连续性
6. 对 UI 相关任务附加图像，例如设计稿、错误截图等

示例工作流

修复 CI 失败

codex exec --full-auto "CI 在 lint 步骤失败。修复所有 ESLint 错误。"

重构组件

codex exec --cd src/components "将 UserProfile.tsx 重构为使用 React Query 替代 useEffect 进行数据获取"

基于规范实现功能

codex exec -i spec.png --cd ~/projects/app "根据该设计规范实现此功能"

审查 PR

codex exec "对比 main 与 feature/auth 分支的差异，重点关注安全问题。"

故障排查

参考资料

• [Codex CLI 概览](https://developers.openai.com/codex/cli)
• [Codex CLI 功能说明](https://developers.openai.com/codex/cli/features)
• [Codex CLI 参考手册](https://developers.openai.com/codex/cli/reference)
• [斜杠命令指南](https://developers.openai.com/codex/cli/slash-commands)
• [AGENTS.md 规范](https://agents.md)
• [Codex GitHub 仓库](https://github.com/openai/codex)