Codex CLI config.toml Reference

Updated September 30, 2026 by Alex Sorokoletov

Independent reference, not affiliated with OpenAI. Tables are generated from the Codex CLI source at rust-v0.159.2 (v0.159.2). Official documentation: learn.chatgpt.com.

Codex CLI reads ~/.codex/config.toml (or $CODEX_HOME/config.toml) and merges it with system, project, profile and command-line layers, the higher layer winning key by key. A project's .codex/config.toml loads only once the project is trusted and cannot set model providers, base URLs or notify. Legacy managed_config.toml outranks everything, including -c flags.

Where is Codex config.toml located?#

The user file is config.toml in $CODEX_HOME, which defaults to .codex in your home directory. When CODEX_HOME is set it must point at an existing directory, or Codex refuses to start. The machine-wide file is /etc/codex/config.toml on macOS and Linux and %ProgramData%\OpenAI\Codex\config.toml on Windows. Repositories can add .codex/config.toml; Codex finds every one from the working directory up to the project root, but applies them only after the project is trusted, recorded in config.toml as trust_level = "trusted" under [projects."/path/to/repo"].

What overrides config.toml?#

Every source is a layer with a fixed precedence; a key set in a higher layer replaces the same key from lower ones, and tables merge recursively.

Two results of that order surprise people. -c flags and --profile files override the user file, but the legacy managed_config.toml layers sit above session flags, so an administrator's file there beats anything typed on the command line. And a trusted project's config beats your user config for most keys, except the ones below, which a repository may not set because they decide where credentials go and which local commands run:

codex -c hide_agent_reasoning=true -c sandbox_workspace_write.network_access=true

How do Codex profiles work?#

A profile is a separate file, $CODEX_HOME/<name>.config.toml, selected with --profile <name> (or -p). It layers on top of config.toml, so it only needs the keys that differ, and it stays below project config and command-line flags. The old style, a profile = "<name>" selector plus [profiles.<name>] tables inside config.toml, no longer works in 0.159.2:

How do I add a custom model provider?#

Define the provider under [model_providers.<id>] and select it with model_provider. Codex speaks only the OpenAI Responses API to providers, so the endpoint must implement /v1/responses; wire_api = "chat" is rejected at load.

model_provider = "my-gateway"

[model_providers.my-gateway]
name = "My gateway"
base_url = "https://llm.example.com/v1"
env_key = "MY_GATEWAY_API_KEY"
wire_api = "responses"
query_params = { api-version = "2026-01-01" }

env_key names the environment variable that holds the API key; http_headers adds fixed headers and env_http_headers fills header values from environment variables. These provider ids are built in and cannot be redefined, except the two Bedrock ids, which accept endpoint, auth, AWS and header overrides:

How do I configure MCP servers in config.toml?#

Each server is a [mcp_servers.<name>] table. The keys pick the transport: command starts a local process over stdio, url connects over streamable HTTP.

[mcp_servers.docs]
command = "npx"
args = ["-y", "@example/docs-mcp"]
startup_timeout_sec = 20
tool_timeout_sec = 60

[mcp_servers.tracker]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "TRACKER_TOKEN"
enabled_tools = ["search", "get_issue"]

MCP servers that ship inside a plugin are configured under the plugin's entry instead; see the plugins reference.

Which feature flags does Codex have?#

Feature flags are booleans under [features], for example hooks = false or network_proxy = true. The Default column is what applies when the key is absent. Under-development features are incomplete and trigger a warning when enabled, which suppress_unstable_features_warning = true silences. Removed flags still parse, as no-ops, so old configs keep loading. A trusted project's [features] table cannot set respect_system_proxy.

config.toml key reference#

Every top-level key in the JSON Schema Codex generates from its config types. Table-valued keys such as permissions, sandbox_workspace_write and hooks have their own references: permissions and hooks.

Frequently asked questions#

Where is Codex config.toml located?#

In .codex under your home directory: ~/.codex/config.toml on macOS and Linux, and the .codex folder in your user profile on Windows. Setting CODEX_HOME moves it to $CODEX_HOME/config.toml, and that directory must already exist. Machine-wide settings go in /etc/codex/config.toml or %ProgramData%\OpenAI\Codex\config.toml, and repositories can add .codex/config.toml.

What overrides config.toml?#

From highest to lowest: legacy managed_config.toml (MDM, then file), command-line flags and -c key=value, a trusted project's .codex/config.toml, the --profile file, ~/.codex/config.toml, enterprise cloud config, /etc/codex/config.toml, macOS managed preferences, and packaged defaults. Separately, requirements.toml can restrict which values are allowed at all.

How do I add a custom model provider such as OpenRouter, Azure or a local model?#

Add a [model_providers.<id>] table with base_url, env_key and wire_api = "responses", then set model_provider = "<id>". The endpoint must implement the Responses API, because chat completions support was removed. Ollama and LM Studio are built in as ollama and lmstudio; use them with --oss and --local-provider instead of defining your own.

What does wire_api do in Codex?#

wire_api names the protocol Codex uses to talk to a model provider. In 0.159.2 the only accepted value is responses, the OpenAI Responses API, and it is also the default. The old wire_api = "chat" value now fails config loading with an instruction to switch to responses, and the ollama-chat provider id was removed the same way.

How do I configure MCP servers in Codex config.toml?#

Add one [mcp_servers.<name>] table per server. Use command and args (plus optional env and cwd) for a local stdio server, or url with bearer_token_env_var or http_headers for a streamable HTTP server. enabled_tools, disabled_tools, startup_timeout_sec and tool_timeout_sec tune each server, and enabled = false switches one off.

Why does Codex ignore my project .codex/config.toml?#

Project config applies only to trusted projects; until you accept the trust prompt, or set trust_level = "trusted" for the path under [projects], the layer loads but stays disabled. Even when trusted, a project file cannot set keys that redirect credentials or run local commands, such as model_provider, model_providers, openai_base_url, notify and otel; Codex drops them from the project layer and keeps your user values.

Why does Codex say legacy profile config is no longer supported?#

Profiles moved out of config.toml. Codex 0.159.2 rejects profile = "<name>" and refuses --profile <name> while a [profiles.<name>] table exists. Move those settings into ~/.codex/<name>.config.toml, delete the old selector and table, and start Codex with --profile <name>. The profile file only needs the keys that differ, because it layers on top of config.toml.

Release-by-release changes: Codex CLI version tracker. All Codex CLI pages: Codex CLI reference index.