Skip to main content
API7.ai Logo

Codex

Codex supports custom model providers in its configuration file. Use a custom provider when Codex should send Responses API requests to AISIX instead of calling a model provider directly.

In this guide, you will point Codex at the AISIX proxy API root and authenticate with an AISIX caller API key. The Codex custom model value will be an AISIX model alias.

Prerequisites​

Before starting, prepare the following:

  • Codex installed and able to read ~/.codex/config.toml.
  • A running AISIX gateway with the proxy listener available.
  • An AISIX caller API key.
  • A model alias that the caller API key can access and that works with the Responses API.

If AISIX is already deployed for your organization, obtain the gateway URL, model alias, and caller API key from the team that manages it. Otherwise, follow the Open-Source AISIX Gateway Quickstart or AISIX Cloud Quickstart, or contact API7 for Hybrid Cloud access.

Configure Codex​

Set the caller API key in the environment where Codex runs:

# Replace with your values
export AISIX_API_KEY="YOUR_CALLER_API_KEY"

Add an AISIX model provider to ~/.codex/config.toml:

~/.codex/config.toml
model = "gpt-4o-prod" # Use an AISIX model alias, not the upstream provider model ID.
model_provider = "aisix"

[model_providers.aisix]
name = "AISIX AI Gateway"
base_url = "http://127.0.0.1:3000/v1" # Point Codex at the AISIX proxy API root.
env_key = "AISIX_API_KEY" # Read the AISIX caller API key from the environment.
wire_api = "responses"

Verify the Integration​

Start Codex from the shell where AISIX_API_KEY is set:

codex

Ask a short question that requires a model response.

When the request succeeds, verify the following results:

  • Codex prints a model response.
  • AISIX records a successful POST /v1/responses request for the selected model alias.

AISIX authenticates the caller API key, checks model access, resolves the model alias, applies configured policies, and dispatches to the upstream provider behind the alias.

Troubleshoot Codex Requests​

If Codex cannot reach AISIX, check these items:

SymptomCheck
Authentication failsConfirm AISIX_API_KEY is set in the same shell or environment where Codex runs.
Model is not foundConfirm model in config.toml is an AISIX model alias visible to the caller API key.
Responses request failsConfirm the selected model alias works with the AISIX Responses API. Some provider-backed aliases do not support every OpenAI-specific Responses feature.
Requests bypass AISIXConfirm model_provider = "aisix" is in the active Codex configuration layer.

For endpoint behavior and provider boundaries, see Responses API.

Next Steps​