---
title: Claude Code
description: Three environment variables and Claude Code runs through the gateway. Plus the settings.json route, the key precedence to watch for, and a one-command check.
keywords: claude code, anthropic, ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, settings.json, cli
group: integrations
---

## Quick {#quick keywords="environment variables, settings.json, shell profile"}

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`).

:::code-group
```bash title=Shell
# ~/.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
```
```json title=.claude/settings.local.json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.kumorouter.com",
    "ANTHROPIC_AUTH_TOKEN": "<your key>",
    "ANTHROPIC_MODEL": "<model>"
  }
}
```
:::

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](/en/billing)).

:::note
Settings are read at start-up. A session that is already open keeps the old address until it is restarted: open a new terminal.
:::

## Where the settings live {#settings keywords="settings.json, settings.local.json, user, project, windows"}

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`.

:::warning
Rank 1 of that same Authentication precedence order is not either of these variables but the choice of a cloud source: `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_USE_FOUNDRY`. A machine with one of them exported routes past Kumo, whatever token you set. Clear them in the shell you work from: `unset CLAUDE_CODE_USE_BEDROCK CLAUDE_CODE_USE_VERTEX CLAUDE_CODE_USE_FOUNDRY` — and confirm the active source with `/status`.

Further down the same section of the Claude Code docs, `ANTHROPIC_AUTH_TOKEN` ranks above `ANTHROPIC_API_KEY`: the token is sent as `Authorization: Bearer`, the key as `X-Api-Key`, and while the token is set it wins, so requests go to the gateway. The Kumo side agrees from its own end: when both headers arrive, the gateway reads `Authorization`. Still, do not point the two variables at different providers: the moment the token fails to reach the process, the client quietly takes the next source, and the gateway will not accept a key that is not its own. Clear `ANTHROPIC_API_KEY` in the shell you use with Kumo: `unset ANTHROPIC_API_KEY` — or remove the export from your profile.
:::

## Choosing the model {#model keywords="ANTHROPIC_MODEL, small fast model, override"}

`ANTHROPIC_MODEL` sets the main model. Take the identifier from the catalog — the [models page](/en/models) 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 {#verify keywords="verify, curl, claude -p, 200"}

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

```bash title=Verify
# 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](/en/authentication).

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 {#troubleshooting keywords="401, 404, error, model not found"}

- **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](/en/errors).
- **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 →](/en/errors) [Spend and logs →](/en/usage)

:::cards
- [Codex CLI](/en/codex-cli) — the same thing for an OpenAI-compatible client.
- [Every recipe](/en/integrations) — the overview and the agent prompt.
- [Models](/en/models) — which identifiers to name.
:::