Codex config.toml: A Working Setup and What Each Error Means

Recent Codex CLI releases reject parts of older config.toml files. A profile = "..." line, wire_api = "chat" or approval_policy = "untrusted" now stop it at startup, and a few other mistakes fail silently. Configs copied from guides written earlier in 2026 are the usual cause.

This post is the config that works on Codex CLI 0.162.1 with a custom provider, the checks to run after editing it, and the exact messages Codex prints when something is wrong. Checked on October 19, 2026, against OpenAI's configuration docs. AIHubMix is the provider in the examples; any gateway that serves the OpenAI Responses API is configured the same way.

TL;DR

• File: ~/.codex/config.toml (C:\Users\<you>\.codex\config.toml on Windows). Codex reads it only at startup.
• Provider: base_url, wire_api = "responses" (the only accepted value), and env_key, which names an environment variable holding the key.
• Profiles: one file each, ~/.codex/<name>.config.toml, selected with --profile <name>. [profiles.x] tables inside config.toml are gone.
• Project .codex/config.toml: trusted projects only, and it can't set model_provider.
• Proxy: no config key. Codex follows HTTPS_PROXY, ALL_PROXY and NO_PROXY.

Prerequisites

• Codex CLI installed (npm install -g @openai/codex), checked here on 0.162.1
• An API key for your provider; for AIHubMix, from the AIHubMix console

The config

# ~/.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"

# macOS / Linux: put this in ~/.zshrc or ~/.bashrc, then open a new terminal
export AIHUBMIX_API_KEY=sk-...

# Windows PowerShell: applies to terminals opened afterwards
setx AIHUBMIX_API_KEY "sk-..."

Three rules that cause most failures:

• model_provider must match the table name, and the table name can't be openai, ollama or lmstudio, which belong to Codex's built-in providers.
• env_key is the name of the variable, not the key. The key saved by codex login in auth.json is never sent to a custom provider.
• Top-level keys go above the first [table] line. In TOML, everything after a table header belongs to that table.

Check it

codex exec "say ok"     # one non-interactive request
codex doctor            # install, config and auth checks

codex exec prints the effective settings before the request: model:, provider:, approval:, sandbox: and reasoning effort:. That header is the quickest way to see which values actually won. Note that codex exec reported approval: never in testing even with on-request in the config, because a non-interactive run has nobody to ask.

Profiles and project config

A profile is a file with only the keys that differ, written at the top level:

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

Run it with codex --profile review. The format changed in Codex 0.134.0; OpenAI's advanced configuration guide covers the migration.

A repo's .codex/config.toml is read only if the project is trusted in your user config:

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

Even then, Codex drops model_provider, model_providers, openai_base_url, profile, notify and a few others from project files, so a repo can't redirect your requests. Keep providers in ~/.codex/config.toml.

Precedence

From OpenAI's Config basics, highest first:

1. CLI flags and -c key=value overrides
2. Project .codex/config.toml (closest to the working directory wins)
3. The --profile file
4. ~/.codex/config.toml
5. /etc/codex/config.toml
6. Built-in defaults

The project file outranks the profile. In a test with a different model in the user config, a profile and a trusted project, codex exec --profile fast ran the project's model and only took the profile's reasoning effort; -m beat both.

Sandbox and approvals

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, with no network until you set network_access = true under [sandbox_workspace_write]. never stops prompts but doesn't widen the sandbox.

Proxy

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 environment variable reference documents CODEX_CA_CERTIFICATE but not the proxy variables. With Codex 0.162.1, requests to the custom provider went through HTTPS_PROXY, lowercase https_proxy and ALL_PROXY, and hosts in NO_PROXY were skipped.

Custom models in /model

/model lists only OpenAI's models unless a top-level model_catalog_json points at a catalog file. The catalog replaces the built-in list, and every entry needs the full internal field set, so generate it: the AIHubMix Codex CLI guide has a script that clones a built-in entry for the top 30 AIHubMix models. Verify with codex debug models.

Failure modes and fixes

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

A profile = "..." selector is still in config.toml. Move the profile into its own file and delete the selector. With a leftover [profiles.x] table, --profile x fails with --profile x cannot be used while ... contains legacy ... config. Without the flag, the table is ignored silently.

wire_api = "chat" is no longer supported

Change it to responses. Providers that only serve Chat Completions need a translating proxy.

model_providers contains reserved built-in provider IDs

Rename a provider called openai, ollama or lmstudio. To repoint the built-in OpenAI provider, set the top-level openai_base_url instead.

approval_policy = "untrusted" is no longer supported

Remove it or use on-request. on-failure is deprecated but still accepted.

Missing environment variable: AIHUBMIX_API_KEY

The variable named in env_key isn't in the environment Codex started from. New terminal, or source ~/.zshrc.

401 Unauthorized after "Reconnecting..."

The request carried no key. Check env_key; auth.json doesn't apply to custom providers.

Model metadata for ... not found. Defaulting to fallback metadata

A warning for any model outside Codex's catalog, normal for non-OpenAI models. Requests still work; a catalog removes it.

Ignored unsupported project-local config keys

A project file set a user-only key, usually model_provider. Move it to ~/.codex/config.toml.

missing field base_instructions

A catalog entry is incomplete and the whole file is rejected. Regenerate the catalog instead of hand-editing it.

Not verified here

• PAC files: Codex has no setting for them; the behavior described in third-party write-ups wasn't tested.
• The desktop app's model picker: it may hide catalog models (openai/codex#19694); only the CLI was tested.
• No real requests were sent for the error tests; each used a throwaway CODEX_HOME and an unreachable base URL.

Sources

• Config basics (OpenAI)
• Advanced configuration (OpenAI)
• Configuration reference (OpenAI)
• Codex CLI integration guide (AIHubMix)
• Codex CLI proxy configuration: SOCKS, HTTP, and corporate networks (Daniel Vaughan)