---

name: codex-cli
description: "使用 OpenAI Codex CLI 处理编程任务。触发词：codex、代码审查、修复 CI、重构代码、实现功能、编程代理、gpt-5-codex。允许 Clawdbot 将编程工作委托给 Codex CLI 作为子代理或直接工具。"

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                           # 启动交互式终端界面  
codex "解释这个代码库"           # 通过提示词启动  
codex --cd ~/projects/myapp     # 设置工作目录  

非交互模式 (脚本)

codex exec "修复 CI 失败"                    # 执行后退出  
codex exec --full-auto "添加输入验证"        # 自动批准工作区写入  
codex exec --json "列出所有 API 端点"        # 输出 JSON 格式便于解析  
codex exec -i screenshot.png "匹配这个设计"  # 使用图片输入  

会话管理

codex resume               # 从近期会话中选择恢复  
codex resume --last        # 继续最近一次会话  
codex resume <会话ID>      # 恢复特定会话  

斜杠命令 (TUI界面)

审批模式

关键参数

Clawdbot 集成模式

模式1：直接执行工具

通过Clawdbot的exec工具调用Codex处理编码任务：

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

模式2：子代理委托

生成一个使用Codex的编码子代理：

// 在agents.defaults或单代理配置中
{
  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配置为纯文本后备方案：

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

模式4：MCP服务器模式

将Codex作为MCP服务器运行供其他代理使用：

codex mcp-server  # 通过stdio MCP暴露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  # 选择：分支、未提交内容或特定提交

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

多目录项目

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

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

自定义斜杠命令

在 ~/.codex/prompts/ 中创建可重用的提示：

<!-- ~/.codex/prompts/pr.md -->
---
description: 准备并打开一个草稿 PR
argument-hint: [BRANCH=<name>] [TITLE="<title>"]
---

如果指定了分支，则创建 `dev/$BRANCH`。
阶段性提交更改并附带明确的提交信息。
打开一个草稿 PR，标题为 $TITLE 或自动生成一个。

调用：/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

网页搜索

在 ~/.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 — 自动审批用于受信任的仓库，只读用于探索性项目
4. 使用 --add-dir 处理 monorepo 而不是 danger-full-access
5. 恢复会话 以在编码会话之间保持上下文
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 概述
• Codex CLI 功能
• Codex CLI 参考
• 斜杠命令指南
• AGENTS.md 规范
• Codex GitHub