Connect Codex to 9Router

Configure Codex with a 9Router provider in config.toml, a base URL ending in /v1, and wire_api = "responses". Use the exact model ID or combo name from your running router. Keep a backup of your existing Codex configuration before applying a dashboard-generated setup.

Older 9Router documentation includes a config.json example. The current upstream settings writer reviewed for this guide writes config.toml. Mixing those instructions can leave you editing a file that the client is not using.

Check the two sides of the connection

Codex is the client in this guide. The provider behind 9Router can be a separate service. A Codex client installation, a provider subscription, and router credentials are three different parts of the setup.

Before changing Codex, make sure 9Router passes the local endpoint checks. Choose a provider and model that can handle the Responses API behavior required by your client. OpenAI-compatible chat completion support alone does not establish that every Responses API or coding feature works.

Record your installed Codex and 9Router versions. Model names and supported settings change. The goal of the first test is a complete response with a traceable route, not an unattended coding job.

Preserve the existing TOML file

Codex commonly uses ~/.codex/config.toml; an installation with a custom configuration location may differ. Copy the existing file to a new backup filename. Do not print the whole file in logs or paste it into an issue because it can contain private endpoints or credentials.

Keep unrelated configuration sections. In TOML, a new field belongs to the most recently opened table. Pasting provider fields at the end of an unrelated table can change their meaning without producing an obvious syntax error.

If you already use named profiles, preserve them. A separate routing profile makes it easier to switch back. Read the configuration generated by your installed router before letting it replace a default model selection.

Review the generated provider settings

In the 9Router dashboard’s CLI tools area, choose Codex, set the local endpoint, and choose an available model. The current writer generates a provider section equivalent to this structural example:

model = "YOUR_EXACT_MODEL_ID"
model_provider = "9router"

[model_providers.9router]
name = "9Router"
base_url = "http://localhost:20128/v1"
wire_api = "responses"
http_headers = { Authorization = "Bearer YOUR_ROUTER_KEY" }

The two uppercase values are placeholders. Insert the key and model from your own instance. The key authenticates the client to 9Router; it is not necessarily your upstream provider’s API key.

This example follows the reviewed upstream writer’s static-header method. That writer explicitly places an Authorization header on the custom provider. Do not assume that signing in through another authentication path automatically supplies the required key to this custom endpoint.

Treat a file containing a static header as a credential file. Keep it outside public repositories and redact it before sharing diagnostics. This Wiki never needs to receive your configuration or key.

For a profile-based setup, consult the installed Codex configuration reference and preserve your current default. The router also contains profile helpers, but verify the generated profile in your actual version rather than assuming every release has the same UI.

Verify a short request

Restart the Codex process after applying the configuration. Start a fresh session in a scratch directory and ask a short factual question. Do not use a private repository for the first test.

Check the active model and provider in the client, then check the matching router request. If Codex returns text but 9Router has no corresponding request, the session may still be using a different profile or an older process environment.

The expected result is one complete response through the chosen router instance. This does not establish that image input, long contexts, tool calls, or every reasoning mode work. Test each feature you intend to use with a small example and keep ordinary tool approvals enabled.

For coding, a useful second check is reading a small local test file. Confirm that the assistant receives the file contents and responds normally. Stop before allowing broader file changes until the route behaves as expected.

Separate configuration errors from model errors

A request to /responses returns 404: inspect the complete endpoint and installed router version. Confirm the /v1 base path and Responses support. Do not switch to a chat-completion wire format merely to hide the error; the client and server must agree on the protocol.

A request returns 401 or 403: identify whether the rejection came from the router or upstream provider. Verify the custom provider’s authentication configuration and check whether the provider connection is still valid.

A request returns model not found: copy the exact model ID again from the router. Provider prefixes, combo names, and display labels are not interchangeable.

A session hangs after a tool call: a short text response was an incomplete compatibility test. Inspect streaming and tool-result handling, then try a known supported model before adding another routing layer.

Switch back safely

End the test session. Restore the backed-up TOML or select the original profile, then open a new session and verify the original provider. If you changed shell environment variables as well, restore those values too.

Keep a small record of the working client version, router version, model ID, and configuration method. Avoid storing keys in that record. When the basic route works, add a fallback combo and test it separately.

Can I reuse an OpenAI-compatible chat configuration?

Not without checking its wire format. Codex’s configured Responses path and a Chat Completions-only endpoint are different API contracts. A server that answers a generic chat request may still reject the request shape used by the coding client. Keep the provider configuration in TOML, verify the exact base URL, and test a short task before using a large repository.

What should I record before switching gateways?

Keep the working provider ID, base URL, model identifier, and a backup of the client configuration. Change one route at a time and verify the selected provider in a fresh session. Compare the same harmless task after switching, including tool-call behavior and streaming. The OmniRoute comparison describes a separate-instance evaluation, while OpenRouter with 9Router explains hosted versus local routes.