Codex config.toml: Model, Proxy and Permissions Setup

Codex’s user configuration is $CODEX_HOME/config.toml, normally ~/.codex/config.toml. Trusted projects can add .codex/config.toml overrides. Before adding settings, check which file and profile your session actually loads.

This guide was refreshed against OpenAI’s configuration basics and configuration reference on September 9, 2026. Keep the installed client’s version in mind: older tutorials may use a different profile format or keys that have changed.

Where is config.toml on Windows, macOS and Linux?

In the IDE extension, the official guide points to Codex Settings → Open config.toml. That is useful when the extension’s environment differs from the terminal you normally use.

Start with a minimal config.toml

This example sets behavior without guessing which model your account can access:

approval_policy = "on-request"
sandbox_mode = "workspace-write"
file_opener = "vscode"

[sandbox_workspace_write]
network_access = false

Choose a model from the options available to your actual account and provider before adding a model value. A model name copied from an older tutorial is not proof of present access.

Keep top-level keys above TOML table headers. For example, placing model_provider after [sandbox_workspace_write] makes it part of that table unless you restructure the file. Valid TOML syntax does not guarantee the key is in the right Codex section.

Which configuration wins?

The current official precedence, highest first, is:

1. CLI flags and --config overrides.
2. Trusted project .codex/config.toml layers, with the closest directory taking precedence.
3. The selected profile file.
4. User config.toml.
5. System configuration, when present.
6. Built-in defaults.

Organization-enforced requirements can constrain available settings; they are not simply another user-editable default. A local file cannot bypass an organization’s requirements or the host application’s permissions.

The reference also lists keys ignored in project-local configuration, including provider/auth routing, notifications, profile selection and telemetry routing. Put machine-local provider configuration in the user configuration. Do not treat all sandbox and approval settings as categorically ignored in project files; check the current trust and policy rules.

Profiles: use the documented file format

Current documentation uses a separate file next to the user config. For example, create ~/.codex/review.config.toml with:

approval_policy = "on-request"
sandbox_mode = "read-only"

Then select it:

codex --profile review

With a custom CODEX_HOME, place the file in that directory. Profile values can still be overridden by trusted project configuration and explicit CLI flags. If an old tutorial shows [profiles.review] inside the main file, compare it with the documentation for your installed version instead of mixing both styles into one example.

Why a setting does not take effect

Restart the relevant session after editing persistent configuration when necessary. Save the exact startup error instead of assuming an ignored key is a network failure.

Sandbox permissions and approval prompts are separate

sandbox_mode describes the execution boundary. approval_policy controls when approval can be requested. Setting approval_policy="never" does not grant filesystem or network access that the sandbox lacks.

workspace-write is a useful starting point for a project that needs local edits. Configure additional writable roots or network access only for the intended workflow and within the host’s policy. danger-full-access removes the Codex sandbox boundary but does not override operating-system permissions or organizational restrictions.

A task may fail because of a permission boundary, an approval policy or a separate service error. Distinguish these before changing several controls together. The sandbox troubleshooting guide covers that category of failures.

Proxy and network checks

A package download or API call can fail because of DNS, authentication, a proxy, service availability or a network restriction. A network error does not automatically mean you should disable the sandbox.

Start by checking the exact host and error, the environment inherited by the Codex process, and the applicable network policy. If you need advanced permission profiles or proxy configuration, use the matching sections of the configuration reference. Do not combine an old boolean feature flag and a table under the same TOML key.

Custom providers need the right API protocol

The current reference documents responses as the supported wire_api value. A provider exposing only Chat Completions is not automatically compatible with that requirement.

The following is a configuration template, not a verified live route:

# User-level config.toml; replace all provider placeholders first.
model_provider = "example"
model = "PROVIDER_DOCUMENTED_MODEL_ID"

[model_providers.example]
name = "Example provider"
base_url = "https://api.example.com/v1"
wire_api = "responses"
env_key = "EXAMPLE_API_KEY"
requires_openai_auth = false

Keep the real secret in the environment, not in the TOML file. requires_openai_auth concerns OpenAI authentication; it is not a generic switch for accepting or rejecting key prefixes. Check the provider’s route, model ID and authentication requirements together.

See the custom provider guide for the wider workflow, and OpenAI model_not_found troubleshooting when a request reports a missing model.

MCP and environment settings

The reference documents mcp_servers.<id> entries for local commands and HTTP servers. Use the server’s actual installation instructions and required environment variables. A configured name does not prove that a package exists or that its tools initialized successfully.

Check startup and tool timeouts when a server is slow. Do not assume a longer timeout repairs invalid credentials or an incorrect command.

Environment inheritance is also configurable. The current reference states that shell_environment_policy.ignore_default_excludes defaults to true; setting it to false enables automatic exclusions for names containing KEY, SECRET or TOKEN before other filters. Avoid copying old claims that automatic secret-name filtering is always enabled by default. Preserve the variables your intended tools need while keeping unrelated credentials out of their environment.

Keep advanced settings as a reference, not a giant starter file

Hooks, telemetry, TUI shortcuts and permission profiles have their own schemas. Add one section at a time and verify it against the installed client. A long pasted file can contain contradictory tables or unsupported defaults even when individual snippets look plausible.

For errors beyond configuration, use the Codex error index. Keep a known-working configuration so a failed provider or profile change can be rolled back without rebuilding the whole file.