LYRouter Docs

Claude Code: install, configure and troubleshoot LYRouter access

Claude Code can connect to LYRouter as a custom model service. This page starts with the installation prerequisites, then shows how to configure the tool and make your first call.

Already installed? Go straight to Configure LYRouter.

Prerequisites

Choose your operating system and prepare the matching terminal and dependencies. The native installer does not require Node.js; your device needs at least 4 GB of RAM, network access and write permission to the installation directory.

1. Check your system and terminal

Use Windows 10 1809+ / Windows Server 2019+, on x64 or ARM64. Check your system in PowerShell:

Get-CimInstance Win32_OperatingSystem | Select-Object Caption, Version, OSArchitecture

2. Prepare Git Bash (optional)

The native installation runs directly in PowerShell. If you need Bash tools, install Git for Windows, then reopen the terminal:

winget install --id Git.Git --exact --source winget
git --version

If you use WSL, prepare the environment in the WSL Linux terminal by following the Linux tab; you do not need Git for Windows.

To connect to LYRouter you also need an enabled API key and a model available in the current workspace. Replace MODEL_ID in the examples with an actual system model identifier. Your tool account and your LYRouter account are two separate identities.

Install the app

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

Use the official installer. When it finishes, run claude --version to confirm the version.

Configure LYRouter

Merge the following fields into the existing env in ~/.claude/settings.json, keeping your other settings:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.lyrouter.com",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_LYROUTER_API_KEY",
    "ANTHROPIC_MODEL": "MODEL_ID",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "MODEL_ID",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "MODEL_ID",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "FAST_MODEL_ID",
    "CLAUDE_CODE_SUBAGENT_MODEL": "MODEL_ID",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

Replace MODEL_ID with a model ID enabled in the workspace's Model marketplace, and FAST_MODEL_ID with the ID of a fast, low-cost model (it can be the same as MODEL_ID). What each field does:

Field Purpose
ANTHROPIC_BASE_URL Gateway root URL without /v1; Claude Code appends /v1/messages itself
ANTHROPIC_AUTH_TOKEN Your LYRouter API key, which Claude Code sends in an Authorization: Bearer header
ANTHROPIC_MODEL Main model for the session
ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL Model actually used when you choose the opus or sonnet alias in /model
ANTHROPIC_DEFAULT_HAIKU_MODEL Model used for the haiku alias and for background tasks such as generating session titles
CLAUDE_CODE_SUBAGENT_MODEL Default model for subagents
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC Turns off nonessential network requests such as automatic update checks and telemetry

Fill every model field with a LYRouter model ID. By default, Claude Code's background tasks, model aliases and subagents use official Claude model names, and those names are not LYRouter model IDs. When the matching field is not set, these requests return 403 Model is not available in the model plaza; if the workspace has a Default Model set, the default model answers instead. The models you choose need to support tool calling and streaming output.

Verify your first call

Start the app, explicitly select the model you just configured, and send a minimal task such as "Reply OK". Then check the generation endpoint, status and actual model in LYRouter's request logs. A successful connection test does not mean that full generation or tool calling works.

Everyday use and troubleshooting

The command is not found after installation. What should I do?

Answer: Reopen the terminal, run the version check command from this page's installation steps, and check whether the installation directory is on PATH. Use the same terminal and runtime environment as in the installation steps. If it still does not work, check the installation against the official installation guide.

How do I fill in the Base URL, and why do I get address errors?

Answer: Set ANTHROPIC_BASE_URL to https://api.lyrouter.com without /v1; the client appends the Messages path. Do not enter the console page address, and do not append the endpoint again.

What should I check before switching models?

Answer: Make sure the new model is enabled in the current workspace, has at least one valid service source, and supports the protocol and tool capabilities the app needs. Use the system model identifier, not the display name.

Why does my configuration stop working after an app update?

Answer: First check the current app version and which configuration location it actually reads, then check the provider, address, key and model against "Configure LYRouter" on this page. The official resources linked on this page define the configuration requirements of each version.

A request returns 401 / 403. What should I check first?

Answer: Make sure you entered an enabled LYRouter API key, and check the model sources and access policies of the workspace the key belongs to. Use the specific error and the logs to find what rejected the request; see 401 / 403: authentication and access.

A request returns 429. Does retrying repeatedly help?

Answer: First find out whether a platform limit or an exhausted upstream quota caused it, then adjust concurrency, call frequency or resource configuration. Retry with bounded backoff instead of retrying immediately and repeatedly; see 429: rate limits and quotas.

The main conversation works, but the logs show 403 Model is not available in the model plaza. Why?

Answer: Usually a background task, a model alias or a subagent sent the request with an official Claude model name. Following "Configure LYRouter" on this page, fill in ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL and CLAUDE_CODE_SUBAGENT_MODEL, all with LYRouter model IDs. The Model (request) column in the request logs shows which name is not configured.

The cache hit rate is very low or even 0. What should I do?

Answer: Upgrade Claude Code first. Some versions write a line at the start of the system prompt that changes with every request, so the prompt cache cannot hit from the very first byte and Input (cache hit) in the logs stays at 0. Upgrading to the latest version fixes this. Adding or removing tools or MCP servers in the middle of a session also lowers the hit rate; for more, see Reducing costs and improving cache reuse.

The app replies, but I cannot find the request in the LYRouter logs. What should I do?

Answer: Make sure the LYRouter provider and model configured on this page are the ones in effect, and check the gateway address. After verifying with a minimal generation task, search the request logs in the correct workspace by time and key. Listing models alone does not appear in the regular call list.

Official resources

The requirements and installation methods below come from the tool's official documentation. For later versions, the official instructions take precedence.