Coding agents
Set up Claude Code with Router
Point Claude Code at Router by editing its settings file. Nothing to install and no installer to run.
Claude Code talks to Router over Router's Anthropic Messages endpoint, so you only need to give it Router's address and a Router key. This page walks through doing that by hand by editing Claude Code's settings file. We also offer automated setup using the Router installer, which makes the same changes.
Requirements: Claude Code 2.1.118 or newer, and a Router API key from the API keys page. Run claude --version to check your version.
The installer offers a richer experience: the Router installer also adds a status line to Claude Code that shows which models served your session, how much each cost, and how much you saved with Router. Manual setup doesn't include it.
Open API keys, create a key, and copy it. The secret is shown only once.
Claude Code reads its settings from ~/.claude/settings.json, or from settings.json inside the directory named by CLAUDE_CONFIG_DIR if you have set it. Create the file if it doesn't exist, and add these entries to its env object. If the file already has an env object, add the keys to it rather than replacing it.
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.router.com",
"ANTHROPIC_AUTH_TOKEN": "your-router-key",
"ANTHROPIC_CUSTOM_HEADERS": "X-Gateway-Client: claude-code",
"CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
"CLAUDE_CODE_AUTO_COMPACT_WINDOW": "900000"
}
}Here is what each setting does:
Setting | What it does |
|---|---|
ANTHROPIC_BASE_URL | Sends Claude Code's requests to Router. Don't add /v1 here; Claude Code appends the path itself. |
ANTHROPIC_AUTH_TOKEN | Your Router key, sent as a bearer token. |
ANTHROPIC_CUSTOM_HEADERS | Tells Router you're using Claude Code, so it lists models in the form Claude Code's model picker expects, including Router's own routing options such as switchyard. |
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY | Makes Claude Code read the model list from Router instead of using its built-in list. |
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC | Stops optional background calls that can interfere with Router's model list if you're also signed in to an Anthropic account. |
CLAUDE_CODE_AUTO_COMPACT_WINDOW | Makes Claude Code compact long conversations before it reaches 1,000,000 tokens, which is slightly more than some models accept in one request. Models with smaller context windows are unaffected. |
Don't set ANTHROPIC_API_KEY: Claude Code treats it differently from ANTHROPIC_AUTH_TOKEN, and setting both is ambiguous. If it is set in your shell or in the same settings file, remove it.
If you'd rather not store the key in a file, leave ANTHROPIC_AUTH_TOKEN out of settings.json and export it from your shell profile instead:
export ANTHROPIC_AUTH_TOKEN="$RAMP_ROUTER_API_KEY"Confirm that your key works and see which models it can use:
curl https://api.router.com/v1/models \
-H "Authorization: Bearer $RAMP_ROUTER_API_KEY"Then start Claude Code and run /model. The picker lists the models your key can use. Pick one, or start Claude Code on a specific model with claude --model <model-id>.
Claude Code and Claude Desktop are Anthropic's own tools, and through Router they run Claude models only. The /model picker lists the Claude models your key can use, including Claude served through Amazon Bedrock or Google Vertex AI if your key reaches them, and Router's Switchyard and auto routing options when both of their models are Claude models. Models from other providers stay available to your key through every other harness and through the API; see Supported models for what's available.
If Claude Code is still configured with a model from another provider, Router returns an error naming the model. Pick a Claude model from /model, or run ramp router refresh to update the configured default.
Claude Code sends its sub-agents to a model tier (sonnet, opus, haiku, or fable), and it resolves each tier to an Anthropic model ID by default. If your key can't use that model, or you want sub-agents on a different model, name the model to use for each tier in the same env object:
{
"env": {
"ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
}
}For Anthropic models, use IDs returned by GET /v1/models for your key.
Remove the entries you added from env in settings.json (and any model entry you chose). Claude Code then goes back to using your Anthropic account.
What you see | What to check |
|---|---|
Claude Code asks you to sign in to Anthropic | ANTHROPIC_AUTH_TOKEN and ANTHROPIC_BASE_URL aren't both being read. Confirm they're in the env object of the settings file Claude Code loads, and that the JSON is valid. |
A 401 error | The key is wrong or was revoked. Check it on the API keys page. |
"There's an issue with the selected model" | The model isn't available for your API key. Pick one from /model or from GET /v1/models. |
"is not available in Claude Code or Claude Desktop through Router" | Claude Code is set to a model from another provider. Pick a Claude model from /model, or run ramp router refresh. |
A switchyard model you configured doesn't appear in /model | Both of its models must be Claude models to appear in Claude Code. Change the pair on the Workloads page, or use it from another harness. |
An error mentioning ANTHROPIC_API_KEY | Remove ANTHROPIC_API_KEY from your shell and settings. |
If a failure persists, report it to the Router team with the x-request-id from the response. See Support and feedback.
The Router installer, or ramp router configure claude-code, makes the changes on this page and also installs a status line that shows which models served your session, how many requests each handled, and how much you saved. The status line is a script the installer adds, so it isn't part of the manual setup.