codex-configuration
Manages OpenAI Codex CLI configuration including config.toml settings, MCP servers, model profiles, sandbox modes, approval policies, and skill paths. Use when configuring Codex CLI, setting up model profiles, managing MCP server integrations, troubleshooting Codex configuration issues, or optimizing Codex for different workflows.
When & Why to Use This Skill
This Claude skill provides comprehensive management for OpenAI Codex CLI configurations, allowing users to fine-tune model profiles, MCP server integrations, and security sandbox policies. It simplifies the setup of agentic coding environments by centralizing control over config.toml settings, skill path hierarchies, and runtime overrides for an optimized developer workflow.
Use Cases
- Environment Setup: Quickly configuring model profiles to switch between high-reasoning tasks and fast, low-cost code generation.
- Security Management: Defining sandbox modes and approval policies to balance execution power with system safety.
- Tool Integration: Managing MCP (Model Context Protocol) servers by configuring commands, arguments, and environment variables for external tool connectivity.
- Workflow Optimization: Customizing skill search paths and CLI overrides to adapt the Codex agent to specific project structures or repository requirements.
- Troubleshooting: Validating TOML syntax and verifying configuration hierarchy to resolve issues with missing skills or failing server connections.
| name | codex-configuration |
|---|---|
| description | This skill should be used when configuring Codex CLI, setting up profiles, or when "config.toml", "sandbox mode", "Codex config", or "approval policy" are mentioned. |
| version | 1.0.0 |
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 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