> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex CLI

> Use OpenAI's Codex CLI as an external agent in PraisonAI

## Overview

<img src="https://mintcdn.com/praisonai/SX0Y8_-DRBjzOTnt/docs/cli/codex-cli-codex-cli-for-code-improvement.gif?s=6ef1f5765c95fb6de4c5f6f011d884b4" alt="Codex CLI for Code Improvement" width="1497" height="1104" data-path="docs/cli/codex-cli-codex-cli-for-code-improvement.gif" />

Codex CLI is OpenAI's AI-powered coding assistant that can run commands, edit files, and perform complex coding tasks. PraisonAI integrates with Codex CLI to use it as an external agent.

## Installation

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Install via npm
npm install -g @openai/codex

# Or build from source
git clone https://github.com/openai/codex
cd codex/codex-cli
pnpm install && pnpm build
```

## Authentication

Codex uses ChatGPT authentication:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Login with ChatGPT account
codex login
```

Or set OpenAI API key:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
export OPENAI_API_KEY=your-api-key
```

## Basic Usage with PraisonAI

<Note>
  `--external-agent codex` invokes Codex CLI via a manager Agent by default. The manager reasons and calls Codex as a subagent tool. Use `--external-agent-direct` for pass-through proxy behavior.
</Note>

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Manager delegation (default — manager reasons + calls codex as subagent tool)
praisonai "Fix the bug in auth.py" --external-agent codex

# Direct proxy (escape hatch — no manager, passes prompt straight to codex)
praisonai "Fix the bug in auth.py" --external-agent codex --external-agent-direct

# With verbose output
praisonai "Refactor this module" --external-agent codex --verbose
```

## CLI Options Reference

### Core Options

| Option                | Description                               |
| --------------------- | ----------------------------------------- |
| `[PROMPT]`            | Optional user prompt to start the session |
| `-m, --model <MODEL>` | Model the agent should use                |
| `-h, --help`          | Print help                                |
| `-V, --version`       | Print version                             |

### Configuration

| Option                     | Description                                 |
| -------------------------- | ------------------------------------------- |
| `-c, --config <key=value>` | Override config from `~/.codex/config.toml` |
| `-p, --profile <PROFILE>`  | Configuration profile from config.toml      |
| `--enable <FEATURE>`       | Enable a feature (repeatable)               |
| `--disable <FEATURE>`      | Disable a feature (repeatable)              |

### Sandbox Modes

| Option                 | Description                       |
| ---------------------- | --------------------------------- |
| `-s, --sandbox <MODE>` | Sandbox policy for shell commands |

**Sandbox Mode Values:**

* `read-only` - Read-only access
* `workspace-write` - Write access to workspace
* `danger-full-access` - Full system access (dangerous)

### Approval Policies

| Option                                       | Description                            |
| -------------------------------------------- | -------------------------------------- |
| `-a, --ask-for-approval <POLICY>`            | When to require human approval         |
| `--full-auto`                                | Low-friction automatic execution       |
| `--dangerously-bypass-approvals-and-sandbox` | Skip all prompts (extremely dangerous) |

**Approval Policy Values:**

* `untrusted` - Only run trusted commands without approval
* `on-failure` - Ask approval only on command failure
* `on-request` - Model decides when to ask
* `never` - Never ask for approval

### Working Directory

| Option            | Description                     |
| ----------------- | ------------------------------- |
| `-C, --cd <DIR>`  | Working directory for the agent |
| `--add-dir <DIR>` | Additional writable directories |

### Input Options

| Option               | Description                          |
| -------------------- | ------------------------------------ |
| `-i, --image <FILE>` | Image(s) to attach to initial prompt |
| `--search`           | Enable web search tool               |

### Local Models

| Option                        | Description                                     |
| ----------------------------- | ----------------------------------------------- |
| `--oss`                       | Use local open source model provider            |
| `--local-provider <PROVIDER>` | Specify local provider (`lmstudio` or `ollama`) |

## Commands

| Command            | Description                              |
| ------------------ | ---------------------------------------- |
| `codex exec`       | Run Codex non-interactively              |
| `codex review`     | Run code review non-interactively        |
| `codex login`      | Manage login                             |
| `codex logout`     | Remove authentication credentials        |
| `codex mcp`        | Run as MCP server and manage MCP servers |
| `codex mcp-server` | Run the Codex MCP server (stdio)         |
| `codex completion` | Generate shell completion scripts        |
| `codex sandbox`    | Run commands within sandbox              |
| `codex apply`      | Apply latest diff as `git apply`         |
| `codex resume`     | Resume previous interactive session      |
| `codex cloud`      | Browse tasks from Codex Cloud            |
| `codex features`   | Inspect feature flags                    |

## Examples

### Basic Query

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Simple question
praisonai "What files are in this directory?" --external-agent codex

# Code analysis
praisonai "Analyze the code quality" --external-agent codex
```

### Non-Interactive Execution

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Run non-interactively
codex exec "Fix all linting errors"

# With specific working directory
codex exec -C /path/to/project "Update dependencies"
```

### Full Auto Mode

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Automatic execution with workspace write access
codex exec --full-auto "Refactor the authentication module"

# Equivalent to:
codex exec -a on-request --sandbox workspace-write "Refactor the authentication module"
```

### Sandbox Modes

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Read-only mode (safest)
codex exec -s read-only "Analyze this codebase"

# Workspace write mode
codex exec -s workspace-write "Fix all bugs"

# Full access (dangerous)
codex exec -s danger-full-access "Install dependencies and run tests"
```

### Code Review

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Run code review
codex review

# Review specific changes
codex review --diff HEAD~5
```

### With Images

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Attach screenshot for context
codex exec -i screenshot.png "Fix the UI bug shown in this image"
```

### Web Search

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Enable web search
codex exec --search "Find the latest best practices for React hooks"
```

### Local Models

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Use local LM Studio
codex --oss --local-provider lmstudio "Explain this code"

# Use local Ollama
codex --oss --local-provider ollama "Refactor this function"
```

## Python Integration

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.integrations import CodexCLIIntegration

# Create integration
codex = CodexCLIIntegration(
    workspace="/path/to/project",
    full_auto=True,
    sandbox="workspace-write"
)

# Execute a task
result = await codex.execute("Fix the authentication bug")
print(result)

# Execute with JSON output
codex_json = CodexCLIIntegration(json_output=True)
result = await codex_json.execute("List all functions")
print(result)

# Stream output
async for event in codex.stream("Add error handling"):
    print(event)
```

## Configuration File

Codex uses `~/.codex/config.toml` for configuration:

```toml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Default model
model = "gpt-5.2-codex"

# Default sandbox mode
sandbox_permissions = ["disk-full-read-access"]

# Shell environment policy
[shell_environment_policy]
inherit = "all"
```

Override via CLI:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
codex -c model="o3" "Complex reasoning task"
codex -c 'sandbox_permissions=["disk-full-read-access"]' "Read all files"
```

## Environment Variables

| Variable         | Description    |
| ---------------- | -------------- |
| `OPENAI_API_KEY` | OpenAI API key |

## Output Format

Codex provides detailed output including:

```
OpenAI Codex v0.75.0 (research preview)
--------
workdir: /path/to/project
model: gpt-5.2-codex
provider: openai
approval: never
sandbox: read-only
--------
user
Your prompt here

thinking
**Analysis of the request**

codex
Response from Codex

tokens used
209
```

## Related

* [External Agents Overview](/docs/cli/cli)
* [Claude CLI](/docs/cli/claude-cli)
* [Gemini CLI](/docs/cli/gemini-cli)
* [Cursor CLI](/docs/cli/cursor-cli)