--- title: "Claude Code" description: "Point Claude Code at pirouter: set ANTHROPIC_BASE_URL to https://api.pirouter.ai (no /v1), ANTHROPIC_AUTH_TOKEN to your pirouter key, and pick models by hyphenated aliases such as claude-sonnet-5-5." canonical: "https://pirouter.ai/docs/integrations/claude-code" last-updated: "2026-10-18" lang: "en" source: "content/docs/en/integrations/claude-code.mdx" --- # Claude Code Point Claude Code at pirouter: set ANTHROPIC_BASE_URL to https://api.pirouter.ai (no /v1), ANTHROPIC_AUTH_TOKEN to your pirouter key, and pick models by hyphenated aliases such as claude-sonnet-5-5. [Claude Code](https://code.claude.com/docs/en/overview) runs on pirouter without a plugin. Set two environment variables, `ANTHROPIC_BASE_URL` to pirouter and `ANTHROPIC_AUTH_TOKEN` to your pirouter key, and name models by hyphenated aliases such as `claude-sonnet-5-5`. Claude Code speaks only the Anthropic protocol and sends its requests to `POST /v1/messages`. ## Prerequisites - A pirouter API key. If you do not have one, create it with the [quickstart](https://pirouter.ai/docs/quickstart.md) and store it in an environment variable: ```bash export PIROUTER_API_KEY="sk-pi-..." ``` - Claude Code v2.1.293 or later. Sonnet 5.5 needs v2.1.284, Opus 5.5 needs v2.1.280, and Haiku 5.5 needs v2.1.293. This page was verified on v2.1.302. * If Claude Code is not installed yet, run this on macOS, Linux or WSL: ```bash curl -fsSL https://claude.ai/install.sh | bash ``` On Windows, run `winget install Anthropic.ClaudeCode`. For other install methods, see the [Claude Code setup guide](https://code.claude.com/docs/en/setup). If it is already installed, run `claude update`. ## Configure Put this in `~/.claude/settings.json` and replace the `ANTHROPIC_AUTH_TOKEN` value with your pirouter key. If the file already has other settings, merge these entries into its `env` block: `~/.claude/settings.json`: ```json { "env": { "ANTHROPIC_BASE_URL": "https://api.pirouter.ai", "ANTHROPIC_AUTH_TOKEN": "sk-pi-...", "ANTHROPIC_MODEL": "claude-sonnet-5-5", "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-5-5" } } ``` Settings in this file apply to every project, background agents included. When a shell export sets the same variable, the value in this file wins. Never put the key in a project's `.claude/settings.json`: that file is committed with the repository. What each entry does: - `ANTHROPIC_BASE_URL` is `https://api.pirouter.ai`, without `/v1`. Claude Code appends `/v1/messages` itself. - `ANTHROPIC_AUTH_TOKEN` is your pirouter key. Claude Code sends it in the `Authorization: Bearer` header, which is where the gateway reads it. - `ANTHROPIC_MODEL` is the main model. - `ANTHROPIC_DEFAULT_HAIKU_MODEL` pins the model for background tasks. Claude Code sends short requests in the background, such as session titles and summaries. Through pirouter they use the main model by default; with this entry they use the cheaper Haiku 5.5 instead. ### Use it in one terminal only To leave the settings file alone, export the same variables in the terminal that starts Claude Code: ```bash export ANTHROPIC_BASE_URL="https://api.pirouter.ai" export ANTHROPIC_AUTH_TOKEN="$PIROUTER_API_KEY" claude --model claude-sonnet-5-5 ``` ### Use hyphenated aliases for models Name models by hyphenated aliases such as `claude-sonnet-5-5`, `claude-opus-5-5` and `claude-haiku-5-5`, not by full IDs such as `anthropic/claude-sonnet-5.5`. Logs and billing still record the full ID, `anthropic/claude-sonnet-5.5` for example; see [Aliases](https://pirouter.ai/docs/models.md#aliases). The reason is on the Claude Code side. It identifies a model by the built-in Anthropic model ID that your ID contains, and sets the context window and capabilities from that. The hyphenated aliases match the built-in IDs, so Claude Code identifies them correctly and runs Sonnet 5.5 with its 1M context window. A full ID with dots gets identified as something else: `anthropic/claude-opus-5.5` contains `claude-opus-5`, so Claude Code treats it as Opus 5. The request still succeeds, but Claude Code runs with Opus 5's settings. ### Which models you can use Claude Code speaks only the Anthropic protocol, and Anthropic supports it only with Claude models. The gateway does not convert protocols, so use Claude models; see the Anthropic column of the protocol table in [Models & protocols](https://pirouter.ai/docs/models.md#which-protocols-each-model-accepts). ## Verify In an empty directory, run: ```bash claude -p "Reply with the single word: ok" ``` You should see `ok` printed in the terminal. Asking it to read a file and call a tool works too, and prompt caching takes effect. The request shows up in [Logs](https://pirouter.ai/docs/guides/logs.md) in the console, with `/v1/messages` under **Endpoint** and the full model ID. In interactive mode, run `/status` to see the base URL and the credential source Claude Code is using. ## Troubleshooting ### 401 invalid\_api\_key Usually `ANTHROPIC_BASE_URL` is set but `ANTHROPIC_AUTH_TOKEN` is not. Claude Code then keeps using your Claude subscription login and sends that credential to pirouter. The gateway reads `Authorization` first, finds a value that is not a pirouter key, and returns `401`. Set `ANTHROPIC_AUTH_TOKEN` to your pirouter key, then run `/status` to confirm it is the credential source. For other authentication failures, see [Authentication & API keys](https://pirouter.ai/docs/authentication.md#when-authentication-fails). ### 400 mentioning context\_management or Extra inputs are not permitted By default Claude Code sends some experimental beta features along with the request fields that go with them. When the upstream rejects them, the request returns `400`, and the `message` often names `context_management` or `output_config`, or says `Extra inputs are not permitted`. Set this variable in the environment that starts Claude Code, and it stops sending those experimental features: ```bash export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 ``` You can also add `"CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"` to the `env` block of `~/.claude/settings.json`. ### Warning that the model isn't recognized A startup warning `Model "..." isn't recognized ยท context assumed to be 200k tokens` means Claude Code cannot identify your model ID. It assumes a 200K context window and compacts the conversation early. Switch to a hyphenated alias such as `claude-sonnet-5-5`. If the alias is already right and the warning stays, your Claude Code is probably older than the model: run `claude update`. ### 422 validation\_failed A `422` with the error code `validation_failed` and a `message` starting "This model is not served on the endpoint you called." means the model does not accept the Anthropic protocol, for example `openai/gpt-6.1-sol`. Pick a Claude model. To code with OpenAI models, use [Codex](https://pirouter.ai/docs/integrations/codex.md). ## Not verified yet - Non-Claude models that accept the Anthropic protocol (rows with Anthropic support in the protocol table) have not been tested with Claude Code, and Anthropic does not support that setup. - Long thinking tasks, many subagents in parallel, and sessions with many MCP tools have not been tested specifically. - Token counts in `/context` are estimates: the gateway does not serve `POST /v1/messages/count_tokens`, so Claude Code falls back to a character-based estimate without an error. ## Related links - [Claude Code](https://github.com/anthropics/claude-code) on GitHub - [Claude Code setup](https://code.claude.com/docs/en/setup) - [Connect to an LLM gateway](https://code.claude.com/docs/en/llm-gateway-connect): the official gateway setup guide for Claude Code - [Model configuration](https://code.claude.com/docs/en/model-config): model aliases, context windows and the related environment variables