Skip to content

codex-config.md

Latest commit

 

History

History
109 lines (79 loc) · 3.17 KB

codex-config.md

File metadata and controls

109 lines (79 loc) · 3.17 KB

Best Practice: Config

A comprehensive guide to Codex CLI's TOML-based configuration system — covering config hierarchy, profiles, sandbox modes, and approval policies.

← Back to Codex CLI Best Practice Codex

Settings Hierarchy

Settings apply in order of precedence (highest to lowest):

Priority Location Scope Purpose
1 CLI flags / -c key=value Invocation One-off overrides for a single run
2 .codex/config.toml Project Team-shared defaults, profiles, MCP, agents
3 ~/.codex/config.toml Global Personal defaults across projects

Core Configuration

# .codex/config.toml
model = "o4-mini"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

Profiles

Named presets under [profiles.<name>] — switch with codex --profile <name>:

[profiles.conservative]
sandbox_mode = "read-only"
approval_policy = "untrusted"

[profiles.development]
sandbox_mode = "workspace-write"
approval_policy = "on-request"

[profiles.ci]
model = "o4-mini"
sandbox_mode = "read-only"
approval_policy = "never"

[profiles.trusted]
sandbox_mode = "danger-full-access"
approval_policy = "never"

Set a default profile with profile = "conservative" at the top level.

Sandbox Modes

Mode File Access Network Best for
read-only Read-only project access Blocked Reviews, audits, CI analysis
workspace-write Read/write inside the workspace Blocked Local development and doc/code edits
danger-full-access Unrestricted filesystem access Allowed Fully trusted automation that needs network or installs

Approval Policies

Policy Behavior Best for
untrusted Auto-runs only trusted read-style commands; asks for the rest New repos, audits, reviews
on-request Model decides when it should ask Everyday development
never Never asks; failures come straight back to the model Non-interactive runs and tightly controlled automation

Override

Use AGENTS.override.md for personal instruction overrides — loaded before AGENTS.md, not committed to git.

MCP Servers

Declare shared integrations in the same config file:

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "$GITHUB_TOKEN" }

Agents

Register agents under [agents.<name>] and optionally point them at dedicated role files:

[agents.backend-dev]
description = "Handles backend implementation tasks"
config_file = "agents/backend-dev.toml"

One-Off Overrides

codex -c model=\"o3\" -c approval_policy=\"never\" exec "summarize this diff"

Anti-Patterns

  • Using danger-full-access for ordinary editing tasks
  • Treating never as a general-purpose local default
  • Using danger-full-access and never together without a real containment boundary
  • Hardcoding secrets instead of using $ENV_VAR expansion
  • Mixing unrelated concerns into one profile instead of creating focused profiles
⚡