How to use Claude Code with other models and a custom base URL
Claude Code sends every request to whatever ANTHROPIC_BASE_URL says, authenticates with ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY, and uses the model named in ANTHROPIC_MODEL. Point those at any server that speaks the Anthropic Messages protocol and Claude Code runs against it, with no fork or proxy. The one trap: the base URL is the bare host, without /v1, because the client appends /v1/messages itself.
How does Claude Code decide where to send requests?
Claude Code is an Anthropic Messages client. Each turn of the agent loop is a POST to <base>/v1/messages with the conversation, the system prompt and the tool definitions, and the response streams back as server-sent events. Nothing in that loop is tied to one host. The client builds the URL from a base, attaches a key, and names a model, and all three come from configuration you control.
That makes a gateway the simplest way to run Claude Code against a different model or a different bill: you don’t patch the tool, you change four environment variables. The same idea applies to OpenAI-style tools with OPENAI_BASE_URL; the OpenAI-compatible API guide covers that side, and the connect guide for Claude Code has the exact values for Smouter.
| Variable | What it does | Notes |
|---|---|---|
ANTHROPIC_BASE_URL | Host the client sends Messages requests to | Bare host only. The client appends /v1/messages. |
ANTHROPIC_AUTH_TOKEN | Sends the key as Authorization: Bearer <key> | The usual choice for gateways. |
ANTHROPIC_API_KEY | Sends the key as an x-api-key header | Works the same against Smouter; use whichever your setup already has. |
ANTHROPIC_MODEL | The main model for the agent loop | Copy the id exactly from the catalog. |
ANTHROPIC_SMALL_FAST_MODEL | Model for lightweight background calls | Optional. A cheaper id keeps background work cheap. |
Variable names in Claude Code have shifted between releases, and newer versions add finer-grained model overrides. The base URL and key variables have been stable; for anything model-related, check the settings reference for the version you run.
How do I point Claude Code at a custom base URL?
For a terminal session, export the variables and start claude from the same shell. With Smouter the host is https://api.smouter.ai, the key is an sk-smouter-... secret from your dashboard (see creating an API key), and the model is any id from the live models page.
export ANTHROPIC_BASE_URL="https://api.smouter.ai" # no /v1 here
export ANTHROPIC_AUTH_TOKEN="sk-smouter-..."
export ANTHROPIC_MODEL="<model-id>" # copied from /models
export ANTHROPIC_SMALL_FAST_MODEL="<model-id>" # optional, cheaper id
claudeHow do I set it for the desktop app or IDE extension?
Shell exports only reach processes started from that shell. An app launched from the dock or a launcher never sees them, so the desktop app and IDE integrations need the values in Claude Code’s own settings file. Put them in the env block of ~/.claude/settings.json and restart the app.
// ~/.claude/settings.json
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.smouter.ai",
"ANTHROPIC_AUTH_TOKEN": "sk-smouter-...",
"ANTHROPIC_MODEL": "<model-id>"
}
}Claude Code also reads project-level settings from a .claude directory in the repo. That is useful for pinning a model per project, but keep the key itself in your user-level file or a local, uncommitted settings file. A key in a committed file is a key in your git history.
How do I check the endpoint works before blaming Claude Code?
Test outside the tool first. If a plain request succeeds, your key, credit and model id are fine, and whatever remains is the tool’s configuration. The first command lists the model ids you can use; the second sends one Messages request shaped the way Claude Code sends it.
# Which model ids exist right now? (no auth needed)
curl -s https://api.smouter.ai/v1/models | jq -r '.data[].id'
# One Messages call with the same key and model Claude Code will use
curl https://api.smouter.ai/v1/messages \
-H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"<model-id>","max_tokens":64,"messages":[{"role":"user","content":"ping"}]}'If the curl call works and Claude Code still fails, confirm the variables reached the process: run echo $ANTHROPIC_BASE_URL in the same shell you launch from, or check the env block if you use the app. A stale value from an older shell profile is a frequent cause.
What works over the Messages endpoint, and what doesn’t?
Claude Code’s core loop runs entirely over Messages. Smouter implements that endpoint itself, including streaming, tool use and system prompts, so reading files, running commands, editing code and multi-turn sessions all go through it.
Some auxiliary Anthropic endpoints are not proxied, notably token counting and the files API. The agent loop doesn’t need them, but anything that calls them directly will fail against the gateway. If a feature of your setup depends on them, test it before you rely on it.
Gateway features ride along on every request. Responses carry receipt headers such as x-smouter-charge and x-smouter-cache when they are known, and you can pick a lane per request with x-smouter-lane. For a coding agent, the value vs verified lanes article explains the trade-off between the discounted sourcing pool and the model maker’s own endpoint under zero retention.
Can Claude Code use non-Claude models?
Yes, mechanically. On Smouter, any chat model in the catalog can be called on the Messages surface, so you can set ANTHROPIC_MODEL to an open-weight coder like the ones on the Qwen3 Coder or Kimi K3 pages and Claude Code will talk to it.
Whether it works well is a separate question, and the honest answer is that it varies. Claude Code’s system prompt, tool schemas and editing conventions were written for Claude models. Claude-family ids behave best inside it. Other models differ in how reliably they follow long tool-use instructions, format edits, and stop when a task is done. Some handle it well; some loop, emit malformed tool calls, or ignore the edit format. Treat a non-Claude model in Claude Code as something to evaluate on your own repo, not a drop-in swap.
- Start with a small, well-defined task (a refactor in one file, a failing test) and watch the tool calls, not just the final answer.
- Use
ANTHROPIC_SMALL_FAST_MODELfor the cheap background calls even if you keep a Claude model as the main one; that is the lowest-risk place to try a different model. - If a model is good at code but struggles with Claude Code’s harness, try it in an agent built around OpenAI-style tool calls instead, such as OpenCode or Codex CLI.
- Keep one key across tools so the comparison is on the same wallet and the same usage view.
The point of a gateway here is choice, not one particular model: one key, one wallet, and the freedom to change ANTHROPIC_MODEL without opening a new account. If you want the gateway to pick per request, model: "auto" and programmable routes exist; the model routing guide covers when that helps and when it confuses an agent that expects a stable model.
Why is Claude Code returning 404, 401, 402 or 429?
| Symptom | Likely cause | Fix |
|---|---|---|
| 404 on every request | ANTHROPIC_BASE_URL ends in /v1, producing /v1/v1/messages | Use the bare host, https://api.smouter.ai. |
401 auth error | Key pasted wrong, truncated, expired or revoked | Create a fresh key and paste it whole, including the sk-smouter- prefix. |
402 insufficient_quota | Wallet or a per-key spend cap can’t cover the request | Top up, or raise the key’s cap. See credits and top-ups. |
404 model_not_found | The model id doesn’t match the catalog | Copy the id verbatim from /models; ids are case-sensitive and take no vendor prefix. |
429 | A rate or tokens-per-minute window is exhausted | Honor retry-after; per-key TPM is adjustable. See rate limits and TPM. |
| Works in curl, fails in the app | The app never received the variables | Move them into the env block of ~/.claude/settings.json and restart. |
Two more causes worth checking. A key with a model allowlist rejects any model not on the list, including the small/fast model, so make sure both ids are allowed. And long agent sessions send large contexts, so a low per-key TPM cap shows up as 429s mid-task rather than at the start. The fallbacks guide covers how to handle 429s and outages in your own code; inside Claude Code, the fix is usually a higher cap on that key.
If you are stuck, keep the x-request-id from the failing response or the error body. It lets support trace the exact request. The full list of headers and error types is in the API reference.
What does running Claude Code through a gateway change about cost?
Claude Code is token-heavy: it re-sends the conversation and tool output on every turn. The model you pick for ANTHROPIC_MODEL and the one for background calls dominate the bill, and prompt caching on the repeated prefix matters more than anything else. The AI coding agents cost guide walks through a worked example and the levers in order of impact, and live prices per model are on the models page.
Frequently asked questions
Does ANTHROPIC_BASE_URL need /v1 at the end?
No. Claude Code appends /v1/messages to whatever base you give it, so the base must be the bare host, for example https://api.smouter.ai. Adding /v1 produces a doubled /v1/v1/messages path and a 404 on every request. OpenAI-style tools are the opposite and need the /v1 suffix.
Should I use ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY?
ANTHROPIC_AUTH_TOKEN sends the key as a bearer token in the Authorization header; ANTHROPIC_API_KEY sends it as x-api-key. Against Smouter both authenticate the same way, so use whichever your setup already has. Set only one of them to avoid confusion about which key a session is using.
Why do my environment variables not work in the Claude Code desktop app?
Apps launched from the dock or a launcher do not inherit exports from your shell profile. Put the same variables in the env block of ~/.claude/settings.json and restart the app. The IDE extensions read that file as well, so one settings block covers the app, the extensions and new terminal sessions.
Can I use GPT, DeepSeek or Qwen models inside Claude Code?
You can point ANTHROPIC_MODEL at any chat model a Messages-compatible gateway serves, and Smouter serves its whole chat catalog on that surface. Results vary: Claude Code’s prompts and tool schemas are tuned for Claude models, and other models differ in how reliably they follow its tool-use and edit conventions. Evaluate on a small task first.
Does token counting work when Claude Code uses a custom endpoint?
Smouter does not proxy Anthropic’s auxiliary endpoints such as token counting and files. Claude Code’s core agent loop runs entirely over the Messages endpoint, which Smouter implements with streaming, tool use and system prompts, so normal sessions work. Anything that calls those auxiliary endpoints directly will fail and needs testing before you rely on it.
What is ANTHROPIC_SMALL_FAST_MODEL used for?
It names the model Claude Code uses for lightweight background calls, separate from the main model in ANTHROPIC_MODEL. Pointing it at a cheaper id reduces the cost of that background traffic without changing the model doing the actual coding. Newer Claude Code releases add more model override variables, so check the settings reference for your version.