Skip to main content
API7.ai Logo
Version: Dev

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"
# Include /v1 and omit the trailing slash
# The local quickstarts use http://127.0.0.1:3000/v1
base_url = "YOUR_AISIX_GATEWAY_URL/v1"
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.

Use Codex With Other Providers​

When the model alias is backed by a provider key that does not serve the Responses API, such as an Anthropic key, AISIX translates each Codex request to Chat Completions and translates the answer back. A few behaviors on that path matter to Codex specifically:

  • Codex's namespace tools, such as multi_agent_v1, are offered to the model as flattened function tools, and the model's calls come back to Codex under their original name and namespace. See Tool Parameters.
  • The reasoning Codex replays in its history is sent to OpenAI-compatible upstreams as reasoning_content, so input token counts rise over a multi-turn session. See Replayed Conversation History.
  • When a turn fails mid-stream, AISIX ends the stream with a response.failed event, so Codex shows the error message. A turn stopped by an output guardrail fails with invalid_prompt, which Codex does not retry. See Stream Failures on the Bridged Path.
  • Hosted tools such as web_search are dropped on this path.

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.
A follow-up turn fails on an OpenAI-compatible upstream after the model returned reasoningThe upstream may reject the reasoning_content field AISIX adds to replayed assistant messages. See Replayed Conversation History.
Requests bypass AISIXConfirm model_provider = "aisix" is in the active Codex configuration layer.

For endpoint behavior and provider boundaries, see Responses API.

Next Steps​