model_providers.<id>.base_url

Values

Any URL string. There is no default; a custom provider without a base_url has nowhere to send requests. A minimal custom provider looks like:

[model_providers.my_provider]
name = "My Custom Provider"
base_url = "https://api.example.com/v1"
env_key = "MY_API_KEY"
wire_api = "responses"

Sibling keys on the same table (full list in the config reference): query_params (a map, used for things like Azure’s api-version), requires_openai_auth, env_http_headers, request_max_retries (default 4), stream_idle_timeout_ms (default 300000), and stream_max_retries (default 5).

When to change it

1. Azure OpenAI. Set base_url = "https://YOUR_RESOURCE.openai.azure.com/openai" plus query_params = { api-version = "..." }, and make sure model matches your deployment name in Azure AI Foundry, not the base model name (Vaughan’s multi-cloud writeup covers the full snippet).
2. Internal proxy or gateway. Point base_url at your gateway and handle auth with env_key or env_http_headers.
3. Data residency. Regional endpoints like https://us.api.openai.com/v1 go here on a custom entry.
4. Bedrock is the exception. Skip base_url entirely and set model_providers.amazon-bedrock.aws.profile and .region; the built-in provider signs requests through the AWS credential chain.

Gotchas

The big one: the endpoint must speak the Responses API. The config reference says responses “is the only supported value” for wire_api, and chat is gone from the docs. Proxies that only speak chat completions broke at 0.59 (#7051, 0.58 was the last working release). OpenAI shipped more chat/completions fixes in 0.66 and closed the thread, but has since announced it’s deprecating chat/completions in Codex, so a Responses-API endpoint is the safe bet. Setting base_url alone doesn’t switch Codex over, either; point model_provider at your <id> or it keeps calling OpenAI with the wrong key (#987).

Also: the whole model_providers table is blocked in project-scoped config, so a base_url in a repo’s config gets ignored. Set it in ~/.codex/config.toml.

Related settings

• openai_base_url overrides the built-in OpenAI endpoint itself, no custom provider entry needed (also blocked in project scope).
• model_providers.<id>.wire_api is the protocol trap described above.
• model_provider is the switch that actually selects your <id>; without it, base_url does nothing.