Codex Configuration Management

Manages configuration files for OpenAI Codex CLI, including model settings, sandbox policies, MCP servers, and profiles.

Quick Start

Configuration File Location

Primary Config:

~/.codex/config.toml — User-level configuration

Skills Paths (precedence, highest first):

$CWD/.codex/skills/ — Current directory
$CWD/../.codex/skills/ — Parent directory
$REPO_ROOT/.codex/skills/ — Repository root
~/.codex/skills/ — User-level
/etc/codex/skills/ — System/admin level
Built-in skills — Bundled with Codex

CLI Config Override

Override any config value at runtime:

codex -c model="o3"
codex -c 'sandbox_permissions=["disk-full-read-access"]'
codex -c shell_environment_policy.inherit=all

Config Structure

Basic config.toml

# Model settings
model = "gpt-5.2-codex"
model_verbosity = "medium"  # high | medium | low
model_reasoning_effort = "high"  # low | high | xhigh

# Permissions
approval_policy = "on-failure"  # untrusted | on-failure | on-request | never
sandbox_mode = "workspace-write"  # read-only | workspace-write | danger-full-access
exec_timeout_ms = 300000  # 5 minutes

# Misc
file_opener = "cursor"  # Editor for opening files

Model Configuration

model = "gpt-5.2-codex"
model_verbosity = "medium"
model_reasoning_summary = "auto"  # auto | concise | detailed
model_reasoning_summary_format = "experimental"
model_supports_reasoning_summaries = true
model_reasoning_effort = "high"
tool_output_token_limit = 25000

Profiles

Define named profiles for different workflows:

[profiles.max]
model = "gpt-5.1-codex-max"
model_verbosity = "high"
model_reasoning_effort = "xhigh"

[profiles.fast]
model = "gpt-5.1-codex-mini"
model_verbosity = "low"
model_reasoning_effort = "low"

[profiles.normal]
model = "gpt-5.2"
model_verbosity = "medium"
model_reasoning_effort = "high"

Usage:

codex -p max "complex refactoring task"
codex -p fast "quick fix"

Sandbox Modes

| Mode | Description | Use Case | |------|-------------|----------| | read-only | No write access | Safe exploration | | workspace-write | Write to workspace only | Normal development | | danger-full-access | Full system access | Trusted operations |

codex -s read-only "analyze this codebase"
codex -s workspace-write "implement feature"
codex --dangerously-bypass-approvals-and-sandbox  # EXTREME CAUTION

Approval Policies

| Policy | Behavior | |--------|----------| | untrusted | Only trusted commands (ls, cat, sed) run without approval | | on-failure | All commands run; approval only if command fails | | on-request | Model decides when to ask | | never | Never ask for approval |

codex -a untrusted "careful task"
codex -a never "automated pipeline"
codex --full-auto  # Alias for -a on-request --sandbox workspace-write

Project Trust Levels

[projects]
"/path/to/trusted/project" = { trust_level = "trusted" }
"/path/to/another" = { trust_level = "trusted" }

Shell Environment Policy

[shell_environment_policy]
set = { MY_VAR = "value" }  # Force-set environment vars
inherit = "all"  # all | core | none
ignore_default_excludes = false
include_only = []  # Whitelist patterns

Features

Toggle experimental features:

[features]
unified_exec = true
shell_snapshot = true
apply_patch_freeform = true
exec_policy = true
remote_compaction = true
skills = true

CLI toggle:

codex --enable skills
codex --disable remote_compaction

TUI Settings

[tui]
notifications = ["agent-turn-complete", "approval-requested"]

MCP Server Configuration

Adding MCP Servers

[mcp_servers.server-name]
command = "npx"
args = ["-y", "@package/mcp-server"]
enabled = true
tool_timeout_sec = 60.0

[mcp_servers.server-name.env]
API_KEY = "your-key"

Common MCP Servers

Context7 (documentation):

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_KEY"]

Firecrawl (web scraping):

[mcp_servers.firecrawl]
command = "npx"
args = ["-y", "firecrawl-mcp"]

[mcp_servers.firecrawl.env]
FIRECRAWL_API_KEY = "YOUR_KEY"

Graphite (stacked PRs):

[mcp_servers.graphite]
command = "gt"
args = ["mcp"]

Linear (project management):

[mcp_servers.linear]
command = "npx"
args = ["-y", "mcp-remote@latest", "https://mcp.linear.app/sse"]

Disabling MCP Servers

[mcp_servers.disabled-server]
command = "some-command"
args = []
enabled = false

Skills Configuration

Skills Paths

Codex loads skills from multiple locations with precedence:

CWD: .codex/skills/ — Project-specific
Parent: ../.codex/skills/ — Shared in parent folder
Repo Root: $REPO_ROOT/.codex/skills/ — Repository-wide
User: ~/.codex/skills/ — Personal skills
Admin: /etc/codex/skills/ — System-wide
Built-in: Bundled with Codex ($plan, $skill-creator)

Invoking Skills

# Explicit invocation
codex "$plan implement authentication"
codex "$skill-creator new skill for testing"

# Implicit (Codex decides based on context)
codex "plan out the implementation"

Built-in Skills

$plan — Research and create implementation plans
$skill-creator — Bootstrap new skills
$skill-installer — Download skills from GitHub

Convenience Flags

| Flag | Equivalent | |------|------------| | --full-auto | -a on-request --sandbox workspace-write | | --oss | -c model_provider=oss (local LM Studio/Ollama) | | --search | Enable web search tool |

codex --full-auto "implement feature"
codex --oss --local-provider ollama "explain this code"
codex --search "find latest React patterns"

Working Directory

codex -C /path/to/project "work here"
codex --add-dir /additional/writable/path "access multiple dirs"

Validation

# Check TOML syntax
cat ~/.codex/config.toml | toml-lint

# Test config override
codex -c model="test" --help

# Verify MCP server
codex mcp list

Troubleshooting

Common Issues

Config not loading:

Verify ~/.codex/config.toml exists
Check TOML syntax
Use -c to override and test

MCP server not connecting:

Check command path is correct
Verify API keys in env section
Check enabled = true
Review tool_timeout_sec

Skills not found:

Verify path hierarchy
Check skill directory structure
Ensure SKILL.md exists in skill folder

Sandbox too restrictive:

Use -s workspace-write for normal development
Check project trust level
Consider --add-dir for additional paths

Debug Commands

# Check current features
codex features

# Resume previous session
codex resume
codex resume --last

# Run in sandbox debug mode
codex sandbox <command>

Best Practices

Security

Use workspace-write sandbox for most work
Set approval_policy = "on-failure" as baseline
Only use danger-full-access when necessary
Review project trust levels periodically

Performance

Use profiles for different task types
Set appropriate exec_timeout_ms
Configure tool_output_token_limit for large outputs

Organization

Keep user-level skills in ~/.codex/skills/
Use project-level skills for team sharing
Document custom MCP server configurations