Claude Code API gateway setup: verify the protocol first
Claude Code does support LLM gateways, but an OpenAI-compatible URL alone is not enough. Anthropic’s current gateway protocol selects the Anthropic Messages format with ANTHROPIC_BASE_URL and sends inference to /v1/messages. Confirm that route, credentials, headers and model discovery before editing a production setup.
What does Claude Code expect from a gateway?
For the Anthropic Messages format, Anthropic documents ANTHROPIC_BASE_URL as the selector. Claude Code calls /v1/messages; /v1/messages/count_tokens is optional. The gateway must preserve anthropic-version and anthropic-beta when the upstream requires them.
What did we verify on MonkeyAI?
On 2026-08-02, a redacted production probe reached POST https://monkeytheme.com/v1/messages with an invalid test credential. The server returned HTTP 401 and structured JSON with INVALID_API_KEY. The same no-credential check on /v1/models returned HTTP 401 with API_KEY_REQUIRED.
| Check | Observed result | What it proves |
|---|---|---|
GET /v1/models, no key | 401 JSON | The route is reachable and enforces authentication |
POST /v1/messages, invalid x-api-key | 401 JSON | The Messages path and key boundary are reachable |
| Valid Claude Code session | Not run in this audit | No claim about full tool-use or streaming compatibility |
Set the base URL and credential deliberately
Anthropic separates routing from authentication. ANTHROPIC_BASE_URL points Claude Code at the gateway. A gateway credential variable or apiKeyHelper replaces the saved claude.ai subscription credential for that session. Setting only the base URL does not replace the saved login.
export ANTHROPIC_BASE_URL="https://monkeytheme.com" export ANTHROPIC_AUTH_TOKEN="***" claude
This is the documented variable shape, not a guarantee that every MonkeyAI account or model group supports Claude Code. Use a real key from your own dashboard, keep it out of shell history where possible, and verify the selected model before relying on the setup.
Check headers and model discovery
| Item | Gateway requirement |
|---|---|
Authorization / x-api-key | Accept the credential header Claude Code sends for the configured credential method |
anthropic-version | Preserve the API version expected by the upstream format |
anthropic-beta | Forward unchanged; Anthropic warns against allowlisting fixed beta values |
/v1/models | Serve directly if using gateway model discovery; redirects or slow responses can fail silently |
Anthropic’s protocol reference says discovery uses a bearer token when ANTHROPIC_AUTH_TOKEN is set; otherwise it uses the resolved API key in x-api-key. A gateway that supports helper-based discovery must accept x-api-key.
Use a bounded validation sequence
- Confirm that your account can see a Claude-family model in
/v1/models. - Confirm that the gateway supports Anthropic Messages, not only OpenAI Chat Completions or Responses.
- Start Claude Code in a fresh shell with the base URL and credential set.
- Run one small prompt before testing tools, streaming or long contexts.
- If it fails, record the HTTP status, UTC time, model, request ID and whether any stream event arrived.
If the gateway only supports OpenAI-compatible requests, use an OpenAI-compatible client such as Cline or Roo Code instead of forcing Claude Code across the wrong protocol.
Official sources
FAQ
Can Claude Code use any OpenAI-compatible gateway?
No. Claude Code’s documented gateway modes use Anthropic Messages, Bedrock or Google Cloud formats. An OpenAI-compatible URL by itself does not prove compatibility.
Which variable points Claude Code at an Anthropic-format gateway?
ANTHROPIC_BASE_URL. A separate gateway credential or apiKeyHelper controls authentication.
Does setting ANTHROPIC_BASE_URL replace my claude.ai login?
No. Anthropic states that the base URL alone changes routing but does not replace a saved subscription credential.
Does MonkeyAI /v1/messages work?
The unauthenticated production probe reached the route and returned structured 401 JSON. A valid-key end-to-end Claude Code session was not run, so full compatibility is not claimed.
What should I use if the gateway only supports OpenAI-compatible requests?
Use a client with explicit OpenAI-compatible provider support, such as Cline or Roo Code.