> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hairoute.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code

> 通过 CC Switch 或直接配置 CLI 将 Claude Code 接入 HaiRoute

Claude Code 可以通过两种方式接入 HaiRoute：使用 **CC Switch** 配置，或直接通过环境变量配置 **Claude Code CLI**。两种方式都使用 HaiRoute 的 Anthropic Messages 协议。

| 方式            | 推荐场景                                           |
| ------------- | ---------------------------------------------- |
| **CC Switch** | 希望使用可视化配置、统一管理供应商或模型映射，或不希望手动设置终端环境变量。         |
| **直接配置 CLI**  | 偏好轻量的纯终端接入、需要在脚本或 CI 中使用，或希望通过 shell 配置文件统一管理。 |

## 协议与地址说明

Claude Code 使用 Anthropic Messages 协议。在 CC Switch 中请选择 **Anthropic Messages（原生）**，并将接口地址填写为 `https://api.hairoute.ai`。CC Switch 会通过 HaiRoute 的 `POST /v1/messages` 接口发起请求。

<Note>
  接口地址只填写 `https://api.hairoute.ai`，不要追加 `/v1` 或 `/v1/messages`。
</Note>

## 准备信息

* 已安装 Claude Code
* HaiRoute API Key
* 至少一个当前 API Key 可用的模型 ID
* 若使用 CC Switch 方式，需安装 CC Switch

## 方式一：通过 CC Switch 配置（推荐）

### 步骤 1：选择 Claude Code 并新增供应商

打开 CC Switch，在顶部应用栏选择 **Claude Code / Claude Official**，再点击右上角 **+** 新增供应商。

<img src="https://mintcdn.com/hai-token/_6nNjs176oTbHvVD/images/claude/PixPin_2026-08-17_16-54-24.png?fit=max&auto=format&n=_6nNjs176oTbHvVD&q=85&s=1e15169d9d6cf320973ac4866f48b49b" alt="在 CC Switch 中选择 Claude Code 并新增供应商" width="1108" height="632" data-path="images/claude/PixPin_2026-08-17_16-54-24.png" />

### 步骤 2：选择自定义配置并填写 API Key

在 **Claude 供应商** 页签中：

1. 选择 **自定义配置**。
2. 可选：填写供应商名称，例如 `HaiRoute`。
3. 在 **API Key** 中粘贴你的 HaiRoute API Key。

<img src="https://mintcdn.com/hai-token/_6nNjs176oTbHvVD/images/claude/PixPin_2026-08-17_16-55-17.png?fit=max&auto=format&n=_6nNjs176oTbHvVD&q=85&s=961055997ee07717280aca89d05ca244" alt="选择自定义配置并填写 API Key" width="1106" height="1308" data-path="images/claude/PixPin_2026-08-17_16-55-17.png" />

### 步骤 3：完成供应商配置

向下滚动，按下表填写剩余配置：

| 字段     | 填写值                         |
| ------ | --------------------------- |
| 请求地址   | `https://api.hairoute.ai`   |
| API 格式 | **Anthropic Messages（原生）**  |
| 认证字段   | 保持默认：`ANTHROPIC_AUTH_TOKEN` |

填好 API Key 和请求地址后，点击 **获取模型列表**。CC Switch 应提示已获取当前 API Key 可用的模型。

<img src="https://mintcdn.com/hai-token/_6nNjs176oTbHvVD/images/claude/PixPin_2026-08-17_16-59-17.png?fit=max&auto=format&n=_6nNjs176oTbHvVD&q=85&s=18c1f1f7f9b464d83be28798eec31b97" alt="填写接口地址、协议、认证字段和模型映射" width="1106" height="1308" data-path="images/claude/PixPin_2026-08-17_16-59-17.png" />

### 步骤 4：将 Claude 角色映射到 HaiRoute 模型

在 **模型映射** 中，为需要使用的 Claude 角色选择模型：

* **Sonnet** 通常作为主力编程模型。
* **Opus**、**Haiku** 等角色按需填写即可。
* 必须选择 HaiRoute 实际提供的模型 ID，实际请求模型值需与该 ID 完全一致。

**认证字段** 填写的是 Claude Code 使用的环境变量名，不是 API Key 本身。请保持 `ANTHROPIC_AUTH_TOKEN` 不变，真实 API Key 填写在上方的 **API Key** 字段中。

