Advanced Configuration

For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.

Use these options when you need more control over providers, policies, and integrations. For a quick start, see Config basics.

For background on project guidance, reusable capabilities, custom slash commands, subagent workflows, and integrations, see Customization. For configuration keys, see Configuration Reference.

Profiles

Profiles let you save named configuration layers and switch between them from the CLI. When you pass --profile profile-name, Codex loads ~/.codex/config.toml, then overlays ~/.codex/profile-name.config.toml. Profile names can contain letters, numbers, hyphens, and underscores.

Create a separate TOML file for each profile. Use top-level config keys in the profile file; don't nest them under [profiles.profile-name].

# ~/.codex/deep-review.config.toml
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
approval_policy = "on-request"
model_catalog_json = "/Users/me/.codex/model-catalogs/deep-review.json"

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

Because the profile file is a layer above your base user config and below project and CLI config, it only needs the values that differ from your base config. Profile files can also override model_catalog_json; Codex uses the profile value when both files set it.

In Codex 0.134.0 and later, --profile no longer reads [profiles.profile-name] from config.toml, and the top-level profile = "profile-name" selector is no longer supported. Move legacy profile settings into ~/.codex/profile-name.config.toml, then remove the matching [profiles.profile-name] table and profile = "profile-name" selector from config.toml.

One-off overrides from the CLI

In addition to editing ~/.codex/config.toml, you can override configuration for a single run from the CLI:

• Prefer dedicated flags when they exist (for example, --model).
• Use -c / --config when you need to override an arbitrary key.

Examples:

# Dedicated flag
codex --model gpt-5.6-terra

# Generic key/value override (value is TOML, not JSON)
codex --config model='"gpt-5.6-terra"'
codex --config sandbox_workspace_write.network_access=true
codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'

Notes:

• Keys can use dot notation to set nested values (for example, mcp_servers.context7.enabled=false).
• --config values are parsed as TOML. When in doubt, quote the value so your shell doesn't split it on spaces.
• If the value can't be parsed as TOML, Codex treats it as a string.

Config and state locations

Codex stores its local state under CODEX_HOME (defaults to ~/.codex).

Common files you may see there:

• config.toml (your local configuration)
• auth.json (if you use file-based credential storage) or your OS keychain/keyring
• history.jsonl (if history persistence is enabled)
• Other per-user state such as logs and caches

For authentication details (including credential storage modes), see Authentication. For the full list of configuration keys, see Configuration Reference.

For shared defaults, rules, and skills checked into repos or system paths, see Team Config.

If you just need to point the built-in OpenAI provider at an LLM proxy, router, or data-residency enabled project, set openai_base_url in config.toml instead of defining a new provider. This changes the base URL for the built-in openai provider without requiring a separate model_providers.<id> entry.

openai_base_url = "https://us.api.openai.com/v1"

Project config files (.codex/config.toml)

In addition to your user config, Codex reads project-scoped overrides from .codex/config.toml files inside your repo. Codex walks from the project root to your current working directory and loads every .codex/config.toml it finds. If multiple files define the same key, the closest file to your working directory wins.

For security, Codex loads project-scoped config files only when the project is trusted. If the project is untrusted, Codex ignores project .codex/ layers, including .codex/config.toml, project-local hooks, and project-local rules. User and system layers remain separate and still load.

Relative paths inside a project config (for example, model_instructions_file) are resolved relative to the .codex/ folder that contains the config.toml.

Project config files can't override settings that redirect credentials, alter host-owned app request metadata, change provider auth, select config profiles, or run machine-local notification/telemetry commands. Codex ignores the following keys in project-local .codex/config.toml and prints a startup warning when it sees them: openai_base_url, chatgpt_base_url, apps_mcp_product_sku, model_provider, model_providers, notify, profile, profiles, experimental_realtime_ws_base_url, and otel. Set provider, notification, and telemetry keys in your user-level ~/.codex/config.toml; select config profiles with --profile profile-name and ~/.codex/profile-name.config.toml.

Hooks

Codex can also load lifecycle hooks from either hooks.json files or inline [hooks] tables in config.toml files that sit next to active config layers.

In practice, the four most useful locations are:

• ~/.codex/hooks.json
• ~/.codex/config.toml
• <repo>/.codex/hooks.json
• <repo>/.codex/config.toml

Project-local hooks load only when the project .codex/ layer is trusted. User-level hooks remain independent of project trust.

Inline TOML hooks use the same event structure as hooks.json:

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'
timeout = 30
statusMessage = "Checking Bash command"

If a single layer contains both hooks.json and inline [hooks], Codex loads both and warns. Prefer one representation per layer.

For the current event list, input fields, output behavior, and limitations, see Hooks.

Agent roles ([agents] in config.toml)

For subagent role configuration ([agents] in config.toml), see Subagents.

Project root detection

Codex discovers project configuration (for example, .codex/ layers and AGENTS.md) by walking up from the working directory until it reaches a project root.

By default, Codex treats a directory containing .git as the project root. To customize this behavior, set project_root_markers in config.toml:

# Treat a directory as the project root when it contains any of these markers.
project_root_markers = [".git", ".hg", ".sl"]

Set project_root_markers = [] to skip searching parent directories and treat the current working directory as the project root.

Custom model providers

A model provider defines how Codex connects to a model (base URL, wire API, authentication, and optional HTTP headers). Custom providers can't reuse the reserved built-in provider IDs: openai, ollama, and lmstudio.

Define additional providers and point model_provider at them:

model = "gpt-5.6-terra"
model_provider = "proxy"

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"

[model_providers.local_ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"

[model_providers.mistral]
name = "Mistral"
base_url = "https://api.mistral.ai/v1"
env_key = "MISTRAL_API_KEY"

If a custom provider supports the standalone web search endpoint, advertise that capability in its provider configuration:

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "https://proxy.example.com/v1"
env_key = "OPENAI_API_KEY"
supports_standalone_web_search = true

The setting defaults to false for custom providers. Standalone web search is under development and off by default. Setting the provider capability to true doesn't enable it: the provider must support a compatible endpoint, and the selected model and runtime must support standalone search. The configured web_search mode and managed search restrictions still apply.

Add request headers when needed:

[model_providers.example]
http_headers = { "X-Example-Header" = "example-value" }
env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }

Use command-backed authentication when a provider needs Codex to fetch bearer tokens from an external credential helper:

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "https://proxy.example.com/v1"
wire_api = "responses"

[model_providers.proxy.auth]
command = "/usr/local/bin/fetch-codex-token"
args = ["--audience", "codex"]
timeout_ms = 5000
refresh_interval_ms = 300000

The auth command receives no stdin and must print the token to stdout. Codex trims surrounding whitespace, treats an empty token as an error, and refreshes proactively at refresh_interval_ms; set refresh_interval_ms = 0 to refresh only after an authentication retry. Don't combine [model_providers.<id>.auth] with env_key, experimental_bearer_token, or requires_openai_auth.

Amazon Bedrock provider

Codex includes a built-in amazon-bedrock model provider. Set it directly as model_provider; unlike custom providers, this built-in provider supports only the nested AWS profile and region overrides.

model_provider = "amazon-bedrock"