Codex supports named model providers in ~/.codex/config.toml, but a custom base URL is not enough. The endpoint must support the protocol, streaming events, tool calls, and model metadata Codex expects.
Check compatibility first
Look for a provider-specific Codex integration page. Confirm these items:
Provider compatibility checks
| Protocol | Responses or another wire API explicitly supported by Codex and the provider |
|---|---|
| Model ID | Exact current API identifier |
| Authentication | Provider key method documented for Codex |
| Model catalog | Required models.json or equivalent metadata |
| Tools | Streaming and tool-call behavior needed by Codex |
An endpoint described as OpenAI-compatible may implement only Chat Completions. That does not establish full Codex compatibility.
Back up the configuration
Copy these files before changing them:
~/.codex/config.toml
~/.codex/models.jsonThe same files may affect Codex CLI, the Codex IDE extension, and the ChatGPT desktop app in that environment.
Add the provider block
A provider-specific guide should supply the exact fields. The structure generally includes a selected model and a matching named provider:
model = "provider-model-id"
model_provider = "myprovider"
[model_providers.myprovider]
name = "My provider"
base_url = "https://provider.example/api"
wire_api = "responses"Do not copy the example URL or protocol literally. Replace them with values documented by the provider. Add authentication and a model catalog only in the form its current Codex guide requires.
Use a provider-specific setup when available
DeepSeek publishes a Codex setup that uses deepseek-v4-flash, the Responses API, and a custom model catalog. Follow DeepSeek V4 with Codex rather than adapting an old Chat Completions example.
For another provider, use its official Codex page or test the endpoint in an isolated Codex configuration before changing your default.
Verify before editing
Restart Codex after saving the configuration. Check the startup model and send a read-only request from a small repository. Confirm the request in the provider’s logs or usage page.
Common failures:
- A protocol or stream error often means
wire_apidoes not match the endpoint. - A model-not-found response means the model ID or catalog is stale.
- A login prompt can mean the custom authentication settings did not apply.
- Missing tools can mean the provider implements basic text generation but not the features Codex needs.
Custom Codex provider checklist
- Provider-specific Codex documentation located
- Existing Codex files backed up
- Exact model ID and wire protocol verified
- Credential stored outside version control
- Read-only request confirmed in provider logs
