Agents & CLIsGuide reviewed 2026-10-05

Claude Code with RouterPlex

Point Claude Code at RouterPlex with ANTHROPIC_BASE_URL. One prepaid key, hard budgets, no local proxy.

Follow updates Share setup
On this page

Set it up with your coding agent

Paste your key into the prompt's key field, then copy the prompt into Claude Code, Codex, Cursor, or any coding agent. It configures the tool and keeps testing until a real request goes through RouterPlex, fixing environment problems along the way. Prefer to do it by hand? Follow the manual setup below; your key fills those commands too.

prompt

Optional. It stays in this browser tab and is never saved or sent. No key yet? Create one in guided setup.

Set up Claude Code on this machine to use RouterPlex, an OpenAI- and Anthropic-compatible AI gateway. Keep working until a real request from Claude Code succeeds through RouterPlex.
 
My RouterPlex API key: YOUR_ROUTERPLEX_API_KEY
 
Key handling:
- If the key line above is a placeholder rather than a real key (real keys start with sk-), use my ROUTERPLEX_API_KEY environment variable. If that is empty too, ask me for the key once, then continue.
- Store the key only in user-level config or my user environment. Never put it in a project file, never commit it, and do not repeat the full key in your replies (show at most its first 8 characters).
 
Config handling:
- Before changing an existing config file or shell startup file, copy it to a .bak file next to it and show me the diff. Merge into what is there; never replace my other settings, providers, or MCP servers.
- If a step needs something only I can do, such as a click in a settings window, print the exact steps instead of guessing.
 
Full guide: https://docs.routerplex.com/claude-code
 
Step 1. Prove the key and the RouterPlex gateway work before changing anything else. Run:
curl -sS https://api.routerplex.com/v1/chat/completions -H "Authorization: Bearer YOUR_ROUTERPLEX_API_KEY" -H "Content-Type: application/json" -d '{"model":"claude-sonnet-4-6","max_tokens":32,"messages":[{"role":"user","content":"Reply with exactly: RouterPlex connected."}]}'
On Windows PowerShell, use curl.exe with the body in a file, or Invoke-RestMethod.
- A reply containing "RouterPlex connected.": go on.
- 401: the key is wrong or revoked. Stop and ask me for a correct key.
- 402: my balance or trial credit is used up. 403: this key reached its own spending limit. Stop and tell me; retrying cannot fix these.
- Network, DNS, TLS, or proxy errors: find and fix the cause (proxy variables, VPN, firewall, system clock, outdated CA certificates), then run it again.
 
