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

# Claude Code Router: Run Claude Code on Any Model

> Route Claude Code through Opper instead of a local proxy and run it on 300+ models — one API key, provider rates, model fallbacks, and EU-hosted routes.

Claude Code talks to `api.anthropic.com` by default, but it ships with built-in gateway support: point `ANTHROPIC_BASE_URL` at Opper and the same harness runs on any of [300+ models](/capabilities/models) — Anthropic, OpenAI, Google, Kimi, DeepSeek, and more — with one API key, one bill at provider rates, configurable fallbacks, and per-session cost tracking.

Unlike proxy tools such as [claude-code-router](https://github.com/musistudio/claude-code-router), there is nothing to run on your machine: no local server, no router config file to maintain. Claude Code speaks its native protocol directly to Opper's [Anthropic-compatible endpoint](/v3-api-reference/compatibility/create-message), and the routing happens server-side in the gateway.

## Prerequisites

* Node.js ≥ 20.12 (`npx` works without a global install)
* [Claude Code](https://claude.com/claude-code) installed
* An Opper account — free to create; the login step below opens sign-up if you don't have one

## Quick start

```bash theme={null}
npx @opperai/cli login    # one-time OAuth sign-in in your browser
npx @opperai/cli launch claude
```

`launch claude` sets `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN` for the session and starts Claude Code — no config files, nothing else to run. Install globally with `npm i -g @opperai/cli` if you prefer `opper` on your PATH; verify your login anytime with `opper whoami`.

<Note>
  If you were previously signed in to Claude Code with an Anthropic account, run `/logout` inside Claude Code once so cached credentials don't conflict with the gateway, then confirm with `/status` that the Opper base URL is active.
</Note>

## Switch the model

Pass any model from the [catalog](https://opper.ai/models) with `--model`, using full model IDs:

```bash theme={null}
opper launch --model openai/gpt-5.4 claude
opper launch --model alibaba:global/kimi-k2.7-code claude
```

Anything after the agent name is forwarded to Claude Code verbatim:

```bash theme={null}
opper launch claude --resume
```

## Manual configuration (without the CLI)

Claude Code's own environment variables work directly against Opper's Anthropic-compatible endpoint. Get an API key (`opper config get default` prints the key for your default credential), then:

```bash theme={null}
export ANTHROPIC_BASE_URL=https://api.opper.ai/v3/compat
export ANTHROPIC_AUTH_TOKEN=your-api-key
export ANTHROPIC_DEFAULT_OPUS_MODEL=anthropic/claude-opus-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=anthropic/claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=gemini/gemini-3.5-flash
claude
```

The `ANTHROPIC_DEFAULT_*` variables map Claude Code's model aliases, and any full ID from the catalog works in each slot — so `/model sonnet` can resolve to a non-Anthropic model entirely:

| Variable                         | Controls                        |
| -------------------------------- | ------------------------------- |
| `ANTHROPIC_DEFAULT_OPUS_MODEL`   | The `opus` alias                |
| `ANTHROPIC_DEFAULT_SONNET_MODEL` | The `sonnet` alias (main model) |
| `ANTHROPIC_DEFAULT_HAIKU_MODEL`  | The `haiku` alias               |
| `CLAUDE_CODE_SUBAGENT_MODEL`     | Model used for subagents        |

<Note>
  `ANTHROPIC_SMALL_FAST_MODEL` is deprecated in Claude Code; use `ANTHROPIC_DEFAULT_HAIKU_MODEL` for the background model.
</Note>

To route a single project through Opper while others keep using your Anthropic subscription, put the same keys in that project's `.claude/settings.local.json` instead of your shell profile:

```json theme={null}
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.opper.ai/v3/compat",
    "ANTHROPIC_AUTH_TOKEN": "your-api-key",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "anthropic/claude-sonnet-5"
  }
}
```

### Show gateway models in the /model picker

Claude Code can populate its `/model` picker from the gateway's [model list](/v3-api-reference/compatibility/list-models):

```bash theme={null}
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1
```

Discovered models appear in the picker labeled "From gateway"; any catalog ID also works directly via `--model` or the env vars above. Alternatively, pin a single custom entry with `ANTHROPIC_CUSTOM_MODEL_OPTION` (plus `_NAME` and `_DESCRIPTION`).

## Claude Agent SDK and CI

The same environment variables route the [Claude Agent SDK](https://docs.claude.com/en/api/agent-sdk/overview) through Opper. In CI — GitHub Actions, for example — set the base URL in the workflow and keep the key in a secret:

```yaml theme={null}
env:
  ANTHROPIC_BASE_URL: https://api.opper.ai/v3/compat
  ANTHROPIC_AUTH_TOKEN: ${{ secrets.OPPER_API_KEY }}
```

## Keep inference in the EU

Opper's gateway is hosted exclusively in the EU — the only thing that leaves is the model call itself, and you control where that goes. Pick an EU-hosted model from the [catalog](https://opper.ai/models) (marked in the list, e.g. `mistral/mistral-large-2512`) and your coding sessions never leave the EU. See [Keep data in the EU](/overview/gateway#keep-data-in-the-eu) for how routing restrictions are enforced at the gateway.

On a network that only allows egress to the gateway, also set `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` — it turns off Claude Code's nonessential background traffic to Anthropic and third-party services (version checks, telemetry, error reports), which would otherwise show up as blocked connections in egress monitoring.

## Coming from OpenRouter or claude-code-router?

* **From OpenRouter** — same mechanism, different base URL: set `ANTHROPIC_BASE_URL=https://api.opper.ai/v3/compat` and pass your Opper key as `ANTHROPIC_AUTH_TOKEN`. You gain EU-hosted routing, inference at provider rates, and per-call [tracing](/control-plane/trace).
* **From claude-code-router** — the open-source proxy runs locally and needs its own config file and process. With Opper the router runs server-side: the two env vars above are the entire setup, and they work anywhere Claude Code runs, including CI.

## What changes compared to Anthropic direct

* **Billing.** Routed sessions are billed as API usage through Opper at [provider rates](https://opper.ai/pricing). A Claude Pro or Max subscription does not apply while a gateway credential is active.
* **Model IDs.** The `opus` / `sonnet` / `haiku` aliases resolve through the `ANTHROPIC_DEFAULT_*` mapping; for everything else use full IDs from the catalog.
* **Feature parity.** Some Anthropic-endpoint conveniences ([prompt caching](/build/gateway/prompt-caching) among them) depend on the route serving your request. Anthropic documents the gateway mechanism but does not officially support non-Claude models in Claude Code, so expect polish to vary by model — frontier models and strong open-weight tool-callers work well in practice.
* **Reliability.** Opper aliases can define [backup chains](/capabilities/models#aliases-and-backup-chains): if the primary model fails or a provider has an outage, the call falls through to the next model in the chain.

## Troubleshooting

* **"Model not found"** — use the full model ID exactly as listed in the catalog; aliases only resolve through the `ANTHROPIC_DEFAULT_*` mapping.
* **Auth errors** — run `opper whoami`; re-run `opper login` if the session expired. If Claude Code was previously signed in to an Anthropic account, `/logout` once and check `/status` shows the Opper base URL.
* **Context length errors** — context windows differ per model; check the catalog and pick a model sized for your session.
* **Checking spend** — every routed session is metered with per-call cost, latency, and token accounting in your [Opper dashboard](/control-plane/trace).