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.
# 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)
codex # Launch interactive terminal UI
codex "explain this codebase" # Start with a prompt
codex --cd ~/projects/myapp # Set working directory
Non-Interactive (Scripting)
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
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:
# 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:
// 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:
{
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:
codex mcp-server # Exposes Codex tools via stdio MCP
Clawdbot Config: OpenAI Codex Provider
Use your ChatGPT Pro subscription via the
openai-codex
provider:
{
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
# 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
# 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/
:
<!-- ~/.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:
# 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
:
[features]
web_search_request = true
[sandbox_workspace_write]
network_access = true
Then Codex can search for current docs, APIs, etc.
Best Practices
- Start with
/init
to create AGENTS.md with repo-specific instructions
- Use
/review
before commits for AI code review
- Set
/approvals
appropriately — Auto for trusted repos, Read Only for exploration
- Use
--add-dir
for monorepos instead of danger-full-access
- Resume sessions to maintain context across coding sessions
- Attach images for UI work, design specs, error screenshots
Example Workflows
Fix CI Failure
codex exec --full-auto "The CI is failing on the lint step. Fix all ESLint errors."
Refactor Component
codex exec --cd src/components "Refactor UserProfile.tsx to use React Query instead of useEffect for data fetching"
Implement Feature from Spec
codex exec -i spec.png --cd ~/projects/app "Implement this feature based on the design spec"
Code Review PR
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
