Claude Code

Quick

Claude Code is a client of the Anthropic protocol, so its base URL is the bare origin, with no `/v1`: the client appends /v1/messages itself.

Pick one of the two routes. Environment variables apply to every project in that shell; the settings file applies to a user (~/.claude/settings.json) or to a single repository (.claude/settings.local.json).

# ~/.zshrc — or whichever profile your shell reads
export KUMO_API_KEY="kumo_sk_..."
export ANTHROPIC_BASE_URL="https://api.kumorouter.com"
export ANTHROPIC_AUTH_TOKEN="$KUMO_API_KEY"
export ANTHROPIC_MODEL="<model>"

claude

The settings.local.json route carries the key itself, while the verify commands below read it from the KUMO_API_KEY variable: export the key once in the terminal you verify from.

Claude Code spends from the same wallet as a direct call — an empty wallet answers 402 (top it up).

Where the settings live

The settings file exists in two scopes, and both are legal at once.

• ~/.claude/settings.json — user settings, in effect for every project; a key belongs here fine. On Windows that is %USERPROFILE%\.claude\settings.json.
• .claude/settings.json inside a repository — settings shared by the whole team. This file is committed with the repository, so keep only non-secret values in it — never a key.
• .claude/settings.local.json inside a repository — your personal settings for this repository, and the right place for a key. Claude Code excludes this file from Git itself; if you create it by hand, add .claude/settings.local.json to .gitignore yourself.

The file may not exist yet — create it. If it does exist, merge the env block into it rather than replacing the file: your other settings usually sit beside it.

A key in a file is a key on disk: keep it only in settings.local.json or in an environment variable, never in a committed .claude/settings.json.

Choosing the model

ANTHROPIC_MODEL sets the main model. Take the identifier from the catalog — the models page or the gateway's own answer at https://api.kumorouter.com/v1/models.

Claude Code has a separate variable for the auxiliary, small-and-fast model, and different releases name it differently: ANTHROPIC_SMALL_FAST_MODEL or ANTHROPIC_DEFAULT_HAIKU_MODEL. Check the docs of the release you have installed and set the one it names; the other is simply not read.

With no model set at all, the client asks for its release's default — an identifier the catalog may not carry. Name the model explicitly instead.

Verify

Check the gateway first, then the client. That way a wrong key is distinguishable from a wrong Claude Code setting.

# 1. The gateway answers on the Anthropic protocol
curl https://api.kumorouter.com/v1/messages \
  -H "x-api-key: $KUMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "max_tokens": 64,
    "messages": [{ "role": "user", "content": "reply with OK" }]
  }'

# 2. The client goes to the same place — new terminal, empty directory
claude -p "reply with OK"

The x-api-key header is the native Anthropic carrier; the same key also travels as Authorization: Bearer. The whole rule is on the authentication page.

The call shows up in the console log: an answer with no log line means the client did not go through the gateway.

When it does not work

• 401 — the key. It is revoked, expired or malformed; or ANTHROPIC_AUTH_TOKEN never reached the process and the client fell back to the next credential in the Authentication precedence order — ANTHROPIC_API_KEY, or your own Claude Code login — which the gateway does not know. The gateway deliberately does not say which — why.
• The answer is not coming from Kumo — CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX or CLAUDE_CODE_USE_FOUNDRY is exported. That choice ranks above both key variables, so the client goes to the provider cloud instead of the gateway. Unset the variable and confirm the active source with /status.
• 404 — the address. /v1 got into ANTHROPIC_BASE_URL and the client appended its own, producing a path with v1 twice. Take the version segment out of the base URL.
• Model not found — the identifier is not from the catalog. Ask the gateway for the list and use a canonical name or an alias.
• Settings did not apply — the session was opened with the old values. Close it and open a new terminal.
• An answer came back, the log is empty — the variables never reached the process: check that the profile you edited is the one your shell actually reads.

Every status the gateway returns → Spend and logs →