Codex guide

Read the configuration map

config.toml may be absent or empty. A working connection still needs an available model, provider, endpoint and any required credentials, which can come from defaults, login state or configuration. This page lists all 306 public paths and all 103 schema roots. Schema-only fields are structural information, not a promise of availability.

依据：Config reference · Advanced config · Authentication

Locations, precedence and requirements

Normal precedence is CLI overrides, trusted project layers, the selected standalone profile, user config, cloud-managed defaults, system config, then built-ins. Requirements constrain allowed behavior separately. Project config cannot override provider/auth routing keys such as model_provider, model_providers and openai_base_url.

依据：Config reference · Advanced config · Authentication

TOML scope and profile files

Top-level keys go before table headers. Everything after [model_providers.custom] belongs to that table until another header. Blank lines do not reset scope. Since 0.134.0, use $CODEX_HOME/name.config.toml with --profile name; the old [profiles.name] and top-level profile selector no longer work.

依据：Config reference · Advanced config · Authentication

Provider IDs, display names and built-ins

model_provider selects an exact provider ID; [model_providers.custom] defines custom; name is only a display label. Naming it OpenAI does not enable official login. openai, ollama and lmstudio are reserved built-in IDs. amazon-bedrock is a special built-in provider with documented AWS overrides.

model = "<provider-model-id>"
model_provider = "custom"

[model_providers.custom]
name = "OpenAI"
base_url = "https://gateway.example.com/v1"
env_key = "COMPANY_CODEX_KEY"
requires_openai_auth = false
wire_api = "responses"

依据：Config reference · Advanced config · Authentication

Endpoints, protocols and capabilities

base_url is the selected custom provider endpoint; openai_base_url changes the built-in OpenAI endpoint; chatgpt_base_url concerns sign-in. The current wire_api supports only responses and defaults to it. Chat Completions compatibility alone is insufficient. The correct path is service-specific; not every gateway uses /v1.

依据：Config reference · Advanced config · Authentication

Authentication paths and mutual exclusions

Official OpenAI supports ChatGPT sign-in and API keys. A custom env_key names the environment variable supplying a Bearer key. requires_openai_auth defaults to false for custom providers; true selects OpenAI credentials and ignores env_key, not necessarily subscription login. Command-backed auth must not be combined with env_key, experimental_bearer_token or requires_openai_auth. Gateway ChatGPT sign-in needs separate gateway authentication.

依据：Config reference · Advanced config · Authentication

Minimal configuration recipes

Choose one scenario, replace placeholders and verify the target service. ChatGPT and API sign-in, Bearer keys, custom headers, token commands, dual-credential gateways, local models and Bedrock are distinct paths. The examples are configuration structures; no live credentials or gateway calls were tested.

model = "gpt-6.1-sol"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

codex login
codex login status

printenv OPENAI_API_KEY | codex login --with-api-key
codex login status

model = "<gateway-model-id>"
model_provider = "company"

[model_providers.company]
name = "Company gateway"
base_url = "https://gateway.example.com/v1"
wire_api = "responses"
env_key = "COMPANY_CODEX_KEY"
requires_openai_auth = false

model = "<gateway-model-id>"
model_provider = "header_gateway"

[model_providers.header_gateway]
name = "Header gateway"
base_url = "https://gateway.example.com/v1"
requires_openai_auth = false
env_http_headers = { "X-API-Key" = "COMPANY_CODEX_KEY" }

model = "<gateway-model-id>"
model_provider = "token_gateway"

[model_providers.token_gateway]
name = "Short-lived token gateway"
base_url = "https://gateway.example.com/v1"
wire_api = "responses"

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

model_provider = "enterprise_gateway"
model = "gpt-6.1-sol"

[model_providers.enterprise_gateway]
name = "ChatGPT via company gateway"
base_url = "https://gateway.example.com/backend-api/codex"
requires_openai_auth = true
env_http_headers = { "X-Gateway-Key" = "GATEWAY_KEY" }

oss_provider = "ollama"

model_provider = "amazon-bedrock"
model = "<supported-bedrock-model-id>"

[model_providers.amazon-bedrock.aws]
profile = "default"
region = "<supported-aws-region>"

依据：Config reference · Advanced config · Authentication

Models, reasoning, context and costs

Use model IDs and effort levels available to your account/provider. A larger model_context_window does not increase server limits. Compaction thresholds, verbosity and service tiers serve different purposes. Compaction and rollout token accounting do not reset subscription usage or enforce a universal billing cap.

依据：Config reference · Advanced config · Authentication

Permission profiles and approvals

Legacy sandbox settings and beta permission profiles do not compose. A loaded sandbox_mode or --sandbox selects the legacy path except when managed profile requirements force profiles. network.enabled alone does not activate the proxy; domain rules require an active command proxy. never does not grant additional access.

依据：Config reference · Advanced config · Authentication

Tools, integrations and environment

Search, command networking, MCP and apps have separate routes and controls. MCP OAuth is independent of model login. Skill catalogs, hook handlers and agent roles need compatible runtime support. Shell filtering controls child-process environments, not every possible secret-access path.

依据：Config reference · Advanced config · Authentication