Codex CLI Configuration Guide: A Complete Breakdown of config.toml Errors

Recent Codex CLI updates have caused many older config.toml configurations to throw errors immediately on startup. The profile = "..." line, wire_api = "chat", or approval_policy = "untrusted" now block startup entirely, while some other errors fail silently. The most common cause is copying outdated configuration from earlier guides. This article compiles a working custom provider configuration for Codex CLI 0.162.1, the check commands to run after editing, and the exact messages Codex prints when something goes wrong.

Core Configuration: The Minimal Working Version

The config file lives at ~/.codex/config.toml (on Windows, C:\Users\<you>\.codex\config.toml), and Codex only reads it at startup. Here is the minimal configuration for working with a custom provider:

**TOML table header scoping rules**: In TOML, a `[table]` line is not a grouping marker but a "current table" switch—from that line until the next table header appears, all bare keys belong to that table. This means that if you mistakenly put `model = ...` under `[model_providers.aihubmix]`, it becomes `model_providers.aihubmix.model`, the top-level `model` is missing, and Codex falls back to the built-in default model—usually without any error. Similarly, `env_key` and `base_url` must be inside the provider table, while `model`, `model_provider`, and `model_reasoning_effort` must appear before any table header. This is why the article stresses that "top-level keys must be written before the first `[table]` line."

**wire_api and the Responses API**: `wire_api` specifies the request/response protocol Codex uses to communicate with the provider. `responses` refers to OpenAI's Responses API, whose request body contains an `input` array, `instructions`, and other fields, supporting reasoning summaries and structured output for tool calls; `chat` refers to the earlier Chat Completions API (a `messages` array). Newer versions of Codex implement features like reasoning effort and planning tools only under Responses semantics, so the `chat` option has been removed entirely. Third-party providers that only offer Chat Completions must put a protocol-conversion proxy in front to translate Responses requests into Chat Completions and back again.
# ~/.codex/config.toml
model = "gpt-6-sol"
model_provider = "aihubmix"
model_reasoning_effort = "high"

[model_providers.aihubmix]
name = "AIHubMix"
base_url = "https://aihubmix.com/v1"
wire_api = "responses"
env_key = "AIHUBMIX_API_KEY"

The API key is passed in via an environment variable. On macOS/Linux, add export AIHUBMIX_API_KEY=sk-... to ~/.zshrc or ~/.bashrc; on Windows PowerShell, use setx AIHUBMIX_API_KEY "sk-...", then open a new terminal.

Three rules behind most failures

• model_provider must match the table name, and the table name cannot be openai, ollama, or lmstudio—these are reserved IDs for Codex's built-in providers.
• env_key is the name of the variable, not the key itself. Credentials saved by codex login in auth.json are never sent to custom providers.
• Top-level keys must be written before the first [table] line. In TOML, everything after a table header belongs to that table.

Verifying That the Configuration Works

After editing, check with two commands:

codex exec "say ok"     # a single non-interactive request
codex doctor            # installation, configuration, and authentication check

codex exec prints the effective settings before making a request: model:, provider:, approval:, sandbox:, and reasoning effort:. This is the fastest way to confirm which value ultimately wins. In testing, even with on-request in the config, non-interactive runs still showed approval: never—because there's no one to ask.

Profiles and Project-Level Configuration

The profile format has changed. Each profile is now a separate file ~/.codex/<name>.config.toml containing only the keys that differ from the default configuration, placed at the top level:

# ~/.codex/review.config.toml
model_reasoning_effort = "xhigh"
sandbox_mode = "read-only"

Invoke it with codex --profile review. The old [profiles.x] tables are no longer supported.

A project-level .codex/config.toml is only read if the user configuration marks the project as trusted:

[projects."/Users/you/code/my-app"]
trust_level = "trusted"

Even then, Codex strips keys like model_provider, model_providers, openai_base_url, profile, and notify from project files to prevent a repository from redirecting your requests. Provider configuration should always live in the user-level ~/.codex/config.toml.

Precedence Order

From highest to lowest: CLI flags and -c key=value overrides, project .codex/config.toml (the one closest to the working directory wins), the --profile file, ~/.codex/config.toml, /etc/codex/config.toml, and built-in defaults.

One easy pitfall: project files take precedence over profiles. In testing, the user config, profile, and trusted project each set a different model, and codex exec --profile fast ultimately ran the project's model, adopting only the profile's reasoning effort; the -m flag can override both.

Sandbox and Approval Policy

Key	Values
sandbox_mode	read-only, workspace-write, danger-full-access
approval_policy	on-request, never, or a granular table

