Codex Proxy: Route OpenAI Codex Through AISIX

A Codex proxy gives a platform team one controlled boundary for model traffic. Codex keeps using the Responses API, while the gateway holds provider credentials, authenticates the developer or automation profile, resolves an approved model name, and records the requests that actually cross the route.

The configuration is short. The compatibility contract is not. Codex needs Responses streaming, continuation, function calls, and useful errors—not merely an endpoint that returns one text response. Provider translation, hosted tools, reasoning history, retries, and mid-stream failures can change the result.

This guide uses AISIX AI Gateway 1.6.0 and the official Codex gateway documentation available on October 13, 2026. It covers the direct model path. Local shell commands, filesystem access, MCP connections, and Codex approval policy remain outside that path unless separately routed and controlled.

Key Takeaways

• Configure Codex with a custom model provider and wire_api = "responses".
• Give each developer or automation profile a scoped gateway credential, not the upstream provider key.
• Use a model name recognized by the installed Codex version, or distribute a matching model catalog for a custom alias.
• Test streaming, continuation, function calls, errors, and alias routing before rollout.
• Treat native Responses and Responses-to-chat translation as different compatibility targets.
• Apply only the limits, guardrails, budgets, and telemetry that your AISIX configuration explicitly attaches.

What Changes at the Gateway Boundary

The official Codex custom provider documentation defines a provider by its base URL, wire API, authentication, and optional headers. Placing AISIX at that URL changes four operational boundaries:

1. Developer credential: Codex presents a gateway credential. The upstream provider credential stays on the gateway.
2. Model selection: Codex requests an approved name that AISIX resolves to a provider-backed target.
3. Policy: authentication, model access, routing, and configured traffic controls run at AISIX.
4. Telemetry: AISIX can observe model traffic that reaches its proxy listener.

flowchart LR
    C[Codex CLI or automation] -->|Gateway credential<br/>POST /v1/responses| G[AISIX AI Gateway 1.6.0]
    G -->|Resolve approved model| R{Native or bridged path}
    R -->|Responses| N[Responses-capable upstream]
    R -->|Protocol translation| B[Supported chat or Messages upstream]
    G --> T[Gateway metrics and usage events]

The diagram does not show local actions because they do not automatically pass through the model endpoint. If Codex reads a repository, runs a command, or calls an MCP server, the operating system, sandbox, network, and MCP configuration own those boundaries.

Prepare the AISIX Resources

The AISIX Codex integration requires:

• an AISIX proxy URL;
• a caller API key;
• a model alias that the key may access;
• a route that supports POST /v1/responses.

The caller key and provider key serve different actors. The caller key answers whether this Codex profile may use the selected gateway resource. The provider key authorizes AISIX to call the upstream. Keeping them separate lets the platform rotate or replace the provider credential without distributing it to every workstation.

Do not treat a shared key as verified employee identity. If several people use the same credential, gateway usage is attributable to that key, not provably to one person. Issue individual or workload-scoped credentials when revocation and attribution matter.

Configure Codex

Export the caller key in the environment that starts Codex:

export AISIX_API_KEY="YOUR_AISIX_CALLER_KEY"

Then configure the provider in ~/.codex/config.toml:

model = "gpt-6-sol" # An AISIX alias recognized by this Codex version.
model_provider = "aisix"

[model_providers.aisix]
name = "AISIX AI Gateway"
base_url = "https://ai-gateway.example.com/v1"
env_key = "AISIX_API_KEY"
wire_api = "responses"

The URL includes /v1 and omits the trailing slash. Current Codex releases require a compatible Responses endpoint for custom providers; a Chat Completions-only endpoint is not sufficient.

If the gateway uses a custom name such as company-coding-model, the official Codex gateway rollout guide requires a compatible model_catalog_json. The catalog supplies context limits, reasoning options, instructions, and tool capabilities. It replaces the bundled catalog, so it must contain every model users need, and it must match the installed Codex version. A route can reach the intended upstream while Codex still behaves incorrectly if the alias lacks accurate catalog metadata.

For production credentials, Codex also supports a command-backed token resolver. Do not combine that auth block with env_key; test token refresh and failure behavior before managed rollout.

Verify More Than a Text Reply

Start Codex from the configured environment and ask a short question. Verify both sides:

• Codex renders the response incrementally.
• AISIX records POST /v1/responses for the expected caller and alias.

Then test the required contract from the official Codex gateway checklist:

A health endpoint, /v1/models, or a single non-streaming response does not establish this contract. Test with the same Codex surface and configuration layer that developers will use.

Native Responses and Translation Are Different Products

AISIX can route Responses traffic to a native Responses-capable provider or translate it to another supported provider protocol. Translation can extend provider choice, but it is not feature equivalence.

For every alias, record:

• inbound and upstream protocols;
• supported text, image, reasoning, and function-tool behavior;
• streaming and continuation behavior;
• hosted-tool support;
• context and output limits;
• retry and fallback ownership;
• known unsupported fields.

AISIX 1.6.0 improved bridge behavior, including streamed Claude tool calls reaching OpenAI-protocol clients and reasoning moving across Messages/chat bridges. Those release changes are version-specific. They do not prove that every model, adapter, hosted tool, or provider-specific field behaves like a native Responses implementation.

Hosted tools are a particularly clear boundary. A gateway may preserve custom function calls while dropping a provider-hosted tool such as web search on a translated path. If a workflow depends on such a tool, test it explicitly or keep that alias on a native path.

Test Failure Timing and Retry Ownership

An HTTP 200 at stream start is not proof that the turn completed. AISIX 1.6.0 records streamed requests when the stream ends and assigns terminal outcomes such as client cancellation, upstream break, or timeout. Codex still needs the gateway to return a useful Responses error rather than an unexplained disconnect.

Run these counterexamples:

Retries may exist in Codex, AISIX routing, a provider SDK, or another intermediary. Define which layer owns which failure. Otherwise one transient error can multiply into several upstream attempts and unexpected cost. A guardrail refusal should not be retried as though it were a dropped connection.

Apply Controls Without Overclaiming Them

Once compatibility is stable, add the controls required by the rollout:

• scope each caller API key to approved models;
• keep provider credentials on AISIX and rotate them independently;
• set request, token, or concurrency limits for the actual workload;
• attach guardrails only after testing their input, output, stream-buffer, and fail-open/fail-closed behavior;
• monitor requests, attempts, fallback, latency, usage events, and configuration health;
• configure budgets only in the product and deployment mode that provides the required budget behavior.

None of these controls appears merely because traffic passes through AISIX. An unattached guardrail scans nothing. A shared key does not create per-developer attribution. A model alias does not equalize model quality, price, context, or tools.

Keep Explicit Non-Claims

A Codex proxy does not by itself guarantee that:

• every Codex feature works with every upstream;
• a custom alias has correct Codex capabilities without matching catalog metadata;
• local files, shell commands, network calls, or MCP traffic pass through AISIX;
• a caller-controlled identifier is trusted identity;
• gateway token or cost data exactly matches a provider invoice;
• a blocked output prevents an upstream side effect or charge;
• retries occur only once across all layers.

These are separate contracts owned by different systems. Keep each limitation beside the feature it constrains.

Roll Out One Tested Profile First

The smallest useful pilot is one isolated Codex profile, one scoped AISIX credential, and one approved model. Configure the custom provider, verify the request in both Codex and AISIX, then run streaming, continuation, tool, error, policy, and retry tests.

Only after that matrix passes should the platform distribute configuration and credentials more broadly. Start with the AISIX Codex integration, and use the official Codex gateway compatibility requirements as the client-side acceptance contract.