Codex Sub Agents 1

OpenAI Codex CLI 技能

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

适用场景

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

安装与认证

Codex CLI 要求用户具备 ChatGPT Plus / Pro / Business / Enterprise 订阅资格。

# 安装
npm i -g @openai/codex

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

# 或使用 API Key
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# 恢复指定 ID 的会话

斜杠命令（在 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，供其他代理调用：

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 的 auth profiles。

代码审查工作流

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

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

多目录项目支持

# 在 monorepo 中跨 package 工作
codex --cd apps/frontend --add-dir ../backend --add-dir ../shared

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

自定义斜杠命令

在 ~/.codex/prompts/ 下创建可复用提示模板：

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

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

MCP 集成

添加 MCP 服务以扩展 Codex 能力：

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

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

# 列出已配置的服务
codex mcp list

Web 搜索支持

在 ~/.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)