codex-cli

어떤 스킬인가요?

Use OpenAI Codex CLI for coding tasks. Triggers: codex, code review, fix CI, refactor code, implement feature, coding agent, gpt-5-codex. Enables Clawdbot to delegate coding work to Codex CLI as a subagent or direct tool.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

---
name: codex-cli
description: "Use OpenAI Codex CLI for coding tasks. Triggers: codex, code review, fix CI, refactor code, implement feature, coding agent, gpt-5-codex. Enables Clawdbot to delegate coding work to Codex CLI as a subagent or direct tool."
---

# 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)

# Clawdbot + Codex CLI Integration Patterns

## Overview

Clawdbot can integrate with OpenAI Codex CLI in multiple ways:
1. **Provider**: Use `openai-codex` provider for ChatGPT Pro subscription routing
2. **Exec tool**: Call `codex exec` directly from Clawdbot
3. **Subagent**: Spawn a dedicated coding subagent
4. **CLI Backend**: Fallback text-only mode
5. **MCP Server**: Run Codex as MCP server for tool access

## Pattern 1: OpenAI Codex Provider

Use your ChatGPT Pro/Plus subscription with Clawdbot's built-in `openai-codex` provider.

### Config

```json5
// ~/.clawdbot/clawdbot.json
{
  agents: {
    defaults: {
      model: { 
        primary: "openai-codex/gpt-5.2",
        fallbacks: ["anthropic/claude-sonnet-4-5"]
      },
      models: {
        "openai-codex/gpt-5.2": { alias: "Codex" },
        "anthropic/claude-opus-4-5": { alias: "Opus" }
      }
    }
  }
}
```

### Auth Sync

Clawdbot auto-syncs OAuth tokens from Codex CLI:
- Source: `~/.codex/auth.json`
- Target: `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json`
- Profile key: `openai-codex:codex-cli`

### Onboarding

```bash
clawdbot onboard --auth-choice openai-codex
# Or if Codex CLI is already authenticated:
codex-cli  # Clawdbot detects and imports tokens
```

## Pattern 2: Direct Exec Tool

Call Codex CLI directly from Clawdbot's exec tool for coding tasks.

### Usage

```bash
# From Clawdbot chat
> Fix the TypeScript errors in src/components

# Clawdbot runs:
exec codex exec --full-auto --cd ~/projects/medreport "fix TypeScript errors in src/components"
```

### Best Practices

- Use `--full-auto` for trusted repos
- Use `--cd` to target specific project
- Use `--json` for parsing results
- Check exit code for success/failure

### Example AGENTS.md Instruction

```markdown
## Coding Tasks

When asked to fix code, refactor, or implement features:

1. Use the codex CLI for complex coding tasks
2. Command: `codex exec --full-auto --cd <project_path> "<task>"`
3. For large changes, use interactive mode: `codex --cd <path>`
4. Report the result back to the user
```

## Pattern 3: Coding Subagent

Spawn a dedicated subagent for coding that uses Codex or runs in a sandboxed environment.

### Config

```json5
{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        workspace: "~/clawd",
        model: { primary: "anthropic/claude-opus-4-5" }
      },
      {
        id: "coder", 
        workspace: "~/clawd-coder",
        model: { primary: "openai-codex/gpt-5.2" },
        sandbox: {
          mode: "all",
          scope: "agent",
          workspaceAccess: "rw"
        },
        tools: {
          allow: ["exec", "read", "write", "edit", "apply_patch", "process"],
          deny: ["browser", "canvas", "cron"]
        },
        subagents: {
          allowAgents: ["main"]  // Main can spawn coder
        }
      }
    ]
  },
  tools: {
    agentToAgent: {
      enabled: true,
      allow: ["main", "coder"]
    }
  }
}
```

### Usage

From main agent:
```
sessions_spawn task="Refactor the Dashboard component to use React Query" agentId="coder"
```

The coder subagent runs with Codex model, announces result back to main chat.

## Pattern 4: CLI Backend Fallback

Configure Codex CLI as a text-only fallback when API providers fail.

### Config

```json5
{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "codex",
          args: ["exec", "--full-auto"],
          output: "text"
        }
      }
    }
  }
}
```

### Notes

- CLI backends are text-only (no tool calls)
- Used as fallback when API auth fails or rate limits
- Sessions managed by Codex internally
- Good for emergencies but less capable

## Pattern 5: MCP Server Mode

Run Codex as an MCP server that Clawdbot can call.

### Setup

```bash
# Terminal 1: Start Codex MCP server
codex mcp-server

# Configure Clawdbot to connect
# In ~/.clawdbot/clawdbot.json or via skill
```

### Skill Integration

Create a skill that declares Codex MCP:

```markdown
---
name: codex-mcp
mcp:
  - name: codex
    command: codex
    args: ["mcp-server"]
---
```

## Model Handoff Patterns

### Opus → Codex Handoff

Use Opus for planning, Codex for implementation:

```json5
{
  agents: {
    list: [
      {
        id: "planner",
        model: { primary: "anthropic/claude-opus-4-5" },
        subagents: { allowAgents: ["coder"] }
      },
      {
        id: "coder",
        model: { primary: "openai-codex/gpt-5.2" }
      }
    ]
  }
}
```

