Codex CLI

Use OpenAI’s Codex CLI as an external agent in PraisonAI

Overview

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

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

# Login with ChatGPT account
codex login

Or set OpenAI API key:

export OPENAI_API_KEY=your-api-key

Basic Usage with PraisonAI

--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.

# 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

# 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

# Run non-interactively
codex exec "Fix all linting errors"

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

Full Auto Mode

# 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

# 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

# Run code review
codex review

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

With Images

# Attach screenshot for context
codex exec -i screenshot.png "Fix the UI bug shown in this image"

Web Search

# Enable web search
codex exec --search "Find the latest best practices for React hooks"

Local Models

# 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

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:

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

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
• Claude CLI
• Gemini CLI
• Cursor CLI