codex-config

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

1. $CWD/.codex/skills/ - Current directory
2. $CWD/../.codex/skills/ - Parent directory
3. $REPO_ROOT/.codex/skills/ - Repository root
4. ~/.codex/skills/ - User-level
5. /etc/codex/skills/ - System/admin level
6. 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 files

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"

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=all

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

Quick 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