Codex Configuration Management
Manages configuration files for OpenAI Codex CLI, including model settings, sandbox policies, MCP servers, and profiles.
Configuration Location
Primary Config: ~/.codex/config.toml
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
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 filesProfiles
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"Usage:
codex -p max "complex refactoring task"
codex -p fast "quick fix"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"Skills
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
CLI 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=allConvenience 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 -C /path/to/project "work in different dir"
codex --add-dir /additional/path "access multiple dirs"Quick Validation
# Check TOML syntax
cat ~/.codex/config.toml | toml-lint
# Test config override
codex -c model="test" --help
# Verify MCP servers
codex mcp listQuick Troubleshooting
Config not loading: Verify ~/.codex/config.toml exists, check TOML syntax
MCP server not connecting: Check command path, verify API keys, check enabled = true
Skills not found: Verify path hierarchy, check SKILL.md exists in skill folder
Sandbox too restrictive: Use -s workspace-write, check project trust level
References
Detailed documentation for specific scenarios:
- MCP Servers - Server configuration examples (Context7, Firecrawl, Graphite, Linear)
- Troubleshooting - Common issues, debug commands, validation
- Security - Sandbox modes, approval policies, trust levels, best practices