OpenAI Codex CLI: Exhaustive Reference

This document provides a comprehensive reference for OpenAI's Codex CLI, covering configuration, sandbox modes, approval policies, notification hooks, execpolicy, MCP integration, and comparison with other AI coding assistants.

Last Updated: January 2026 Codex CLI Versions Covered: v0.65 through v0.80.x

---

Table of Contents

1. Overview
2. Installation and Authentication
3. Configuration
4. Sandbox Modes
5. Approval Policies
6. Notification Hooks
7. Execpolicy (Command Filtering)
8. Tools
9. MCP Server Integration
10. Skills System
11. Command Line Reference
12. Shell Environment Policy
13. Feature Flags
14. Version History and Changelog
15. Known Issues and Limitations
16. Comparison with Claude Code, Cursor, and Gemini CLI
17. Sources and References

---

Overview

Codex CLI is OpenAI's locally-run coding agent that operates from your terminal. It can read, change, and run code on your machine within the selected directory.

Key Characteristics:

• Open source, built in Rust for speed and efficiency
• Available on macOS, Linux, and Windows (experimental)
• Included with ChatGPT Plus, Pro, Business, Edu, and Enterprise plans
• Supports MCP (Model Context Protocol) for third-party tool integration
• No full hook system - uses notification callbacks and policy controls instead

Repository: github.com/openai/codex License: Apache-2.0 Stars: 56k+ (as of January 2026)

Sources:

• Codex CLI Documentation
• GitHub Repository

---

Installation and Authentication

Installation Methods

Platform Support

Authentication Options

1. ChatGPT Account (recommended): Integrates with Plus, Pro, Team, Edu, or Enterprise plans
2. API Key: Requires OPENAI_API_KEY environment variable

codex login          # Interactive login
codex logout         # Remove credentials

Configuration Options

---

Configuration

File Locations

Configuration Format

Codex uses TOML format (not JSON like Claude Code):

# ~/.codex/config.toml

model = "gpt-5.2-codex"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
model_reasoning_effort = "high"

[shell_environment_policy]
include_only = ["PATH", "HOME", "USER"]

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "..." }

Profiles

Named configuration sets for different workflows:

[profiles.safe]
approval_policy = "untrusted"
sandbox_mode = "read-only"

[profiles.yolo]
approval_policy = "never"
sandbox_mode = "danger-full-access"

Usage: codex --profile safe

Admin-Enforced Settings (requirements.toml)

Administrators can constrain settings via requirements.toml:

allowed_approval_policies = ["untrusted", "on-failure"]
allowed_sandbox_modes = ["read-only", "workspace-write"]

Source: Advanced Configuration

---

Sandbox Modes

Codex provides three sandbox modes controlling filesystem and network access:

Setting Sandbox Mode

# CLI flag
codex --sandbox workspace-write

# Config file
sandbox_mode = "workspace-write"

workspace-write Options

Fine-tune workspace-write behavior:

Platform Implementation

Sandbox CLI Command

Test sandbox behavior independently:

codex sandbox "ls -la"

---

Approval Policies

Controls when Codex pauses for human approval before executing commands:

Setting Approval Policy

# CLI flag
codex --ask-for-approval on-request

# Shortcut for on-request + workspace-write
codex --full-auto

# Config file
approval_policy = "on-request"

Dangerous Mode

Bypass all safety mechanisms (use with extreme caution):

codex --dangerously-bypass-approvals-and-sandbox
# or
codex --yolo

Warning: Only use in isolated environments (VMs, containers).

---

Notification Hooks

Codex has a limited hook system compared to Claude Code. Currently, only notification callbacks are supported.

Configuration

# ~/.codex/config.toml
notify = ["bash", "-lc", "afplay /System/Library/Sounds/Blow.aiff"]

Supported Events

TUI Notifications

[tui]
notifications = true                    # All notifications
notifications = ["agent-turn-complete"] # Filtered

Notification Payload

The notify command receives a JSON payload via stdin:

{
  "event": "agent-turn-complete",
  "session_id": "abc123",
  "timestamp": "2026-01-14T10:30:00Z"
}

Hook Feature Request

The community has requested a full hook system similar to Claude Code. See Discussion #2150.

Requested features:

• Pre/post tool execution hooks
• Exit code handling
• Ability to block/modify operations
• Additional event types

Status: Under consideration; maintainers direct users to upvote Issue #2109.

---

Execpolicy (Command Filtering)

Execpolicy is an experimental feature for filtering shell commands before execution.

Enabling Execpolicy

[features]
exec_policy = true  # Default: on

CLI Command

Test whether a command would be allowed:

codex execpolicy "rm -rf /"

TUI Whitelist

When a command is approved in the TUI, it can be added to a whitelist for future auto-approval (v0.66.0+).

Note: Execpolicy documentation is sparse. The feature is experimental and APIs may change.

---

Tools

Codex provides built-in tools for file operations, shell execution, and web access.

Core Tools

Shell Tool Behavior

Environment variable CODEX_CLI=1 is set in subprocesses.

Tool Configuration

[features]
shell_tool = true
web_search_request = true
apply_patch_freeform = false  # Experimental

MCP Tools

MCP tools follow the naming pattern: mcp__<server>__<tool>

Example: mcp__github__create_issue

---

MCP Server Integration

Codex supports Model Context Protocol (MCP) for third-party tool integration.

Configuration

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "..." }

[mcp_servers.remote]
url = "https://mcp.example.com"
bearer_token_env_var = "MCP_TOKEN"

STDIO Server Options

HTTP Server Options

Common Options

MCP CLI Commands

codex mcp add <server-name>    # Add server
codex mcp list                 # List servers
codex mcp remove <server-name> # Remove server

Recommended MCP Servers

• Context7: Developer documentation
• Figma: Design access
• Playwright: Browser automation
• GitHub: Repository management
• Sentry: Error logs

Source: MCP Documentation

---

Skills System

Skills extend Codex with task-specific capabilities, following the Agent Skills Standard.

Skill Structure

skill-name/
├── SKILL.md          # Required: Instructions and metadata
├── scripts/          # Optional: Executable code
├── references/       # Optional: Documentation
└── assets/           # Optional: Templates

SKILL.md Format

---
name: skill-name
description: Description for skill selection
---

Skill instructions here...

Skill Locations (Priority Order)

Invoking Skills

1. Explicit: /skills command or $skill-name mention
2. Implicit: Codex auto-selects based on task match

Built-in Skills

Source: Skills Documentation

---

Command Line Reference

Main Commands

Global Flags

codex exec Flags

Slash Commands (TUI)

Keyboard Shortcuts (TUI)

Source: Command Line Reference

---

Shell Environment Policy

Control which environment variables are passed to subprocesses:

[