### 步骤 5：保存并测试

点击 **添加**，确认新供应商已对 Claude Code 生效，然后启动或重启 Claude Code，发送一条简单请求，例如 `hello`。

能够正常返回内容，即表示 Claude Code 已通过 CC Switch 接入 HaiRoute。

## 方式二：直接配置 Claude Code CLI

如果希望不依赖 CC Switch，可直接在启动 Claude Code 的终端中设置环境变量。

### 步骤 1：设置 API Key、接口地址和默认模型

Windows PowerShell：

```powershell theme={null}
$env:ANTHROPIC_AUTH_TOKEN = "YOUR_API_KEY"
$env:ANTHROPIC_BASE_URL = "https://api.hairoute.ai"
$env:ANTHROPIC_MODEL = "claude-sonnet-4-0"
claude
```

macOS / Linux：

```bash theme={null}
export ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY"
export ANTHROPIC_BASE_URL="https://api.hairoute.ai"
export ANTHROPIC_MODEL="claude-sonnet-4-0"
claude
```

请将 `claude-sonnet-4-0` 换成当前 API Key 实际可用的模型 ID。`ANTHROPIC_BASE_URL` 只填写 `https://api.hairoute.ai`，不要追加 `/v1` 或 `/v1/messages`。

### 步骤 2：指定或切换模型

你可以通过 `ANTHROPIC_MODEL` 设置默认模型，也可以在单次启动时指定模型，或在 Claude Code 会话中切换：

```bash theme={null}
claude --model claude-sonnet-4-0
```

在 Claude Code 会话中输入：

```text theme={null}
/model
```

`/model` 会立即对当前会话生效。`--model` 仅影响本次启动，并会覆盖该会话中的 `ANTHROPIC_MODEL`。

### 步骤 3：按需持久化配置

上述命令只对当前终端会话有效。如需长期使用，请将相同的环境变量写入配置文件：Windows 写入 PowerShell Profile；macOS 或使用 zsh 的 Linux 写入 `~/.zshrc`；使用 bash 的 Linux 写入 `~/.bashrc`。保存后重新打开终端，再运行 `claude`。

### 步骤 4：验证直接 CLI 接入

从已设置环境变量的终端启动 Claude Code，发送一条简单请求，例如 `hello`。能够正常返回内容，即表示 Claude Code 已直接通过 HaiRoute 接入。

## 验证清单

1. CC Switch 中该供应商已对 Claude Code 启用。
2. **获取模型列表** 成功，并返回当前 API Key 可用模型。
3. 请求地址为 `https://api.hairoute.ai`，不带路径和末尾斜杠。
4. API 格式为 **Anthropic Messages（原生）**。
5. 重启 Claude Code 后可正常回复。

## 常见问题

| 问题                          | 解决方案                                                                          |
| --------------------------- | ----------------------------------------------------------------------------- |
| 获取模型时报 `404`                | 确认请求地址严格填写为 `https://api.hairoute.ai`，不要添加 `/v1` 或 `/v1/messages`。            |
| Claude Code 提示鉴权失败          | 检查 **API Key** 是否填写了 HaiRoute API Key，并确认 **认证字段** 仍为 `ANTHROPIC_AUTH_TOKEN`。 |
| 已保存供应商，但 Claude Code 仍使用旧配置 | 在 CC Switch 中启用新供应商，然后彻底退出并重启 Claude Code。                                    |
| 映射的模型无法使用                   | 重新获取模型列表，并确认实际请求模型 ID 与当前 API Key 可用的模型 ID 完全一致。                              |
| 直接配置 CLI 后鉴权失败              | 确认 `ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_BASE_URL` 是在启动 `claude` 的同一个终端中设置的。      |
| 直接配置 CLI 后找不到模型             | 使用当前 API Key 可用的模型 ID，并通过 `ANTHROPIC_MODEL`、`claude --model` 或 `/model` 指定。   |

## 下一步

* 查看 [获取 API Key](/docs/zh/quickstart/get-api-key)
* 查看 [Claude 格式 API](/docs/zh/api-reference/chat/claude-format)
* 查看 [模型列表](/docs/zh/api-reference/models/list-models)