# 给配置助手的任务

我是新手，正在 Windows 上配置 Claude Code，使用 Vmvia API。请先阅读这份教程：https://doc.vmvia.com/simple/claude-code-windows

请先确认我已经安装了什么、进行到哪一步。每次只指导一个步骤，写清楚在哪里操作、填什么、成功后会看到什么，等我反馈再继续。遇到错误先根据教程排查，不要猜测不存在的模型、分组或界面选项。已有配置先备份并只合并必要字段。API Key 用 sk-xxx 占位，由我在本机填写。

如果无法读取链接，请明确告诉我，让我粘贴完整教程。你没有本机操作能力时，请指导我执行，不要声称已经替我修改成功。

---

# Claude Code · Windows 配置教程

先完成一步，再继续下一步。已经完成的安装步骤可以跳过。

> 配置资料核对日期：2026-09-28。分组和模型可能调整，当前可用情况以 [Vmvia 模型广场](https://www.vmvia.com/pricing) 为准。

## 这份教程会帮你完成什么

安装并连接 Vmvia API，最后发送一条消息确认可以使用。所有 API Key 示例都是占位值 `sk-xxx`，实际 Key 只在你自己的软件中填写。

| 要填写的内容 | 本教程使用的值 |
| --- | --- |
| 工具 | Claude Code |
| 系统 | Windows |
| 令牌分组 | `cc_max`（倍率 1.8x） |
| Base URL | `https://www.vmvia.com` |
| 模型 | 在 CC Switch 中留空，使用 Claude 默认模型 |

## 1. 安装并打开工具

右键开始按钮，打开「终端」或「Windows PowerShell」。先从 [Git for Windows](https://git-scm.com/install/windows) 安装 Git，安装后重新打开终端。

```powershell
git --version
```

执行安装命令：

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

关闭并重新打开终端，再检查版本：

```powershell
claude --version
```

**完成标志**：版本检查能显示版本号，没有「找不到命令」的提示。

## 2. 准备 Vmvia API Key

**先看模型广场，再创建密钥。** 打开 [Vmvia 模型广场](https://www.vmvia.com/pricing)，用左侧「分组」筛选 `cc_max`，确认它当前支持的模型；后面填写 `model` 时，直接复制模型卡片上的完整名称，避免写错模型导致调用失败。

1. 登录 [Vmvia 控制台](https://www.vmvia.com/console/token)，进入「令牌」页面。
2. 新建或编辑一个令牌，分组选择 `cc_max`。**不要选 `default`**，该分组没有可用模型。
3. **关闭「模型限制」**，限制可调用模型有时会引发未知异常。
4. 保存并复制 API Key，稍后填入本机的软件。

本教程使用 `cc_max` 分组，它只允许 Claude Code 客户端内部调用，倍率 1.8x。如果你还想在 IDE 或其他第三方客户端里外接 Claude，请另外创建一个 `sale_kiro` 分组的令牌，见 [外接兼容说明](https://doc.vmvia.com/external-compat)。

**完成标志**：手中有一个 `cc_max` 分组的 API Key，令牌的模型限制已关闭。

## 3. 用 CC Switch 填写配置

### 使用前先确认两件事

> 1. **关闭路由模式**。CC Switch 的路由模式会把请求转一道，有时会掩盖真实报错，配置和排障时先关掉。
> 2. **保存后直接用客户端验证**。CC Switch 的「检测」按钮走的是它自己的探测请求，结果不一定代表 Claude Code 能否正常使用；保存并启用配置后，直接打开 Claude Code 发一条消息。

![CC Switch 路由模式开关示意，使用前请关闭](https://doc.vmvia.com/img/cc-switch/cc-switch-routing-toggle.png)

从 [CC Switch 发布页](https://github.com/farion1231/cc-switch/releases) 下载适合 Windows 的版本并安装。

**CC Switch 简称 ccs；Claude Code 简称 cc，两者是不同的软件。** CC Switch 的预设供应商列表里没有 Vmvia，按下面的步骤手动新建即可。

1. 打开 CC Switch，点击「添加配置」。
2. 框架选择 **Claude Code**。
3. 预设供应商选择 **「自定义配置」**。
4. 供应商名称填 `Vmvia`，官网链接填 `https://www.vmvia.com`。
5. 请求地址（Base URL）填 `https://www.vmvia.com`。
6. 把第 2 步准备的 API Key 填入对应输入框。
7. 模型留空，使用 Claude 默认模型。
8. 保存或点击「添加」，并确认已启用这个配置。
9. 重新打开终端。

确认 Base URL 是 `https://www.vmvia.com`。Claude Code 的地址**不带** `/v1`。

**完成标志**：CC Switch 已启用 Vmvia 配置，工具已重新打开。

## 4. 发一条消息验证

在终端执行：

```powershell
claude
```

如果出现工作目录信任提示，确认目录后按界面操作，再发送：**请只回复「配置成功」**。

**完成标志**：收到正常回复，没有 API Key 无效、模型不可用或连接失败的报错。

## 没成功时，先看这里

| 你看到的现象 | 先做什么 |
| --- | --- |
| 找不到命令 | 关闭并重新打开终端，再检查版本；Windows 下确认打开的是本教程指定的终端。 |
| API Key 无效 / 401 | 检查 Key 是否复制完整、是否过期，确认已启用正确的 Vmvia 配置。不要把完整 Key 发到聊天里。 |
| 模型不可用 | 检查令牌分组、模型名称和模型限制；以本教程的配置表和模型广场为准。 |
| 403 block | 先确认使用官方客户端和正确分组，第三方客户端另见完整手册的外接说明。 |
| 连接失败 / 一直等待 | 换一个可用网络，检查代理；主站不通时把地址换成国内优化线路 `https://api.vmvia.com`。记录完整错误文字，不要同时修改多个设置。 |

### 以前登录过 Claude 官方账号

如果 Vmvia 配置没有生效，先在终端执行 `claude auth logout` 退出旧账号，再用 CC Switch 重新启用 Vmvia 配置。不要同时混用官方 OAuth 登录和 Vmvia API Key。

## CC Switch 不可用时：手动配置

这是备用方式。已有配置时先备份，只合并下面涉及的字段，不要整份覆盖原文件。保存后重新打开工具。

配置文件：`%USERPROFILE%\.claude\settings.json`。

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://www.vmvia.com",
    "ANTHROPIC_API_KEY": "sk-xxx"
  }
}
```

把占位值 `sk-xxx` 替换成你自己的 API Key。

## 配好了，接下来

可以开始使用，也可以进入 [Claude Code 详细手册](https://doc.vmvia.com/claude-code) 查看更多配置。后续报错请保留错误原文、系统和工具版本，按 [报错手册](https://doc.vmvia.com/errors) 排查。