# Claude Code: install, configure and troubleshoot LYRouter access

Source: https://platform.lyrouter.com/ai_gateway/docs/claude-code/en
Last updated: 2026-10-14

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](#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.

**Choose your operating system**

Windows:
#### 1. Check your system and terminal

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

```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](https://git-scm.com/downloads/win), then reopen the terminal:

```powershell
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.

Linux:
#### 1. Check your system and terminal

Ubuntu 20.04+, Debian 10+ and similar environments are officially supported. Open a **Bash** terminal and check the distribution, the architecture and write permission to the installation directory:

```bash
cat /etc/os-release
uname -m
bash --version
```

#### 2. Prepare cURL

```bash
curl --version
```

If dependencies are missing, run on Ubuntu / Debian:

```bash
sudo apt update
sudo apt install -y curl bash
```

Alpine and other musl-based environments need extra runtime libraries. Prepare them as described in the [official system requirements](https://code.claude.com/docs/en/setup#alpine-linux-and-musl-based-distributions) before you install.

macOS:
#### 1. Check your system and terminal

Use macOS 13+, on Intel or Apple Silicon. Check in **Terminal**:

```bash
sw_vers -productVersion
uname -m
```

#### 2. Check cURL

macOS usually includes cURL, so you can run the native installation command in the next section with Bash / Zsh:

```bash
curl --version
```

Make sure the current user can write to the installation directory and can reach the official installation URL.

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

**Install for your operating system**

macOS / Linux / WSL:
```bash
curl -fsSL https://claude.ai/install.sh | bash
claude --version
```

Windows PowerShell:
```powershell
irm https://claude.ai/install.ps1 | iex
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:

```json
{
  "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](https://platform.lyrouter.com/ai_gateway/docs/routing/en) 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](https://platform.lyrouter.com/ai_gateway/docs/logs/en). 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](https://platform.lyrouter.com/ai_gateway/docs/auth-errors/en).

### 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](https://platform.lyrouter.com/ai_gateway/docs/rate-errors/en).

### 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](https://platform.lyrouter.com/ai_gateway/docs/logs/en) 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](https://platform.lyrouter.com/ai_gateway/docs/cost-practice/en).

### 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](https://platform.lyrouter.com/ai_gateway/docs/logs/en) 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.

- [Claude Code installation and system requirements](https://code.claude.com/docs/en/setup)
- [Model configuration](https://code.claude.com/docs/en/model-config)