Step 2. Configure Claude Code:
- Run claude --version. If Claude Code is missing, install it with the official installer (curl -fsSL https://claude.ai/install.sh | bash; Windows PowerShell: irm https://claude.ai/install.ps1 | iex).
- In my user-level Claude Code settings, ~/.claude/settings.json (Windows: %USERPROFILE%\.claude\settings.json), set these keys in the "env" object. Merge with what is there and keep my other settings:
ANTHROPIC_BASE_URL = https://api.routerplex.com (no /v1; Claude Code adds /v1/messages)
ANTHROPIC_AUTH_TOKEN = the key
ANTHROPIC_API_KEY = "" (empty, so a direct Anthropic key does not compete)
ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL = claude-sonnet-4-6
- Keeping the key in settings.json means Claude Code does not depend on shell variables, and it also reaches Claude Code when an app such as Conductor or a desktop launcher starts it. For the Claude Code VS Code extension, also set the same variables in VS Code's user settings under "claudeCode.environmentVariables" (a list of {"name", "value"} objects).
- Use ANTHROPIC_AUTH_TOKEN for the key, not ANTHROPIC_API_KEY: it outranks a saved claude.ai login and needs no approval prompt.
- If I want a non-Claude model (any chat model from https://routerplex.com/api/models), also set CLAUDE_CODE_MAX_CONTEXT_TOKENS to that model's context_tokens minus max_output_tokens. Claude Code otherwise assumes 200,000 tokens for IDs that do not start with claude- and compacts too early.
- You cannot switch your own running session to RouterPlex. Test in a new process, and tell me to start a new session afterwards. If a session ever says "Not logged in", I must not run /login (that signs in to Anthropic instead); restarting with claude --resume picks up the settings.
 
Step 3. Test Claude Code itself from a new terminal or a restarted app, so you test the saved setup rather than the shell you changed:
From an empty temporary folder: claude --model 'claude-sonnet-4-6' -p 'Reply with exactly: RouterPlex connected. Do not read files or run tools.'
If the reply is wrong, run claude and check /status: it must show https://api.routerplex.com as the base URL.
Expected reply: "RouterPlex connected."
 
Step 4. If step 1 works but step 3 fails, the problem is Claude Code's configuration or environment, not RouterPlex. Check these, fix what is wrong, and repeat step 3:
- The key or base URL is set in one place but not where Claude Code starts: zsh vs bash startup files, login vs non-login shells, a desktop launcher, a background service, Windows vs WSL, or a remote SSH or container environment.
- Another setting wins: OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_API_BASE, ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, or a project-level config that overrides the user-level one.
- Claude Code is outdated, or still needs a full restart to read the new settings.
- If an environment variable cannot be made to reach Claude Code reliably and Claude Code accepts a key in its user-level config, put the key there instead.
 
Keep repeating steps 3 and 4 until the test reply comes back.
 
Step 5. The test above sends no tools, but real sessions send every tool, MCP server, and plugin schema with each request, and that is where models differ. From a folder with a README.md (create a temporary one containing "# RouterPlex tool check" if needed), run:
claude --model claude-sonnet-4-6 -p "List your available tools, then read ./README.md and reply with its first heading."
It passes when the reply lists the tools and quotes the heading. If it fails while step 3 passes, the tool schemas are the problem, not the connection. Tell me the exact error; the chosen model may not handle Claude Code's tools, so suggest another tool-capable model from https://routerplex.com/models.
 
Stop early only for a 401, 402, or 403, or for a step only I can do, such as a click in a settings window or a login. Then tell me exactly what to do, wait for me, and continue testing afterwards.
 
When it works, tell me exactly which files you changed and which values you set (key shown by its first 8 characters only) so I can undo it, where the key is stored, and the final test output. Remind me that every request shows up in https://routerplex.com/dashboard/usage.

Manual setup

Connect Claude Code directly to RouterPlex's Anthropic Messages endpoint. Start with a Claude model; other chat models may accept the protocol but differ in their support for Claude Code's tools.

1. Install or update

macOS / Linux / WSL

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

Windows PowerShell

powershell
irm https://claude.ai/install.ps1 | iex

Reopen the terminal and run claude --version. Git for Windows is recommended for the Bash tool on native Windows; current Claude Code can use PowerShell when Git Bash is absent. If using WSL, follow the Linux instructions inside WSL.

2. Set the connection

Create a key in guided setup. Paste the block for your shell, replacing YOUR_ROUTERPLEX_API_KEY with that key.

macOS / Linux — Bash or Zsh

bash
export ANTHROPIC_BASE_URL='https://api.routerplex.com'
export ANTHROPIC_AUTH_TOKEN='YOUR_ROUTERPLEX_API_KEY'
export ANTHROPIC_API_KEY=''
export ANTHROPIC_MODEL='claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-sonnet-4-6'

Windows PowerShell

powershell
$env:ANTHROPIC_BASE_URL = 'https://api.routerplex.com'
$env:ANTHROPIC_AUTH_TOKEN = 'YOUR_ROUTERPLEX_API_KEY'
$env:ANTHROPIC_API_KEY = ''
$env:ANTHROPIC_MODEL = 'claude-sonnet-4-6'
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = 'claude-sonnet-4-6'
$env:ANTHROPIC_DEFAULT_SONNET_MODEL = 'claude-sonnet-4-6'
$env:ANTHROPIC_DEFAULT_OPUS_MODEL = 'claude-sonnet-4-6'

The base URL has no /v1 suffix. Claude Code adds /v1/messages. The key goes in ANTHROPIC_AUTH_TOKEN, which Claude Code sends as Authorization: Bearer. It outranks both ANTHROPIC_API_KEY and a saved claude.ai login, and it takes effect without the one-time "use this API key?" prompt that ANTHROPIC_API_KEY triggers. The empty ANTHROPIC_API_KEY avoids a competing direct-provider credential. The default model variables pin aliases and background work to the selected RouterPlex model. ANTHROPIC_SMALL_FAST_MODEL is deprecated; use ANTHROPIC_DEFAULT_HAIKU_MODEL.

3. Send a short test

In the same terminal, from an empty folder:

text
claude --model claude-sonnet-4-6 -p "Reply with exactly: RouterPlex connected. Do not read files or run tools."

Confirm the reply and the request in Usage. Then run claude in your project. /status shows the active setup, and /model changes the model for a session.

Reusing the configuration

The shell settings last for the current terminal session. For persistent setup, use Claude Code's user-level env settings in ~/.claude/settings.json (macOS/Linux) or %USERPROFILE%\.claude\settings.json (Windows), or configure your shell environment. Keep credentials out of project files and source control. Existing settings or organization policies may override the environment; review /status if the wrong route is used.

Give Claude Code a dedicated budget. A successful short reply proves connectivity, not every tool workflow with every model.

Test with your real tools

The short test sends no tools. A real session sends every built-in tool, MCP server, and plugin schema with each request, and those schemas are where models differ. Before relying on a new model, run one tool round trip from a project where your MCP servers and plugins load:

bash
claude --model claude-sonnet-4-6 -p "List your available tools, then read ./README.md and reply with its first heading."

It passes when the reply names your tools and quotes the heading. This uses only the current terminal's variables and leaves your settings files untouched.

Use a non-Claude model

Any chat model in the catalog can be the Claude Code model, for example gpt-6-sol, kimi-k3, or glm-5.3. Set it in all four model variables above. Claude Code assumes a 200,000-token window for model IDs it does not recognize, so it compacts too early on larger models. Declare the real input window:

bash
export CLAUDE_CODE_MAX_CONTEXT_TOKENS=794000 # gpt-6-sol: 922,000 context - 128,000 max output

Take both numbers from the model's context_tokens and max_output_tokens in the public catalog. Subtract the output from the context, because most non-Anthropic providers count the reply inside the same window. Claude Code applies this variable only to IDs that do not start with claude-; RouterPlex's claude-* models use Claude Code's built-in window sizes. Tool support varies by model, so run the tool round trip above before giving a non-Claude model real work.

Pick models in /model

To list RouterPlex's Claude models in the /model picker, also set CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1. Claude Code then reads /v1/models at startup. It keeps only IDs that contain claude, so pass non-Claude models with --model or ANTHROPIC_MODEL instead. Copy model IDs from the catalog exactly. RouterPlex's Claude IDs use dashes (claude-sonnet-4-6), not dots.

VS Code extension and other launchers

The Claude Code VS Code extension checks credentials before it starts Claude Code, so put the variables in VS Code's user settings (Preferences: Open User Settings (JSON)):

json
{
"claudeCode.environmentVariables": [
{ "name": "ANTHROPIC_BASE_URL", "value": "https://api.routerplex.com" },
{ "name": "ANTHROPIC_AUTH_TOKEN", "value": "YOUR_ROUTERPLEX_API_KEY" },
{ "name": "ANTHROPIC_MODEL", "value": "claude-sonnet-4-6" }
]
}

Apps that start Claude Code for you, such as Conductor, desktop launchers, and background agents, do not reliably inherit your shell's variables. Put the same variables in the env block of ~/.claude/settings.json, which Claude Code reads however it is started:

json
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.routerplex.com",
"ANTHROPIC_AUTH_TOKEN": "YOUR_ROUTERPLEX_API_KEY",
"ANTHROPIC_API_KEY": "",
"ANTHROPIC_MODEL": "claude-sonnet-4-6",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-sonnet-4-6",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-sonnet-4-6"
}
}

