Agent skill

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.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/codex-configuration

SKILL.md

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

  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

CLI Config Override

Override any config value at runtime:

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

Config Structure

Basic config.toml

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

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

toml
[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:

bash
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
bash
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
bash
codex -a untrusted "careful task"
codex -a never "automated pipeline"
codex --full-auto  # Alias for -a on-request --sandbox workspace-write

Project Trust Levels

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

Shell Environment Policy

toml
[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:

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

CLI toggle:

bash
codex --enable skills
codex --disable remote_compaction

TUI Settings

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

MCP Server Configuration

Adding MCP Servers

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

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

Firecrawl (web scraping):

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

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

Graphite (stacked PRs):

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

Linear (project management):

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

Disabling MCP Servers

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

Skills Configuration

Skills Paths

Codex loads skills from multiple locations with precedence:

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

Invoking Skills

bash
# 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
bash
codex --full-auto "implement feature"
codex --oss --local-provider ollama "explain this code"
codex --search "find latest React patterns"

Working Directory

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

Validation

bash
# 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

bash
# 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

Didn't find tool you were looking for?

Be as detailed as possible for better results