# CC Switch 接入 LYRouter：安装、配置与故障排查

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

CC Switch 是管理 Claude Code、Codex 等工具服务商配置的桌面应用，本身不调用模型。把 LYRouter 添加为它管理的服务商并启用后，目标工具就会通过 LYRouter 调用模型。本文从安装前提开始，说明如何配置并完成第一次调用。

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

## 前提条件

CC Switch 用于管理编程工具配置，本身不执行模型任务，也不需要额外的 Node.js 运行环境。选择操作系统，准备相应安装条件；使用配置前需安装目标工具，例如 [Claude Code](https://platform.lyrouter.com/ai_gateway/docs/claude-code)或 [Codex CLI](https://platform.lyrouter.com/ai_gateway/docs/codex)。

**选择操作系统**

Windows:
#### 1. 检查系统与架构

使用 Windows 10+，支持 x64 / ARM64。在 PowerShell 中检查：

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

#### 2. 准备安装目录与目标工具

从[官方 Releases](https://github.com/farion1231/cc-switch/releases)选择对应架构的 MSI 或便携版，确认安装或解压目录可写。目标工具需在同一运行环境中安装；CC Switch 自身不要求登录账号。

Linux:
#### 1. 检查系统依赖

要求 **glibc 2.35+ 与 WebKitGTK 4.1**，支持 x64 / ARM64；可使用 Ubuntu 22.04+、Debian 12+ 等符合要求的桌面环境：

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

#### 2. 准备 WebKitGTK 与桌面环境

Ubuntu / Debian 缺少 WebKitGTK 4.1 时，可按系统仓库安装：

```bash
sudo apt update
sudo apt install -y libwebkit2gtk-4.1-0
```

其他发行版参见[官方安装要求](https://github.com/farion1231/cc-switch/blob/main/docs/user-manual/en/1-getting-started/1.2-installation.md)。RHEL / Rocky / Alma 8–9 的系统库不满足当前要求；安装包必须与发行版和架构匹配。

macOS:
#### 1. 检查系统与处理器

使用 macOS 12+，支持 Intel 与 Apple Silicon：

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

#### 2. 准备安装方式与目标工具

可直接下载官方 DMG；若采用下节 Homebrew 方式，先按 [Homebrew 官方说明](https://brew.sh/)准备 Homebrew。配置用于目标工具实际运行的环境，工具尚未安装时可先阅读其安装指南。

接入 LYRouter 还需要一把已启用的 API Key 和当前工作空间可用的模型。示例中的 `MODEL_ID` 必须替换为实际系统模型标识。CC Switch 自身不需要账号，调用凭证用于它所管理的目标工具。

## 安装应用

1. 从[官方 Releases](https://github.com/farion1231/cc-switch/releases)下载安装包。
2. Windows 安装 MSI 或解压便携版；macOS 打开 DMG 并拖入 Applications；Linux 按发行版选择 deb、rpm 或 AppImage。
3. 启动 CC Switch，确认要管理的工具已安装。

macOS 也可按官方说明使用 `brew install --cask cc-switch`。

## 配置 LYRouter

选择要管理的工具，再添加 LYRouter 提供商：

| 目标工具 | 协议与地址 |
| --- | --- |
| Claude Code | Anthropic，https://api.lyrouter.com |
| Codex CLI | Responses，https://api.lyrouter.com/v1 |

填写 LYRouter API Key 与可用模型，启用新提供商并重启目标工具。切换配置前保留原有工具配置；Codex 的具体字段参见[Codex 指南](https://platform.lyrouter.com/ai_gateway/docs/codex)，Claude 字段参见[Claude Code 指南](https://platform.lyrouter.com/ai_gateway/docs/claude-code)。

## 验证首次调用

在 CC Switch 中启用 LYRouter 服务商后，重启目标工具（如 Claude Code 或 Codex），在目标工具里发送“请回复 OK”这样的最小任务。再到 LYRouter 的[请求日志](https://platform.lyrouter.com/ai_gateway/docs/logs)检查生成端点、状态和实际模型。CC Switch 里的连接测试成功，不等于目标工具的生成或工具调用已经可用。

## 日常使用与故障排查

### 装好了 CC Switch，为什么仍找不到 Claude Code 或 Codex 命令？

**答：** CC Switch 不代替目标工具的安装。先按[Claude Code](https://platform.lyrouter.com/ai_gateway/docs/claude-code)、[Codex CLI](https://platform.lyrouter.com/ai_gateway/docs/codex)或对应工具指南完成安装，重新打开终端并检查 PATH，再核对 CC Switch 管理的配置。

### 切换提供商后，为什么目标工具仍调用失败？

**答：** 先核对 CC Switch 管理的目标工具与配置位置，再检查协议和地址：Claude Code 使用根地址 `https://api.lyrouter.com`，Codex CLI 使用 `https://api.lyrouter.com/v1` 和 Responses。CC Switch 管理配置，目标工具仍需已安装并使用正确模型与 LYRouter API Key。

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

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

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

**答：** 先核对当前应用版本和实际读取的配置位置，再对照本页“配置 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)。

### 切换成功后，为什么 LYRouter 仍没有生成日志？

**答：** 确认目标工具实际读取了切换后的配置，正在使用 LYRouter 提供商和模型，再发送最小生成请求。在正确工作空间按时间和 Key 查询[请求日志](https://platform.lyrouter.com/ai_gateway/docs/logs)，不能只凭配置切换成功判断调用已经经过网关。

## 官方资料

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

- [官方安装指南](https://github.com/farion1231/cc-switch/blob/main/docs/user-manual/en/1-getting-started/1.2-installation.md)