Never put the key in a project's .claude/settings.json: that file is committed. Use .claude/settings.local.json for one project, and add it to .gitignore first if you create it by hand. Settings-file values win over shell exports. Settings reach new sessions only, so start a new session after changing them.

Troubleshooting

SymptomCauseFix
Asks you to log in although the curl test worksClaude Code did not receive a credential before first-run setupSet ANTHROPIC_AUTH_TOKEN in a shell export or ~/.claude/settings.json. Do not run /login: it signs in to Anthropic instead of RouterPlex
Startup warning that two credential sources are setA saved claude.ai login and the RouterPlex key are both presentRouterPlex is used for requests. Run /logout to remove the saved login and the warning
/status has no Anthropic base URL lineThe variables did not reach this processUse the settings-file env block, or start claude from the terminal where you set them
401Wrong or revoked keyCheck the key in API Keys and keep it in ANTHROPIC_AUTH_TOKEN
402 or 403Balance or key budget used upSee Errors. Retrying does not help
Model not foundID spelled differently from the catalog, or outside the key's allowlistCopy the ID from the catalog

Rotate the key safely

Create the new key first, test it with the short test and the tool round trip in a new terminal, then swap it into your settings and start a new session. Revoke the old key only after that. Changing the key under a running session makes its next request fail; resume with claude --resume.

A longer install walkthrough is in Install Claude Code with RouterPlex.

Official references: Claude Code setup, connect to an LLM gateway, authentication precedence, model configuration.

Claude Code with RouterPlex · RouterPlex Docs