Configure Codex with config.toml

Codex stores user-level configuration at ~/.codex/config.toml. To scope settings to a project or subfolder, add a .codex/config.toml file in your repo. The Codex CLI and IDE extension share the same configuration layers. For security, Codex loads project .codex/ layers only when you trust the project.

• 1. CLI flags and --config (-c) overrides (highest precedence)
• 2. Project .codex/config.toml files, ordered from the project root down to your current directory. The closest file wins, and only trusted projects count.
• 3. Profile files selected with --profile profile-name (~/.codex/profile-name.config.toml)
• 4. User config: ~/.codex/config.toml
• 5. Cloud-managed config.toml defaults, when your signed-in workspace delivers them
• 6. System config, if present: /etc/codex/config.toml on Unix
• 7. Built-in defaults

A project-level .codex/config.toml cannot change provider, auth, notification, profile selection, or telemetry keys. Codex ignores model_provider, model_providers, openai_base_url, notify, profile, profiles, and otel when they appear there, so put those in your user-level config instead.

model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

• model: the default model for the CLI and IDE. It must be a model your signed-in account or workspace can use.
• model_reasoning_effort: a level the selected model supports, such as low, medium, high, xhigh, max, or ultra. Which levels are available depends on the model and client.
• approval_policy: on-request for interactive runs or never for non-interactive runs. You can also use a granular table. The untrusted value is no longer supported, and on-failure is deprecated.
• sandbox_mode: read-only, workspace-write, or danger-full-access.

For a one-off change, override any key from the CLI with -c or --config, for example codex -c log_dir=./.codex-log.

A profile is now its own TOML file next to config.toml, named profile-name.config.toml. When you pass --profile profile-name, Codex loads ~/.codex/config.toml and then applies the profile file on top. Put top-level keys in the profile file, not a [profiles.profile-name] table. In Codex 0.134.0 and later, --profile no longer reads [profiles.*] tables from config.toml, and the top-level profile selector is gone. Move any old profile settings into their own files.

model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"

codex --profile deep-review
codex exec --profile deep-review "review this change"

Add each MCP server as an [mcp_servers.<server-name>] table. A local stdio server needs a command, and can also take args, env, env_vars, and cwd. A streamable HTTP server needs a url, and can also take bearer_token_env_var, http_headers, and env_http_headers. The ChatGPT desktop app, Codex CLI, and IDE extension all share this configuration.

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

[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp add SERVER_NAME --env VAR1=VALUE1 -- SERVER_COMMAND
codex mcp add example --url https://mcp.example.com --oauth-client-id my-client
codex mcp list
codex mcp login SERVER_NAME

Codex reads AGENTS.md files before it does any work. It first reads a global file from your Codex home (~/.codex/AGENTS.override.md if present, otherwise ~/.codex/AGENTS.md). It then walks from the project root down to your current directory and includes at most one file per directory: AGENTS.override.md, then AGENTS.md, then any names listed in project_doc_fallback_filenames. Files closer to your current directory appear later, so they override earlier guidance. The combined size is capped by project_doc_max_bytes, which defaults to 32 KiB.

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536