Config System & Profiles

~14 min · codex, config, toml, profiles

Level 0🌱 Novice

0 XP0/70 lessons0/11 achievements

0/120 XP to next level120 XP to go0% complete

Layered TOML, with profiles for switchable defaults

Codex's config is layered: ~/.codex/config.toml (user), .codex/config.toml in repo (project, only if trusted), /etc/codex/config.toml (system, always trusted). Precedence: CLI flags + -c key=value overrides → profile (--profile NAME) → project file → user file → system file → built-in defaults.

Profiles are named groups of settings within config.toml. --profile secure swaps in tighter defaults; --profile fast swaps in looser ones for trusted automation. Same config file, multiple operating modes.

Code

Comprehensive ~/.codex/config.toml·toml

# Core
model           = "gpt-5-codex"
provider        = "openai"        # "openai" | "azure" | custom

# Approval + sandbox
approval_policy = "on-request"
sandbox_mode    = "workspace-write"

# Project doc discovery
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes          = 65536

# History
[history]
persistence = "save-all"

# Logging
log_dir = "~/.codex/logs"

# Workspace-write specifics
[sandbox_workspace_write]
network_access  = false
writable_roots  = []

# Profiles — named overlays
[profiles.secure]
approval_policy = "untrusted"
sandbox_mode    = "read-only"

[profiles.fast]
approval_policy = "never"
sandbox_mode    = "workspace-write"
[profiles.fast.sandbox_workspace_write]
network_access = true

Use a profile·bash

# Cautious mode for first-time-on-this-repo work
codex --profile secure "explain the auth flow"

# Looser mode for batch automation
codex --profile fast --sandbox danger-full-access \
      "fix all eslint errors"

# One-off override without changing config file
codex -c sandbox_workspace_write.network_access=true \
      "fetch the API schema from docs.example.com"

External links

Codex config.toml reference

Exercise

Define three profiles in your config.toml: secure, default, fast. Use each on a real task. Note where each profile felt right and where it got in the way.

Progress

Progress is local-only — sign in to sync across devices.

← PreviousAGENTS.md — Project Memory for Codex Next →Slash Commands & Custom Commands

Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)

No comments yet — be the first.