Connect Codex to your API: Base URL, model, and env_key

Collect the connection details first

Confirm the provider’s Base URL, exact model ID, and Responses API support. A successful conversation in another chat client does not prove compatibility with Codex. This guide uses a custom provider with environment-based authentication. For a direct OpenAI key, see authentication and credentials.

• Use the service base address with the prefix your provider specifies, such as /v1.
• Use a model identifier accepted by that provider, not just its display name.
• Keep the secret on your machine; our generator only needs its variable name.

Write a minimal user-level configuration

model = "YOUR_MODEL_ID"
model_provider = "my-provider"

[model_providers.my-provider]
name = "My API provider"
base_url = "https://api.example.com/v1"
env_key = "CODEX_PROVIDER_KEY"
wire_api = "responses"

The example URL and model are placeholders, not working access supplied by this site. Match model_provider to the table identifier. Put routing in the user configuration, not project .codex/config.toml. Do not redefine reserved provider IDs such as openai, ollama, or lmstudio.

env_key is a name, not a secret

Make CODEX_PROVIDER_KEY available to the process that starts Codex. This Bash/zsh example reads a key without displaying the input, exports it for this terminal session, and launches the CLI.

printf "API key: "
IFS= read -r -s CODEX_PROVIDER_KEY
printf "\n"
export CODEX_PROVIDER_KEY
codex

A desktop app launched from an icon may not inherit that terminal export. Compare the actual startup environments before changing keys. For a visual workflow, use our CC Switch guide. Avoid having multiple utilities repeatedly overwrite the same configuration.

Check compatibility by symptom

Current wire_api supports responses only. Setting chat does not adapt a Chat Completions service. Use a compatible endpoint or a verified adapter, and avoid adding repeated /v1 segments while guessing.

Verify a small request

1. Back up the old configuration, merge the provider settings, and verify that the variable exists without printing its contents.
2. Restart the client or CLI and ask it to summarize a small local file.
3. Match the request time, endpoint, and model against provider logs. A displayed model name alone does not prove routing.
4. If it fails, preserve a redacted error and check one layer at a time. Restore the previous settings and restart to roll back.

Use the config generator for a template or continue to the troubleshooting checklist.