Workflow:
1. User asks planner for architecture
2. Planner designs solution
3. Planner spawns coder subagent with implementation task
4. Coder implements and announces result
5. Planner reviews and responds to user

### Channel-Based Routing

Route WhatsApp to fast model, Telegram to Codex:

```json5
{
  bindings: [
    { agentId: "chat", match: { channel: "whatsapp" } },
    { agentId: "coder", match: { channel: "telegram" } }
  ]
}
```

## Cost Optimization

### Strategy 1: Subagent Model Override

```json5
{
  agents: {
    defaults: {
      subagents: {
        model: "openai/gpt-5-mini"  // Cheaper for subagents
      }
    }
  }
}
```

### Strategy 2: Task-Based Routing

- Quick questions → Sonnet/Mini
- Code review → Codex
- Deep analysis → Opus

### Strategy 3: Fallback Chain

```json5
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-5",
        fallbacks: [
          "openai-codex/gpt-5.2",
          "openai/gpt-5-mini"
        ]
      }
    }
  }
}
```

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Codex auth not syncing | Run `codex login` then restart gateway |
| Subagent not spawning | Check `subagents.allowAgents` includes caller |
| Exec timeout | Increase `tools.exec.timeoutSec` |
| Sandbox blocks codex | Add codex binary to allowed paths |
| Wrong workspace | Use `--cd` flag explicitly |

# Codex CLI Quick Reference

## Commands

| Command | Description |
|---------|-------------|
| `codex` | Launch interactive TUI |
| `codex exec <prompt>` | Non-interactive execution |
| `codex resume [--last]` | Continue previous session |
| `codex login` | Authenticate via OAuth |
| `codex logout` | Clear credentials |
| `codex apply <task_id>` | Apply Codex Cloud diff locally |
| `codex completion <shell>` | Generate shell completions |
| `codex mcp <subcommand>` | Manage MCP servers |
| `codex mcp-server` | Run Codex as MCP server |
| `codex cloud [exec]` | Manage Codex Cloud tasks |
| `codex sandbox` | Run commands in sandbox |

## Global Flags

| Flag | Values | Description |
|------|--------|-------------|
| `--model, -m` | string | Override model |
| `--image, -i` | path[,path...] | Attach images |
| `--cd, -C` | path | Set working directory |
| `--add-dir` | path | Add writable root |
| `--sandbox, -s` | read-only, workspace-write, danger-full-access | Sandbox policy |
| `--ask-for-approval, -a` | untrusted, on-failure, on-request, never | Approval mode |
| `--full-auto` | boolean | workspace-write + approve on failure |
| `--yolo` | boolean | No approvals or sandbox (dangerous) |
| `--profile, -p` | string | Config profile name |
| `--oss` | boolean | Use local Ollama |
| `--search` | boolean | Enable web search |
| `--json` | boolean | JSON output |

## codex exec Flags

| Flag | Description |
|------|-------------|
| `PROMPT` | Task instruction (or `-` for stdin) |
| `--skip-git-repo-check` | Allow non-Git directories |
| All global flags | Inherited |

## codex mcp Subcommands

| Subcommand | Description |
|------------|-------------|
| `list [--json]` | List configured MCP servers |
| `get <n> [--json]` | Show server config |
| `add <n> -- <cmd...>` | Add stdio server |
| `add <n> --url <url>` | Add HTTP server |
| `remove <n>` | Delete server |
| `login <n>` | OAuth for HTTP server |
| `logout <n>` | Clear OAuth |

## Slash Commands (TUI)

| Command | Description |
|---------|-------------|
| `/approvals` | Set approval mode |
| `/compact` | Summarize to free context |
| `/diff` | Show Git diff |
| `/exit`, `/quit` | Exit CLI |
| `/feedback` | Send logs to maintainers |
| `/init` | Generate AGENTS.md |
| `/logout` | Sign out |
| `/mcp` | List MCP tools |
| `/mention <path>` | Attach file |
| `/model` | Switch model |
| `/new` | Fresh conversation |
| `/review` | Code review |
| `/status` | Session info |
| `/undo` | Revert last turn |

## Approval Modes

| Mode | Read | Edit | Execute | Network |
|------|------|------|---------|---------|
| Auto | ✓ | ✓ (workspace) | ✓ (workspace) | Ask |
| Read Only | ✓ | Ask | Ask | Ask |
| Full Access | ✓ | ✓ | ✓ | ✓ |

## Sandbox Policies

| Policy | Description |
|--------|-------------|
| `read-only` | No writes allowed |
| `workspace-write` | Writes in workspace + /tmp |
| `danger-full-access` | No restrictions |

## Config File

Location: `~/.codex/config.toml`

```toml
[model]
default = "gpt-5-codex"

[features]
web_search_request = true
rmcp_client = true

[sandbox_workspace_write]
network_access = true

[mcp_servers]
# Defined via codex mcp add
```

## Custom Prompts

Location: `~/.codex/prompts/<n>.md`

```markdown
---
description: Short description
argument-hint: KEY=<value>
---

Prompt content with $KEY placeholders.
$1-$9 for positional args.
$ARGUMENTS for all args.
$$ for literal dollar sign.
```

## Session Files

Location: `~/.codex/sessions/`

## Auth Files

Location: `~/.codex/auth.json`

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Error / task failure |
| Non-zero | git apply conflict, auth failure, etc |