> ## Documentation Index
> Fetch the complete documentation index at: https://developers.meshapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code

> Route Claude Code through Mesh to reach every model in the catalog, with your spend caps, rate limits and usage logging applied.

Claude Code talks the [Anthropic Messages API](/docs/capabilities/messages-api) to
whatever `ANTHROPIC_BASE_URL` points at. Point it at Mesh and every request runs
through the same gateway as the rest of your traffic — spend caps, per-key rate
limits, usage logging and retry/fallback all apply, with no change to how you use
the tool.

<Info>
  Because `/v1/messages` is **not restricted to Anthropic models**, this also lets
  Claude Code run against any model in the Mesh catalog.
</Info>

## Configuration

Add this to `~/.claude/settings.json` (or a project's `.claude/settings.json`):

```json theme={null}
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.meshapi.ai",
    "ANTHROPIC_AUTH_TOKEN": "rsk_YOUR_KEY",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "anthropic/claude-opus-4.8",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "anthropic/claude-sonnet-4.6",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "anthropic/claude-haiku-4.5"
  }
}
```

All three model variables matter. Claude Code picks a model per task, and any
variable you leave unset falls through to a Claude Code default id that Mesh may
not serve (see §2 below).

<Note>
  **Mesh's canonical ids use dots.** Mesh serves `anthropic/claude-sonnet-4.6`.
  Anthropic's native hyphenated form (`claude-sonnet-4-6` or
  `anthropic/claude-sonnet-4-6`) is mapped to the dotted id when exactly one catalog
  model matches it, but suffixes Claude Code adds, such as `[1m]`, are not. Copy
  the ids exactly as written above, or from [Models & Pricing](https://meshapi.ai/models).
</Note>

## The three things that catch people out

### 1. If you are signed in to Claude Code, `ANTHROPIC_AUTH_TOKEN` is ignored

This is the most common failure, and the error does not hint at the cause:

```
Failed to authenticate. API Error: 401 Invalid or missing API key.
```

A signed-in Claude Code prefers its stored credential over the environment
variable, so it sends that credential to Mesh — which correctly rejects it as not
being a Mesh key.

Use a separate config directory so the CLI has no stored login to prefer:

```bash theme={null}
CLAUDE_CONFIG_DIR=~/.claude-mesh claude
```

Wrap it in a shell alias if you switch between the two regularly:

```bash theme={null}
alias claude-mesh='CLAUDE_CONFIG_DIR=~/.claude-mesh claude'
```

Signing out of Claude Code also works, but costs you the direct-Anthropic setup.
A second config directory keeps both.

### 2. `ANTHROPIC_DEFAULT_OPUS_MODEL` is not optional

Claude Code's default model is Opus. Set only Sonnet and Haiku and the first
request fails:

```
There's an issue with the selected model (claude-opus-4-8[1m]).
It may not exist or you may not have access to it.
```

Note the `[1m]` suffix Claude Code appends for its long-context variant — another
reason to map the variable explicitly rather than relying on a default.

### 3. Haiku carries real traffic

`ANTHROPIC_DEFAULT_HAIKU_MODEL` is easy to skip because you never select Haiku
yourself. Claude Code uses it for background work — conversation titles,
summaries — so leaving it unset sends a steady trickle of requests to an id Mesh
does not serve. In a short verification session, roughly a third of the requests
were Haiku.

## Verify it works

```bash theme={null}
CLAUDE_CONFIG_DIR=~/.claude-mesh claude -p 'Say OK'
```

Then confirm the traffic actually reached Mesh — this is the check that
distinguishes "configured" from "working", since a misconfigured client can still
answer from a direct Anthropic connection:

<Tabs>
  <Tab title="Dashboard">
    Open [Usage](https://app.meshapi.ai/usage). Requests from Claude Code appear under
    the key you configured, with the model ids you mapped.
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    curl https://api.meshapi.ai/v1/usage/events \
      -H "Authorization: Bearer rsk_YOUR_KEY" \
      -H "Content-Type: application/json" \
      -d '{"org_id": "YOUR_ORG_ID", "limit": 5}'
    ```

    `org_id` is required by the request schema; with an API key, results are scoped to
    that key regardless. Look for recent rows whose `model` is one of the ids you mapped.
    See [Usage API](/docs/reference/usage-api).
  </Tab>
</Tabs>

## Model discovery (optional)

Claude Code can populate its `/model` picker from the Mesh catalog instead of its
built-in list:

```json theme={null}
{
  "env": {
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
  }
}
```

Two caveats:

* Discovery calls `GET /v1/models`, which accepts **`Authorization: Bearer` only** —
  not `x-api-key`. With `ANTHROPIC_AUTH_TOKEN` (as configured above) this is
  already correct; if you switch to `ANTHROPIC_API_KEY`, inference keeps working
  but discovery returns 401.
* The catalog is large — the response covers the full model list and is fetched
  on start-up.

## What runs through the gateway

Everything, which is the point of routing Claude Code this way:

| | |
| - | - |
| **Spend caps** | A Claude Code session cannot exceed the key's cap. BYOK-served requests count only their platform fee toward it |
| **Rate limits** | Per-key RPM/RPD apply |
| **Usage logging** | Every request is logged in your usage history |
| **Retry & fallback** | [Resilient routing](/docs/platform/retry-and-fallback) applies |
| **BYOK** | Your own provider keys are used when configured |

## Troubleshooting

| Symptom | Cause |
| - | - |
| `401 Invalid or missing API key` | Signed-in CLI overriding the token — use `CLAUDE_CONFIG_DIR` (§1) |
| `issue with the selected model (claude-opus-4-8[1m])` | `ANTHROPIC_DEFAULT_OPUS_MODEL` unset (§2) |
| `404 Model ... is not supported` | An ID Mesh can't map. Check it against [Models & Pricing](https://meshapi.ai/models) (`anthropic/claude-sonnet-4.6`) |
| Works, but no rows in Usage | Requests are not reaching Mesh — re-check `ANTHROPIC_BASE_URL` |
| `402` mid-session | Key's spend cap reached, or the account balance is exhausted |

## Related

* [Messages API](/docs/capabilities/messages-api) — the endpoint Claude Code uses
* [Models & Pricing](https://meshapi.ai/models) — exact ids for the model variables
* [Rate Limits](/docs/getting-started/rate-limits) — what applies to a session
* [Retry & Fallback](/docs/platform/retry-and-fallback) — behaviour on provider failure


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.