docs/guides/codex-claude-routing-guide-en.md
Applies to CC Switch 3.17.0 and later (the Anthropic Messages upstream was introduced in 3.17.0). This guide is based on the repository documentation and code, and uses a Claude-family relay gateway as the example. Screenshots are generated from the current frontend UI with de-identified sample data to avoid exposing a real API key.
The newer Codex CLI targets the OpenAI Responses API, while the various Claude-family relay gateways and internal enterprise gateways expose the Anthropic Messages protocol — that is, /v1/messages. These two protocols use completely different request bodies, streaming events, and response structures, so putting such a gateway's endpoint directly into Codex configuration can only result in a request to /responses coming back 404.
This feature targets the scenario where all you have is a /v1/messages endpoint: you have a key for some Claude-family relay gateway and want to run Claude-family models with Codex's interaction style; or your company has banned the Claude Code client for compliance reasons and kept only an approved Claude-family gateway — the model itself is available, and all that's missing is a permitted client, which Codex can now fill.
CC Switch's approach is to keep Codex always talking to the local route and still sending Responses API requests; once the route detects that the active provider is Anthropic-format, it converts the request into Anthropic Messages for the upstream, then converts the response back into the Responses shape it returns to Codex.
The chain has four main steps:
http://127.0.0.1:15721/v1, and wire_api = "responses" is forcibly kept in place.anthropic upstream format tells the route that the real upstream speaks the Anthropic Messages protocol./responses to /v1/messages and converts the Responses request body into an Anthropic request body.Prepare these three things first:
~/.codex/ directory structure exists./v1/messages) — from some Claude-family relay gateway, or an internal enterprise Claude gateway; follow the gateway's documentation for its endpoint and auth method. Note: some providers restrict their Claude API to Claude Code only, so such a key may error out when used through Codex — if you're unsure, check with your provider first.The Codex tab currently has no built-in Anthropic preset, so the steps below use the Custom Configuration path — just four or five fields from start to finish.
Open CC Switch, switch to the top-level Codex tab, click the plus button in the upper-right corner to add a provider, keep the default Custom Configuration, then fill in:
Claude Gateway.https://claude-gateway.example.com. It works with or without a trailing /v1 — the route sends requests to /v1/messages automatically; don't assemble /v1/messages yourself (if your gateway documentation gives you a complete messages URL, you can turn on the Full URL toggle next to it and paste it verbatim). The yellow hint below the address bar, "compatible with OpenAI Response format", is generic copy written for the direct Responses scenario; when you choose the Anthropic format, just fill it in as this guide describes.claude-sonnet-5; follow the model names in the gateway's documentation.Then expand Advanced Options and change Upstream Format from the default Responses (native) to Anthropic Messages (routing required).
After selecting Anthropic Messages, three supporting fields appear below:
ANTHROPIC_AUTH_TOKEN (Authorization): sends Authorization: Bearer <key>. This is the default, and most Claude-family relay gateways use it.ANTHROPIC_API_KEY (x-api-key): sends x-api-key: <key>. Some gateways that follow Anthropic's native header convention require this. Picking the wrong one usually shows up as 401 / 403.anthropic-beta, and x-app headers and injects the Claude Code identity as the first line of the system prompt. Ordinary gateways don't need it; if you're still rejected after enabling it, see "FAQ".max_tokens is required, and when a Codex request carries no output ceiling the route falls back to a conservative 8192, which may truncate long answers or deep reasoning (showing up as an incomplete reply, stop_reason=max_tokens). If you hit truncation, raise this to the model's real ceiling here — but don't exceed it, or the upstream will 400 outright.The Model Mapping in the same area is optional: add model ids like claude-opus-4-8, claude-sonnet-5, and claude-haiku-4-5-20251001 (use the names your upstream recognizes) one per row, and CC Switch generates a model catalog so Codex's /model menu can list them; you can also leave it empty, in which case Codex just requests the default model.
After you save the provider, a Needs Routing marker appears on the card — providers like this only work while local routing is running.
Go to the Routing page in Settings, expand Local Routing, and complete two toggles:
Routing Master Switch to start the local service (the first time you enable it, an explanatory confirmation dialog appears). The default address is 127.0.0.1:15721.Codex under Routing Enabled. If you only want Codex to use routing, you can leave Claude and Gemini off.After takeover, CC Switch points Codex's live config at the local route (base_url = http://127.0.0.1:15721/v1), with only a placeholder in auth.json. The real Claude key stays in the CC Switch provider config and is injected by the local route on forward, using the auth field you selected.
Return to the Codex provider list and click Enable on the Claude provider. If routing isn't running, CC Switch shows "This provider uses Anthropic Messages API format, requires the routing service to work properly. Start routing first." — just go back to Step 2 and turn it on.
After switching, restart the current Codex terminal session: config.toml and the model catalog are read when the Codex process starts, and a running process isn't guaranteed to hot-load them.
Inside Codex you can verify step by step:
/model to check whether the Claude models now appear in the menu; without a mapping, Codex just uses the default model.claude-*, and you can filter by provider to reconcile token usage.[1m] long-context marker: when the default model or a model id in the mapping ends with [1m] (e.g. claude-sonnet-5[1m]), the route strips the marker and automatically adds the corresponding 1M-context beta header, provided the gateway supports that capability.web_search is deliberately disabled — the conversion layer can't translate it for the Anthropic endpoint, and disabling it avoids presenting the model with a tool that's guaranteed to fail.The upstream returns 401 or 403
Nine times out of ten the auth field doesn't match what the gateway wants: switch between ANTHROPIC_AUTH_TOKEN (Authorization) and ANTHROPIC_API_KEY (x-api-key) per your gateway's documentation and try again (most gateways use the default Bearer). Also confirm the key itself is valid and has balance.
Codex reports 404 or cannot find /responses
Usually Codex routing takeover isn't enabled, or you manually wrote the gateway's address directly into Codex — an Anthropic-protocol upstream has no /responses endpoint, so that always 404s. Check whether the current provider's base_url in ~/.codex/config.toml points to http://127.0.0.1:15721/v1.
The upstream returns 404 (routing already enabled)
Check the API Request URL: it should be the gateway's service root, not an address carrying another protocol's path such as /chat/completions. When the gateway path is unusual, use the Full URL toggle to paste the complete messages endpoint directly.
Replies often get cut off mid-way
This is the default 8192 output ceiling showing up. Raise it in Max output tokens under the provider form's Advanced Options (don't exceed the model's/gateway's real ceiling), save, and retry.
/model doesn't show the Claude models
Confirm you've added entries to the model mapping, then restart Codex after saving the provider — the model catalog isn't hot-loaded by a running process. When the default model isn't in the mapping, the menu won't list it, but a direct request still works.
Web search doesn't work
By design; see "Capabilities and known limitations". For tasks that need web search, switch back to a Responses/Chat-format provider.
An error says usage is restricted to Claude Code
Some providers restrict their Claude API to the Claude Code client, so it gets rejected when going through this guide's chain via Codex. Try turning on the Emulate Claude Code client toggle in Advanced Options; if it still errors after that, the restriction is enforced on the provider's side — check with your provider whether your key can be used outside Claude Code. Keep this toggle off for ordinary gateways.
Before using this in the "company bans the client but keeps only the gateway" scenario, it's worth confirming that doing so complies with your organization's specific policy — whether what's banned is a specific client or a manner of use differs from one place to the next. When using a third-party relay gateway, read the target gateway's terms on billing, compliance, and data retention.