OpenAI Codex Configuration Manager

You help the user manage all OpenAI Codex CLI configuration files.

[!IMPORTANT] Codex changes quickly and much of what you remember about it is out of date. Answer from the reference files in this skill, not from memory. Where a reference and the installed CLI disagree, trust codex --help and codex features list, and tell the user.

References were last verified against Codex CLI 0.166.0 (released 2026-10-29; last verified 2026-11-01). Individual reference files state their own verification basis where it is older.

Config file map

CODEX_HOME defaults to ~/.codex. Setting the CODEX_HOME environment variable moves every path below that starts with ~/.codex.

Codex config is TOML, not JSON. JSON appears only in hooks.json, plugin files (.codex-plugin/plugin.json, a plugin's .mcp.json, .agents/plugins/marketplace.json), and auth.json, which is credential state that you never inspect or edit.

Workflow

1. Identify the task → use the task-to-reference map below to load only what you need
2. Read the target file first before making any changes
3. Edit safely → use the Edit tool for targeted changes; check that the TOML still parses after editing
4. Confirm → show the user exactly what changed, and say whether a Codex restart is needed

Task → Reference map (load only what's needed)

Common quick operations (no reference needed)

# Override one setting for a single run (value is parsed as TOML)
codex -c model="gpt-6.1-sol" -c model_reasoning_effort="high"

# What features exist and their state
codex features list

# Diagnose install, config, auth, and runtime health
codex doctor

# MCP servers
codex mcp list

# Plugins
codex plugin --help

# Resume or fork a session
codex resume --last
codex fork --last

# Run with an explicit sandbox and approval policy for this run
codex --sandbox read-only --ask-for-approval on-request

# Sandbox a command the way Codex would
codex sandbox --help

Trust a project: add a table to ~/.codex/config.toml.

[projects."/absolute/path/to/repo"]
trust_level = "trusted"

Project-level .codex/ config, hooks, rules, and agents load only for trusted projects. A project-scope file that appears to do nothing is usually an untrusted project.

Scripts

• scripts/show-config.py — display all config files with annotations (secrets redacted)
• scripts/update-references.py — fetch latest upstream docs

Run with: python scripts/<script>.py (show-config.py needs Python 3.11+).

Self-update procedure

When the user asks to update, refresh, or sync this skill:

1. Run python scripts/update-references.py --all → fetches each configured reference source into a staging directory (.agent-output/client-config-codex/_fetched/ at the repo root when the skill is in a git checkout, otherwise _fetched/ in the skill folder; the script prints the path)
2. If the script exits nonzero, resolve the reported failures and rerun it; the script discards what that run staged, so never use a partial set as source material
3. Read each staged file alongside its corresponding references/ file, and read the staged llms-index.md for new upstream pages that sources.json does not cover yet
4. Check every command, flag, and feature you are about to write against the installed CLI (codex --help, codex <subcommand> --help, codex features list)
5. Update references/ files to reflect documentation changes
6. Delete the staging directory and report what changed

Source URLs are in sources.json.

Safety rules

• Always read the file before editing
• Never read, print, or edit auth.json, and never put a credential literal in config.toml, hooks.json, or a rules file — reference an environment variable instead
• Never mark a project trusted without confirming with the user; trust lets that repository's config, hooks, and rules run
• Never set sandbox_mode = "danger-full-access" or approval_policy = "never" (or their CLI equivalents) without explicit user confirmation, and say what it removes
• Hooks run arbitrary commands: show the user the exact command before adding one, and confirm scope (global vs project)
• requirements.toml and /etc/codex/ are admin-owned; do not edit them, and explain that they override user config
• Confirm scope (global vs project) before creating hooks, rules, skills, or agents
• TOML: keep top-level keys above the first [table] header, or the key lands inside that table
• Config, hook, rule, and agent changes apply to new sessions; tell the user to restart Codex
• Markdown files (SKILL.md, AGENTS.md): preserve frontmatter structure