Based on Anthropic’s official docs, checked October 31, 2026

Claude Code with OpenRouter: setup, models and troubleshooting

OpenRouter exposes an Anthropic Messages API compatible endpoint, so Claude Code can talk to it directly by changing a few environment variables, with no local proxy. OpenRouter pitches it for provider failover, team budget controls and usage analytics. Its docs say Claude Code through OpenRouter is only guaranteed to work with the Anthropic first-party provider, and recommend making Anthropic 1P the top-priority provider. This guide follows OpenRouter’s Claude Code guide and Anthropic’s LLM gateway docs, checked October 31, 2026.

1. 1. Install Claude Code

   Use the native installer (or npm with Node.js 18 or newer). See our install guide for details.

   curl -fsSL https://claude.ai/install.sh | bash

2. 2. Set the gateway variables

   Add these to your shell profile (~/.zshrc or ~/.bashrc), then reload it. The OpenRouter key goes in ANTHROPIC_AUTH_TOKEN, which Claude Code sends as a bearer token, and ANTHROPIC_API_KEY must be explicitly empty. Define OPENROUTER_API_KEY before the line that uses it. Don’t use a project .env file; OpenRouter notes the native installer doesn’t read it.

   export OPENROUTER_API_KEY="<your-openrouter-api-key>"
   export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
   export ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY"
   export ANTHROPIC_API_KEY=""
   source ~/.zshrc

3. 3. Clear a cached Anthropic login

   If you were signed in to Claude Code with an Anthropic account, run /logout once, then quit and relaunch claude. A cached login next to a gateway credential causes auth-conflict warnings and model-not-found errors.

   /logout

4. 4. Start and verify

   Run claude in your project, then /status. It should show ANTHROPIC_AUTH_TOKEN as the auth token and https://openrouter.ai/api as the base URL. Requests also appear in your OpenRouter Activity Dashboard.

   > /status
   Auth token: ANTHROPIC_AUTH_TOKEN
   Anthropic base URL: https://openrouter.ai/api

Project-scoped setup instead of your shell profile

You can put the same variables in the env block of .claude/settings.local.json in your project root. Keep your real key out of version control.

Billing and your Claude subscription

Anthropic’s LLM gateway docs say that while a gateway credential is active, requests carry it instead of your claude.ai subscription login, and the subscription’s usage limits don’t apply to them. With OpenRouter you pay from OpenRouter credits, and usage, including reasoning tokens, shows in your OpenRouter dashboard.

Setting only ANTHROPIC_BASE_URL without a gateway credential doesn’t replace the subscription: a saved claude.ai login stays the active credential.

Choosing models for each role

Claude Code picks models by role. Override them with ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL, ANTHROPIC_DEFAULT_FABLE_MODEL and CLAUDE_CODE_SUBAGENT_MODEL, then open /model to confirm each class is listed. OpenRouter says Fable isn’t offered in /model unless you set ANTHROPIC_DEFAULT_FABLE_MODEL.

Set CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 to show OpenRouter’s gateway model picker, a curated list rather than the full catalog. Some entries route to non-Anthropic providers, and OpenRouter warns Claude Code may not work correctly with them.

Fast mode and the GitHub Action

To use /fast through OpenRouter, set CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1 (Claude Code v2.1.96 or newer) and pin ANTHROPIC_DEFAULT_OPUS_MODEL to a specific supported Opus ID; with a “latest” alias, OpenRouter says requests go out at standard speed.

In the official claude-code-action, pass the OpenRouter key as anthropic_api_key and set ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN in the step’s env block.

Troubleshooting

Model-not-found errors for OpenRouter models usually mean a credential conflict: run /logout for a cached login, or empty a real ANTHROPIC_API_KEY left in your profile. Auth errors: check the key is in ANTHROPIC_AUTH_TOKEN and reload your shell.

If the context window always shows 200k, append [1m] to a model slug that supports a 1M window; OpenRouter strips the marker before routing.

Tips

• Load the key from your OS keychain rather than leaving it in plain text in a dotfile, and rotate it at openrouter.ai/settings/keys if it leaks.
• Make Anthropic first-party the top-priority provider in OpenRouter for the most reliable results.
• OpenRouter says it doesn’t log your prompts unless you opt in to prompt logging in account settings.

Next steps

Sources

• https://openrouter.ai/docs/guides/guides/claude-code-integration · checked 2026-10-31
• https://code.claude.com/docs/en/llm-gateway · checked 2026-10-31
• https://code.claude.com/docs/en/llm-gateway-connect · checked 2026-10-31