| name | codex-config |
| description | Configure Codex CLI/app/IDE settings. Use when editing Codex config.toml, project .codex layers, permissions, sandbox/approvals, MCP servers, hooks, plugins, skills, TUI settings, models, shell environment policy, or Codex troubleshooting defaults. |
Codex Config
Change Codex behavior through the narrowest durable surface. Treat Codex config as layered, security-sensitive TOML; verify active syntax when model, permissions, MCP, hook, or plugin keys matter.
Chezmoi Sources
Edit chezmoi source, not deployed targets:
| Purpose | Source |
|---|
| User config | symsources/codex/config.toml |
| Hooks | dot_codex/hooks.json, dot_codex/executable_herdr-agent-state.sh |
| Guidance | .chezmoitemplates/agents/AGENTS.md, .chezmoitemplates/agents/rules/*.md |
| Shared skills | dot_agents/exact_skills/<skill>/ |
symsources/codex/config.toml is symlinked because Codex writes trust, hook state, plugin, marketplace, and skill-enable state. Do not prune generated tables such as [projects], [hooks.state], [marketplaces], [plugins], or [[skills.config]] unless cleanup is the task.
Layers
Use the smallest surface that matches the request:
| Need | Surface |
|---|
| One run | CLI flags like --model or -c key=value |
| Repo-specific behavior | Trusted project .codex/config.toml |
| Named local mode | ~/.codex/<profile>.config.toml with --profile |
| Personal defaults | symsources/codex/config.toml |
| Organization policy | Managed config or requirements.toml |
| Behavioral instructions | AGENTS.md, rules, or a skill |
| External tools/data | MCP server or plugin config |
| Lifecycle enforcement | hooks.json or inline [hooks] |
Precedence is CLI overrides, trusted project config from root to cwd, selected profile file, user config, system config, then built-in defaults. Project .codex/ layers only load after the project is trusted.
Keep provider auth, credential redirection, notifications, telemetry, profiles, and machine-local commands out of project config; Codex ignores several of those keys there.
Workflow
- Identify the scope: one-off, project, profile, user, plugin, or managed.
- Read current source plus adjacent hook, plugin, or skill files.
- Refresh official docs before changing active syntax or behavior. Prefer
openai-docs, then targeted Codex docs.
- Edit TOML structurally; preserve section order where practical.
- Validate parse and deployment shape:
python3 -c 'import sys,tomllib; tomllib.load(open(sys.argv[1], "rb"))' symsources/codex/config.toml
chezmoi --dry-run --no-pager diff
Config Notes
- Prefer documented keys over remembered names.
- Use beta permission profiles or legacy
sandbox_mode plus [sandbox_workspace_write], never both in one loaded config.
- Load Permission Profiles when choosing or changing Codex sandbox and approval behavior.
- For hooks, use
dot_codex/hooks.json or inline [hooks]; prefer one representation per layer. Codex requires trust review for changed command hooks.
- Use
AGENTS.md, rules, or skills for behavior instructions; use config for runtime settings.
Patterns
Use secret indirection, not secret values:
[mcp_servers.docs]
command = "pnpm"
args = ["dlx", "@example/docs-mcp"]
env_vars = ["DOCS_TOKEN"]
enabled = true
default_tools_approval_mode = "prompt"
Keep project defaults portable:
model_reasoning_effort = "high"
approval_policy = "on-request"
default_permissions = "project-edit"
Guardrails
- Do not edit
~/.codex/auth.json, access tokens, API keys, keychains, or copied target files.
- Do not weaken sandboxing, approval prompts, filesystem permissions, network access, hook trust, or secret filtering without explicit user request.
- Do not move caches, logs, or state directories to bypass sandbox failures.
- Do not encode behavior rules as config keys; use
AGENTS.md, rules, or skills.
- Do not add global package-manager commands or MCP servers from unknown maintainers without reading their source, docs, and install surface.
- Do not assume deprecated model, feature, hook, or MCP names still work.
Official References
- Codex manual:
https://developers.openai.com/codex/codex-manual.md
- Config basics:
https://developers.openai.com/codex/config-basic
- Advanced config:
https://developers.openai.com/codex/config-advanced
- MCP:
https://developers.openai.com/codex/mcp
- Hooks:
https://developers.openai.com/codex/hooks
- Permissions:
https://developers.openai.com/codex/permissions
