介绍
# OpenAI Codex CLI Skill
使用 OpenAI Codex CLI (`codex`) 完成编码任务，包括代码审查、重构、Bug 修复、CI 修复和功能实现。Codex CLI 在您的机器本地运行，拥有完整的文件系统访问权限。
## 何时使用
- 用户要求代码更改、重构或实现 - CI/构建失败需要修复 - 提交/推送前的代码审查 - 大型代码库探索或解释 - 需要文件编辑 + 命令执行的任务 - 需要 GPT-5-Codex 模型优势时（代码生成、工具使用）
## 安装与认证
Codex CLI 需要 ChatGPT Plus/Pro/Business/Enterprise 订阅。
```bash # Install npm i -g @openai/codex
# Authenticate (opens browser for OAuth) codex login
# Or use API key printenv OPENAI_API_KEY | codex login --with-api-key
# Verify auth codex login status ```
## 核心命令
### 交互模式 (TUI) ```bash codex # Launch interactive terminal UI codex "explain this codebase" # Start with a prompt codex --cd ~/projects/myapp # Set working directory ```
### 非交互模式 (脚本) ```bash codex exec "fix the CI failure" # Run and exit codex exec --full-auto "add input validation" # Auto-approve workspace writes codex exec --json "list all API endpoints" # JSON output for parsing codex exec -i screenshot.png "match this design" # With image input ```
### 会话管理 ```bash codex resume # Pick from recent sessions codex resume --last # Continue most recent codex resume <SESSION_ID> # Resume specific session ```
## 斜杠命令 (在 TUI 中)
| 命令 | 用途 | |---------|---------| | `/model` | 切换模型 (gpt-5-codex, gpt-5) | | `/approvals` | 设置审批模式 (自动、只读、完全访问) | | `/review` | 针对分支、未提交的更改或特定提交进行代码审查 | | `/diff` | 显示包含未跟踪文件的 Git diff | | `/compact` | 总结对话以释放上下文 | | `/init` | 生成 AGENTS.md 脚手架 | | `/status` | 显示会话配置和 token 使用情况 | | `/undo` | 撤销最近一轮对话 | | `/new` | 开始新对话 | | `/mcp` | 列出已配置的 MCP 工具 | | `/mention <path>` | 将文件附加到对话中 |
## 审批模式
| 模式 | 行为 | |------|----------| | **Auto** (默认) | 读取/编辑/运行工作区中的命令；外部访问需请求 | | **Read Only** | 仅浏览文件；更改需要审批 | | **Full Access** | 完全的机器访问权限，包括网络（请谨慎使用） |
## 关键标志
| 标志 | 用途 | |------|---------| | `--model, -m <model>` | 覆盖模型 (gpt-5-codex, gpt-5) | | `--cd, -C <path>` | 设置工作目录 | | `--add-dir <path>` | 添加额外的可写根目录 | | `--image, -i <path>` | 将图像附加到提示词 | | `--full-auto` | 工作区写入 + 失败时自动审批 | | `--sandbox <mode>` | read-only, workspace-write, danger-full-access | | `--json` | 输出换行符分隔的 JSON | | `--search` | 启用网络搜索工具 |
## Clawdbot 集成模式
### 模式 1：直接 exec 工具
通过 Clawdbot 的 exec 工具调用 Codex 执行编码任务：
```bash # In Clawdbot session exec codex exec --full-auto --cd ~/projects/medreport "fix the TypeScript errors in src/components" ```
### 模式 2：子代理委托
生成一个使用 Codex 的编码子代理：
```json5 // In agents.defaults or per-agent config { agents: { list: [ { id: "coder", workspace: "~/clawd-coder", model: "openai-codex/gpt-5.2", // Uses Codex auth tools: { allow: ["exec", "read", "write", "edit", "apply_patch", "process"] } } ] } } ```
### 模式 3：CLI 后端回退
将 Codex 配置为纯文本回退：
```json5 { agents: { defaults: { cliBackends: { "codex-cli": { command: "codex", args: ["exec", "--full-auto"], output: "text", sessionArg: null // Codex manages its own sessions } } } } } ```
### 模式 4：MCP 服务器模式
将 Codex 作为 MCP 服务器运行，供其他代理使用：
```bash codex mcp-server # Exposes Codex tools via stdio MCP ```
## Clawdbot 配置：OpenAI Codex 提供商
通过 `openai-codex` 提供商使用您的 ChatGPT Pro 订阅：
```json5 { 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 的认证配置文件。
## 代码审查工作流
```bash # Interactive review codex /review # Choose: branch, uncommitted, or specific commit
# Non-interactive codex exec "review the changes in this PR against main branch" ```
## 多目录项目
```bash # Work across monorepo packages codex --cd apps/frontend --add-dir ../backend --add-dir ../shared
# Or in TUI codex --cd ~/projects/myapp --add-dir ~/projects/shared-lib ```
## 自定义斜杠命令
在 `~/.codex/prompts/` 中创建可重用的提示词：
```markdown <!-- ~/.codex/prompts/pr.md --> --- description: Prepare and open a draft PR argument-hint: [BRANCH=<name>] [TITLE="<title>"] ---
Create branch `dev/$BRANCH` if specified. Stage and commit changes with a clear message. Open a draft PR with title $TITLE or auto-generate one. ```
调用：`/prompts:pr BRANCH=feature-auth TITLE="Add OAuth flow"`
## MCP 集成
添加 MCP 服务器以扩展 Codex：
```bash # Add stdio server codex mcp add github -- npx @anthropic/mcp-server-github
# Add HTTP server codex mcp add docs --url https://mcp.deepwiki.com/mcp
# List configured codex mcp list ```
## 网络搜索
在 `~/.codex/config.toml` 中启用：
```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`** 处理 monorepos，而不是 `danger-full-access` 5. **恢复会话** 以在不同的编码会话之间保持上下文 6. **附加图像** 用于 UI 工作、设计规范、错误截图
## 示例工作流
### 修复 CI 失败 ```bash codex exec --full-auto "The CI is failing on the lint step. Fix all ESLint errors." ```
### 重构组件 ```bash codex exec --cd src/components "Refactor UserProfile.tsx to use React Query instead of useEffect for data fetching" ```
### 根据规范实现功能 ```bash codex exec -i spec.png --cd ~/projects/app "Implement this feature based on the design spec" ```
### 审查 PR 代码 ```bash codex exec "Review the diff between main and feature/auth branch. Focus on security issues." ```
## 故障排除
| 问题 | 解决方案 | |-------|----------| | 认证失败 | 运行 `codex logout` 然后 `codex login` | | 命令被阻止 | 检查 `/approvals`，可能需要 `--full-auto` | | 上下文不足 | 使用 `/compact` 进行总结 | | 目录错误 | 使用 `--cd` 标志或检查 `/status` | | 模型不可用 | 验证订阅层级是否支持该模型 |
## 参考资料
- [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)