> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# Claude Code (gateway)

> Set up Claude Code with the Respan gateway.

Route Claude Code's LLM calls through the Respan gateway for automatic logging, caching, and model switching. Only your `RESPAN_API_KEY` is needed.

## Setup

#### Install Claude Code

```bash
npm install -g @anthropic-ai/claude-code
```

#### Set environment variables

Add to your shell profile (`.bashrc`, `.zshrc`, or PowerShell `$PROFILE`):

```bash
unset ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_BASE_URL="https://api.respan.ai/api/anthropic/"
export ANTHROPIC_API_KEY="YOUR_RESPAN_API_KEY"
```

Use `ANTHROPIC_API_KEY`, not `ANTHROPIC_AUTH_TOKEN`, for Claude Code through the Respan Anthropic gateway. Claude prefers `ANTHROPIC_AUTH_TOKEN` when both are set.

#### Or use Claude Code settings (persistent)

Add to `~/.claude/settings.json` for global config, or `.claude/settings.local.json` in your project for repo-local config:

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.respan.ai/api/anthropic/",
    "ANTHROPIC_API_KEY": "YOUR_RESPAN_API_KEY",
    "ANTHROPIC_AUTH_TOKEN": ""
  }
}
```

Setting `ANTHROPIC_AUTH_TOKEN` to an empty string clears any inherited token so Claude Code prefers `ANTHROPIC_API_KEY`. Run Claude Code as usual — all LLM calls will route through Respan.

> **Note**
>
> The Anthropic gateway path is `/api/anthropic/` (with trailing slash). For interactive Claude Code sessions, prefer shell env vars or `~/.claude/settings.json`. If `ANTHROPIC_AUTH_TOKEN` is exported by your shell or terminal app, Claude may still prefer it, so unset or remove it first. On first interactive launch, Claude may prompt: **Detected a custom API key in your environment**. Choose **Yes** to use the Respan API key. If you skipped it earlier, run `/config`, search for `custom`, and enable **Use custom API key**. Non-interactive `claude -p` and `claude --print` use `ANTHROPIC_API_KEY` automatically.

## Switch models

Once routed through the gateway, you can use any Claude model.

```bash
# In your shell
claude --model claude-sonnet-4-5-20250929
claude --model claude-haiku-4-5-20251001
```

See the [full model list](https://platform.respan.ai/platform/models).

## Pin requests to a specific provider

To route Claude Code to your Vertex AI throughput (or any other provider) without changing the model slug, set the `X-Respan-Route-Provider` header. Claude Code keeps using its standard slug and the gateway resolves the provider transparently:

```bash
export ANTHROPIC_CUSTOM_HEADERS="X-Respan-Route-Provider: vertex_ai"
```

For a fallback across providers (e.g. primary Vertex, fall back to Anthropic on failure), use `fallback_models` instead. See [Retries and fallback](/docs/documentation/features/gateway/retries).