The task looked like a five-minute job: point Claude Code at a compatible endpoint instead of the native Anthropic API. I set the environment variables in the morning and spent the evening figuring out why the CLI stayed silent.
What follows is five places where the connection breaks. Not "how to set it up" — "why it is not working", because the second question is the one people search at 3 a.m. Every error below was reproduced on a live setup; the configs are at the end.
What a compatible endpoint actually is
Claude Code is an ordinary HTTP client. It does not "integrate with Anthropic"; it sends a POST to /v1/messages in the Anthropic Messages API shape and reads an SSE stream. All it needs is a server that answers in that shape. The native Anthropic API is just one option.
That is the first fork in the road, and where people get lost: compatibility comes in two flavours. OpenAI-compatible (/v1/chat/completions) and Anthropic-compatible (/v1/messages). Claude Code needs the second. Cursor, Cline and Codex mostly need the first. A gateway that only speaks OpenAI is useless for Claude Code, no matter how many models it lists.
Trap 1: /v1 in the base URL
The most common one. OpenAI-compatible SDKs expect base_url = https://host/v1, and the client appends /chat/completions. Claude Code does the opposite: ANTHROPIC_BASE_URL takes the host without /v1, and it appends /v1/messages itself.
Set https://host/v1 and you get a request to /v1/v1/messages and a 404 that shows up in the client log as "model not found" or "invalid request", because the request body itself was valid.
Rule of thumb: two different base URLs for two protocols. Use the same one everywhere and one of the two will break.
Trap 2: ANTHROPIC_AUTH_TOKEN versus ANTHROPIC_API_KEY
Claude Code can authenticate two ways:
-
ANTHROPIC_API_KEY→ thex-api-keyheader; -
ANTHROPIC_AUTH_TOKEN→ theAuthorization: Bearer …header.
Gateways usually accept one of the two. The key itself can be perfectly valid and the answer is still 401. One command tells you which:
curl -s -o /dev/null -w "%{http_code}\n" https://host/v1/models \
-H "x-api-key: $KEY"
If you only get 200 with Authorization: Bearer, you need ANTHROPIC_AUTH_TOKEN, not ANTHROPIC_API_KEY. And vice versa.
A variant of the same problem: a native Anthropic key instead of the gateway key. Same 401, but the error text usually tells you which endpoint produced it.
Trap 3: model names
Claude Code picks the model from environment variables:
export ANTHROPIC_MODEL="..."
export ANTHROPIC_DEFAULT_SONNET_MODEL="..."
export ANTHROPIC_DEFAULT_OPUS_MODEL="..."
The name has to exist in the gateway catalog character for character. claude-sonnet-4-6 from Anthropic docs and claude-sonnet-5-5 from a provider are two different identifiers, and the second is under no obligation to be an alias of the first.
Check it with the same GET /v1/models: the response must contain exactly the id you typed. If it does not, the CLI either gets a 404 on the model or silently falls back to the gateway default. The second is worse: it works, just not on the model you think.
Trap 4: streaming that is "sort of supported"
Claude Code streams over SSE on /v1/messages. That works almost everywhere.
It breaks where a tool calls /v1/responses (Codex CLI, some assistants) and the gateway either does not implement that path or implements it without streaming, answering 400 to stream: true. The error text is usually useless, so test it up front: curl with "stream": true against the path you need, before you point a production task at the tool.
The practical takeaway: "OpenAI-compatible" ≠ "supports everything OpenAI does". Compatibility of request shape and compatibility of behaviour are two different things.
Trap 5: billing and limits
An agent is not a chat. It makes dozens of calls per task, drags context around and happily re-reads files. Without an upper bound on spend, one refactoring run eats the balance and you find out from an email.
What the gateway side needs in order to fix this:
- a per-key limit (in money or tokens), separate from the account balance;
- distinguishable 402 and 429 — "out of money" and "too many requests" need different reactions, and collapsing them into one "error" is a bad idea;
- a log with model, tokens and price at the time of the request, not "approximately".
Diagnostic checklist
-
curl $BASE/v1/modelswith your key → 200 and a model list. If not, the problem is auth or the address, and Claude Code is still far away. -
claude /status→ shows the base URL and the models the CLI actually uses. - One short request → a log line with tokens. No line means the request never arrived.
- 401 → key or header form. 402 → balance or key limit. 403 → model not allowed for the key, or IP not on the list. 429 → rate. 404 on a model → the name.
The full config
Through the shell:
export ANTHROPIC_BASE_URL="https://llmcode.io"
export ANTHROPIC_AUTH_TOKEN="sk-llmcode-..."
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-5-5"
claude /status
Through ~/.claude/settings.json — more reliable, it survives a new terminal tab:
{
"env": {
"ANTHROPIC_BASE_URL": "https://llmcode.io",
"ANTHROPIC_AUTH_TOKEN": "sk-llmcode-...",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5-5"
}
}
A step-by-step version with the response codes explained lives in the Claude Code guide (RU), and the compatible-endpoint overview with published per-token prices is here.
Full disclosure: I run LLMcode, the gateway used in the examples above. It is a prepaid balance with a per-key spend cap, crypto top-up, and both API shapes behind one URL — no card, no subscription. The traps above are the same for any gateway, including this one, which is why they are worth checking before you commit to a provider.
What this is not
A compatible endpoint is not native access. Latency and limits depend on the upstream, not on your code, and nobody gives Anthropic-grade SLA guarantees there. If the tool is critical in production, the behavioural difference between a channel and the native API is a risk to price in before migration, not after.
There is exactly one upside: one key and one bill for every tool that lets you change the base URL. For local development, agents and scripts that is usually enough.
Top comments (0)