workspace-write allows writes in the working directory, /tmp, and $TMPDIR, but has no network by default—you need to set network_access = true under [sandbox_workspace_write]. never only stops pop-up approval prompts; it does not relax the sandbox scope.

Sandbox mode and approval policy are two orthogonal dimensions: sandbox_mode determines what the process can do at the OS level (which paths are writable, whether it has network access), while approval_policy determines whether Codex pauses to ask a human before performing an action. So setting approval_policy to never only cancels interactive confirmation—the sandbox boundary is untouched; conversely, setting sandbox_mode to danger-full-access does not automatically grant approval, it just removes the sandbox restrictions. A common misconception is that never means "unrestricted"—in fact, under read-only it still cannot write files. The granular approval table lets you set policies per command type (e.g., exec, apply_patch), which suits automation flows that need fine-grained control.

Proxy Settings

Codex has no proxy configuration keys; instead it follows environment variables:

export HTTPS_PROXY=http://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1
export CODEX_CA_CERTIFICATE=/path/to/corp-root-ca.pem   # only for TLS-inspecting proxies

OpenAI's documentation only records CODEX_CA_CERTIFICATE and does not document proxy variables. But in testing on 0.162.1, requests to custom providers did go through HTTPS_PROXY, lowercase https_proxy, and ALL_PROXY, and hosts in NO_PROXY were correctly skipped.

Common Errors and Fixes

legacy profile = "..." config is no longer supported

A leftover profile = "..." selector remains in config.toml. Move the profile into a separate file and delete that line. If a leftover [profiles.x] table remains, --profile x will report --profile x cannot be used while ... contains legacy ... config; without the flag, the table is silently ignored.

wire_api = "chat" is no longer supported

Change it to responses. Providers that only offer a Chat Completions interface need a conversion proxy layer.

model_providers contains reserved built-in provider IDs

Rename any provider named openai, ollama, or lmstudio. To point back to the built-in OpenAI provider, set the top-level openai_base_url instead.

approval_policy = "untrusted" is no longer supported

Delete the line or switch to on-request. on-failure is deprecated but still accepted.

Missing environment variable: AIHUBMIX_API_KEY

The variable specified by env_key is not in the environment when Codex starts. Open a new terminal or source ~/.zshrc.

401 Unauthorized after "Reconnecting..."

The request is not carrying the key. Check env_key; auth.json does not apply to custom providers.

Model metadata for ... not found

This is a warning about a model outside Codex's catalog, and it's normal for non-OpenAI models. Requests still work, and the warning disappears once you configure a model catalog.

Ignored unsupported project-local config keys

The project file sets keys that are user-level only, usually model_provider. Move them to ~/.codex/config.toml.

missing field base_instructions

A model catalog entry is incomplete, and the entire file was rejected. Regenerate the catalog rather than editing it by hand.

The model catalog mechanism: Codex ships with a built-in catalog of model metadata recording internal fields like context window, reasoning capability, and base_instructions for each model; the /model list and request construction both depend on it. When the configured model name is not in the catalog, Codex prints a Model metadata for ... not found warning and continues sending requests with a generic set of defaults—so non-OpenAI models can run but may behave oddly. When the top-level model_catalog_json points to a custom catalog file, it fully replaces the built-in catalog rather than merging with it, so every entry must have a complete set of fields; a missing required field like base_instructions causes the entire file to be rejected. The safe approach is to use a script to clone built-in entries and rewrite the model names, rather than writing them by hand.

Parts Not Yet Verified

The original author explicitly flagged three untested areas: PAC files (Codex has no corresponding setting, and the behavior described in third-party articles is unverified), the desktop app model selector (which may hide catalog models—see openai/codex#19694; only the CLI was tested), and the fact that none of the error tests sent real requests (each used a throwaway CODEX_HOME and an unreachable base_url).

Custom Models Appearing in /model

/model lists only OpenAI models by default unless the top-level model_catalog_json points to a catalog file. The catalog replaces the built-in list, and each entry needs a complete set of internal fields, so it's best generated with a script—AIHubMix's Codex CLI guide provides a script that clones built-in entries to cover its first 30 models. Verify with codex debug models.

Key Takeaways

• The config file is only read at startup, so you must restart Codex after changes.
• The only valid value for wire_api is responses, and the profile selector has moved to separate files.
• Project-level configuration takes precedence over profiles but cannot override provider settings.
• Authentication for custom providers goes only through environment variables; codex login credentials do not apply.
• Proxies rely on standard environment variables, with no dedicated configuration keys.