Introduction
# OpenAI Codex CLI Skill
Use OpenAI Codex CLI (`codex`) for coding tasks including code review, refactoring, bug fixes, CI repairs, and feature implementation. Codex CLI runs locally on your machine with full filesystem access.
## When to Use
- User asks for code changes, refactoring, or implementation - CI/build failures need fixing - Code review before commit/push - Large codebase exploration or explanation - Tasks requiring file editing + command execution - When GPT-5-Codex model strengths are needed (code generation, tool use)
## Installation & Auth
Codex CLI requires ChatGPT Plus/Pro/Business/Enterprise subscription.
```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 ```
## Core Commands
### Interactive Mode (TUI) ```bash codex # Launch interactive terminal UI codex "explain this codebase" # Start with a prompt codex --cd ~/projects/myapp # Set working directory ```
### Non-Interactive (Scripting) ```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 ```
### Session Management ```bash codex resume # Pick from recent sessions codex resume --last # Continue most recent codex resume <SESSION_ID> # Resume specific session ```
## Slash Commands (In TUI)
| Command | Purpose | |---------|---------| | `/model` | Switch model (gpt-5-codex, gpt-5) | | `/approvals` | Set approval mode (Auto, Read Only, Full Access) | | `/review` | Code review against branch, uncommitted changes, or specific commit | | `/diff` | Show Git diff including untracked files | | `/compact` | Summarize conversation to free context | | `/init` | Generate AGENTS.md scaffold | | `/status` | Show session config and token usage | | `/undo` | Revert most recent turn | | `/new` | Start fresh conversation | | `/mcp` | List configured MCP tools | | `/mention <path>` | Attach file to conversation |
## Approval Modes
| Mode | Behavior | |------|----------| | **Auto** (default) | Read/edit/run commands in workspace; asks for outside access | | **Read Only** | Browse files only; requires approval for changes | | **Full Access** | Full machine access including network (use sparingly) |
## Key Flags
| Flag | Purpose | |------|---------| | `--model, -m <model>` | Override model (gpt-5-codex, gpt-5) | | `--cd, -C <path>` | Set working directory | | `--add-dir <path>` | Add additional writable roots | | `--image, -i <path>` | Attach image(s) to prompt | | `--full-auto` | Workspace write + approve on failure | | `--sandbox <mode>` | read-only, workspace-write, danger-full-access | | `--json` | Output newline-delimited JSON | | `--search` | Enable web search tool |
## Clawdbot Integration Patterns
### Pattern 1: Direct exec Tool Call Codex from Clawdbot's exec tool for coding tasks:
```bash # In Clawdbot session exec codex exec --full-auto --cd ~/projects/medreport "fix the TypeScript errors in src/components" ```
### Pattern 2: Subagent Delegation Spawn a coding subagent that uses 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"] } } ] } } ```
### Pattern 3: CLI Backend Fallback Configure Codex as a text-only fallback:
```json5 { agents: { defaults: { cliBackends: { "codex-cli": { command: "codex", args: ["exec", "--full-auto"], output: "text", sessionArg: null // Codex manages its own sessions } } } } } ```
### Pattern 4: MCP Server Mode Run Codex as an MCP server for other agents:
```bash codex mcp-server # Exposes Codex tools via stdio MCP ```
## Clawdbot Config: OpenAI Codex Provider
Use your ChatGPT Pro subscription via the `openai-codex` provider:
```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" } } } } } ```
Auth syncs automatically from `~/.codex/auth.json` to Clawdbot's auth profiles.
## Code Review Workflow
```bash # Interactive review codex /review # Choose: branch, uncommitted, or specific commit
# Non-interactive codex exec "review the changes in this PR against main branch" ```
## Multi-Directory Projects
```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 ```
## Custom Slash Commands
Create reusable prompts in `~/.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. ```
Invoke: `/prompts:pr BRANCH=feature-auth TITLE="Add OAuth flow"`
## MCP Integration
Add MCP servers to extend 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 ```
## Web Search
Enable in `~/.codex/config.toml`:
```toml [features] web_search_request = true
[sandbox_workspace_write] network_access = true ```
Then Codex can search for current docs, APIs, etc.
## Best Practices
1. **Start with `/init`** to create AGENTS.md with repo-specific instructions 2. **Use `/review` before commits** for AI code review 3. **Set `/approvals` appropriately** — Auto for trusted repos, Read Only for exploration 4. **Use `--add-dir`** for monorepos instead of `danger-full-access` 5. **Resume sessions** to maintain context across coding sessions 6. **Attach images** for UI work, design specs, error screenshots
## Example Workflows
### Fix CI Failure ```bash codex exec --full-auto "The CI is failing on the lint step. Fix all ESLint errors." ```
### Refactor Component ```bash codex exec --cd src/components "Refactor UserProfile.tsx to use React Query instead of useEffect for data fetching" ```
### Implement Feature from Spec ```bash codex exec -i spec.png --cd ~/projects/app "Implement this feature based on the design spec" ```
### Code Review PR ```bash codex exec "Review the diff between main and feature/auth branch. Focus on security issues." ```
## Troubleshooting
| Issue | Solution | |-------|----------| | Auth fails | Run `codex logout` then `codex login` | | Commands blocked | Check `/approvals`, may need `--full-auto` | | Out of context | Use `/compact` to summarize | | Wrong directory | Use `--cd` flag or check `/status` | | Model unavailable | Verify subscription tier supports model |
## References
- [Codex CLI Overview](https://developers.openai.com/codex/cli) - [Codex CLI Features](https://developers.openai.com/codex/cli/features) - [Codex CLI Reference](https://developers.openai.com/codex/cli/reference) - [Slash Commands Guide](https://developers.openai.com/codex/cli/slash-commands) - [AGENTS.md Spec](https://agents.md) - [Codex GitHub](https://github.com/openai/codex)