# Claude Code 接入 LYRouter：安装、配置与故障排查

来源: https://platform.lyrouter.com/ai_gateway/docs/claude-code
更新日期: 2026-10-14

Claude Code 可以通过自定义模型服务接入 LYRouter。本文从安装前提开始，说明如何配置并完成第一次调用。

已安装应用？直接查看[配置 LYRouter](#配置-lyrouter)。

## 前提条件

选择操作系统，准备对应的终端与依赖。原生安装不要求先安装 Node.js；设备需至少 4 GB 内存、联网环境和安装目录写权限。

**选择操作系统**

Windows:
#### 1. 确认系统与终端

使用 Windows 10 1809+ / Windows Server 2019+，按 x64 / ARM64 选择环境。在 **PowerShell** 中检查系统：

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

#### 2. 准备可选的 Git Bash

原生安装可直接使用 PowerShell；需要 Bash 工具时，安装 [Git for Windows](https://git-scm.com/downloads/win)，再重新打开终端：

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

使用 WSL 时，在 WSL 的 Linux 终端按 Linux 页签准备环境；不需要另装 Git for Windows。

Linux:
#### 1. 确认系统与终端

官方支持 Ubuntu 20.04+、Debian 10+ 等环境。打开 **Bash** 终端，确认发行版、架构及安装目录写权限：

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

#### 2. 准备 cURL

```bash
curl --version
```

缺少依赖时，Ubuntu / Debian 可执行：

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

Alpine / musl 环境需要额外运行库，按[官方系统要求](https://code.claude.com/docs/en/setup#alpine-linux-and-musl-based-distributions)准备后再安装。

macOS:
#### 1. 确认系统与终端

使用 macOS 13+，支持 Intel 与 Apple Silicon。在 **终端（Terminal）** 中检查：

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

#### 2. 检查 cURL

macOS 通常已自带 cURL，可使用 Bash / Zsh 运行下节原生安装命令：

```bash
curl --version
```

确认当前用户可以写入安装目录，并能访问官方安装地址。

接入 LYRouter 还需要一把已启用的 API Key 和当前工作空间可用的模型。示例中的 `MODEL_ID` 必须替换为实际系统模型标识；工具账号与 LYRouter 账号是两个独立身份。

## 安装应用

**按系统安装**

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

使用官方安装器，完成后运行 `claude --version` 确认版本。

## 配置 LYRouter

在 `~/.claude/settings.json` 的已有 `env` 中合并以下字段，保留其他设置：

```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"
  }
}
```

把 `MODEL_ID` 换成工作空间模型广场中已开通的模型 ID，`FAST_MODEL_ID` 换成一个速度快、价格低的模型 ID（也可以与 `MODEL_ID` 相同）。各字段的作用：

| 字段 | 作用 |
| --- | --- |
| `ANTHROPIC_BASE_URL` | 网关根地址，不加 `/v1`，Claude Code 会自己拼接 `/v1/messages` |
| `ANTHROPIC_AUTH_TOKEN` | LYRouter API Key，Claude Code 以 `Authorization: Bearer` 头发送 |
| `ANTHROPIC_MODEL` | 本次会话使用的主模型 |
| `ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` | 在 `/model` 中选择 `opus`、`sonnet` 别名时实际使用的模型 |
| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | `haiku` 别名以及后台任务（如生成会话标题）使用的模型 |
| `CLAUDE_CODE_SUBAGENT_MODEL` | 子代理默认使用的模型 |
| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 关闭自动更新检查、遥测等非必要的网络请求 |

**模型字段都要填 LYRouter 的模型 ID。** Claude Code 的后台任务、模型别名和子代理默认使用 Claude 官方的模型名，这些名称不是 LYRouter 的模型 ID。没有配置对应字段时，这部分请求会返回 403 `Model is not available in the model plaza`；如果工作空间设置了[默认模型](https://platform.lyrouter.com/ai_gateway/docs/routing)，则会改由默认模型回答。所选模型需要支持工具调用和流式输出。

## 验证首次调用

启动应用，显式选择刚配置的模型，发送“请回复 OK”这样的最小任务。再到 LYRouter 的[请求日志](https://platform.lyrouter.com/ai_gateway/docs/logs)检查生成端点、状态和实际模型。连接测试成功不等于完整生成或工具调用已通过。

## 日常使用与故障排查

### 安装后提示找不到命令，怎么办？

**答：** 重新打开终端，执行本页安装步骤中的版本检查命令，并核对安装目录是否在 PATH 中。使用与安装步骤一致的终端和运行环境；仍不可用时，按官方安装指南检查安装结果。

### Base URL 应该怎么填，为什么会出现地址错误？

**答：** `ANTHROPIC_BASE_URL` 使用 `https://api.lyrouter.com`，不添加 `/v1`；客户端会拼接 Messages 路径。不要填控制台页面地址，也不要重复拼接端点。

### 切换模型前需要检查什么？

**答：** 确认新模型已在当前工作空间启用、至少有一个有效服务来源，并支持应用所需的协议和工具能力。使用系统模型标识，不使用展示名称。

### 应用更新后，原来的配置为什么不生效？

**答：** 先核对当前应用版本和实际读取的配置位置，再对照本页“配置 LYRouter”检查提供商、地址、密钥和模型。不同版本的配置要求以本页链接的官方资料为准。

### 请求返回 401 / 403，应该先检查什么？

**答：** 确认填写的是已启用的 LYRouter API Key，并检查该 Key 所属工作空间的模型来源与访问策略。结合具体错误和日志判断拒绝来源，详见[鉴权与权限 FAQ](https://platform.lyrouter.com/ai_gateway/docs/auth-errors)。

### 请求返回 429，反复重试有用吗？

**答：** 先确认是平台限制还是上游额度耗尽，再调整并发、调用频率或资源配置。使用有上限的退避重试，避免立即密集重试，详见[限流与配额 FAQ](https://platform.lyrouter.com/ai_gateway/docs/rate-errors)。

### 主对话正常，但日志里有 403 `Model is not available in the model plaza`，是什么原因？

**答：** 通常是后台任务、模型别名或子代理用 Claude 官方模型名发出了请求。按本页「配置 LYRouter」补齐 `ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_HAIKU_MODEL` 和 `CLAUDE_CODE_SUBAGENT_MODEL`，全部填 LYRouter 的模型 ID。在[请求日志](https://platform.lyrouter.com/ai_gateway/docs/logs)中查看「模型（请求）」列，可以确认是哪个名称没有配置。

### 缓存命中率很低甚至为 0，怎么办？

**答：** 先升级 Claude Code。部分版本会在系统提示词开头写入一行每个请求都变化的标记，使提示词缓存从第一个字节起就无法命中，日志中的「输入（缓存命中）」长期为 0。升级到最新版本后即可恢复。会话中途增删工具或 MCP 服务器也会降低命中率，更多做法见[降低成本与优化缓存](https://platform.lyrouter.com/ai_gateway/docs/cost-practice)。

### 应用有回复，但 LYRouter 日志里找不到请求，怎么办？

**答：** 确认当前生效的是本页配置的 LYRouter 提供商和模型，并核对网关地址。用最小生成任务验证后，在正确工作空间按时间和 Key 查询[请求日志](https://platform.lyrouter.com/ai_gateway/docs/logs)。仅拉取模型列表不会出现在普通调用列表中。

## 官方资料

下列要求和安装方式来自工具官方资料，后续版本以官方说明为准。

- [Claude Code 安装与系统要求](https://code.claude.com/docs/en/setup)
- [模型配置](https://code.claude.com/docs/en/model-config)