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

# Claude Code

> 在 Claude Code 中接入 AIHubMix：这款终端 AI 编程助手用单个 API key 即可跨厂商调用模型，享受稳定路由与统一计费。

## 快速开始

本指南将帮助您在几分钟内使用由 AIHubMix 提供的 Claude Code。

### 1. 安装 Claude Code

#### 本地安装

<CodeGroup>
  ```shellscript macOS theme={null}
  curl -fsSL https://claude.ai/install.sh | bash
  ```

  ```shellscript Windows theme={null}
  irm https://claude.ai/install.ps1 | iex
  ```
</CodeGroup>

#### 使用 npm 安装

需要 [Node.js 18 或更高版本](https://nodejs.org/en/download/)

```shellscript theme={null}
npm install -g @anthropic-ai/claude-code
```

### 2. 配置 AIHubMix API

要通过兼容 Anthropic API 的方式来接入 AIHubMix 的模型服务，需要配置以下环境变量。

1. 将 `ANTHROPIC_BASE_URL` 设置为 `https://aihubmix.com`
2. 将 `ANTHROPIC_AUTH_TOKEN` 设置为从 [AIHubMix 平台](https://console.aihubmix.com/token) 获取的 API Key
3. 将 `ANTHROPIC_MODEL` 设置为[模型列表](https://aihubmix.com/models)中支持的 Claude 模型，例如 `claude-sonnet-4-5`。

<Warning>
  `AIHUBMIX_API_KEY` 只是占位符，请替换成你自己的真实 Key（通常以 `sk-` 开头）。如果原样写入，Claude Code 会把它当成真正的 Key，并返回 `401 invalid key: AIHUBMIX_API_KEY`。
</Warning>

<Tabs>
  <Tab title="macOS">
    1. 在终端中执行以下命令，查看默认 Shell 类型。

    ```shellscript theme={null}
    echo $SHELL
    ```

    2. 根据 Shell 类型设置环境变量，命令如下：

    <CodeGroup>
      ```shellscript Zsh theme={null}
      # 将 <AIHUBMIX_API_KEY> 替换为你从 AIHubMix 平台获取的真实 Key
      echo 'export ANTHROPIC_BASE_URL="https://aihubmix.com"' >> ~/.zshrc
      echo 'export ANTHROPIC_AUTH_TOKEN="<AIHUBMIX_API_KEY>"' >> ~/.zshrc
      echo 'export ANTHROPIC_MODEL="claude-sonnet-4-5"' >> ~/.zshrc
      ```

      ```shellscript Bash theme={null}
      # 将 <AIHUBMIX_API_KEY> 替换为你从 AIHubMix 平台获取的真实 Key
      echo 'export ANTHROPIC_BASE_URL="https://aihubmix.com"' >> ~/.bash_profile
      echo 'export ANTHROPIC_AUTH_TOKEN="<AIHUBMIX_API_KEY>"' >> ~/.bash_profile
      echo 'export ANTHROPIC_MODEL="claude-sonnet-4-5"' >> ~/.bash_profile
      ```
    </CodeGroup>

    3. 在终端中执行下列命令，使环境变量生效。

    <CodeGroup>
      ```shellscript Zsh theme={null}
      source ~/.zshrc
      ```

      ```shellscript Bash theme={null}
      source ~/.bash_profile
      ```
    </CodeGroup>

    4. 打开一个新的终端，执行下列命令，查看环境变量是否生效。

    ```shellscript theme={null}
    echo $ANTHROPIC_BASE_URL
    test -n "$ANTHROPIC_AUTH_TOKEN" && echo "ANTHROPIC_AUTH_TOKEN is set"
    echo $ANTHROPIC_MODEL
    ```
  </Tab>

  <Tab title="Windows">
    在 Windows 中，可以通过 CMD 或 PowerShell 将 AIHubMix 的 Base URL 和 [API Key](https://console.aihubmix.com/token) 设置为环境变量。

    <Tabs>
      <Tab title="CMD">
        1. 在 CMD 中运行以下命令，设置环境变量。

        ```shellscript theme={null}
        REM 将 <AIHUBMIX_API_KEY> 替换为你从 AIHubMix 平台获取的真实 Key
        setx ANTHROPIC_AUTH_TOKEN "<AIHUBMIX_API_KEY>"
        setx ANTHROPIC_BASE_URL "https://aihubmix.com"
        setx ANTHROPIC_MODEL "claude-sonnet-4-5"
        ```

        2. 打开一个新的 CMD 窗口，运行以下命令，检查环境变量是否生效。

        ```shellscript theme={null}
        if defined ANTHROPIC_AUTH_TOKEN echo ANTHROPIC_AUTH_TOKEN is set
        echo %ANTHROPIC_BASE_URL%
        echo %ANTHROPIC_MODEL%
        ```
      </Tab>

      <Tab title="PowerShell">
        1. 在 PowerShell 中运行以下命令，设置环境变量。

        ```shellscript theme={null}
        # 将 <AIHUBMIX_API_KEY> 替换为你从 AIHubMix 平台获取的真实 Key
        [Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "<AIHUBMIX_API_KEY>", [EnvironmentVariableTarget]::User)
        [Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://aihubmix.com", [EnvironmentVariableTarget]::User)
        [Environment]::SetEnvironmentVariable("ANTHROPIC_MODEL", "claude-sonnet-4-5", [EnvironmentVariableTarget]::User)
        ```

        2. 打开一个新的 PowerShell 窗口，运行以下命令，检查环境变量是否生效。

        ```shellscript theme={null}
        if ($env:ANTHROPIC_AUTH_TOKEN) { "ANTHROPIC_AUTH_TOKEN is set" }
        echo $env:ANTHROPIC_BASE_URL
        echo $env:ANTHROPIC_MODEL
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

<Note>
  如果你准备通过 CC Switch 管理 Claude Code，建议不要再额外设置全局 `ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_BASE_URL`、`ANTHROPIC_MODEL`。系统或用户环境变量可能覆盖 CC Switch 写入的 Provider 配置，导致界面里选择了正确 Provider，但 Claude Code 实际仍使用旧 Key 或旧模型。
</Note>

### 3. 验证配置是否生效

完成环境变量或 CC Switch 配置后，建议先用一次最小请求确认 Key、模型和 Anthropic 兼容接口都可用，再启动长会话。

<CodeGroup>
  ```bash macOS/Linux theme={null}
  curl https://aihubmix.com/v1/messages \
    -H "content-type: application/json" \
    -H "anthropic-version: 2023-06-01" \
    -H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
    -d '{
      "model": "claude-sonnet-4-5",
      "max_tokens": 16,
      "messages": [{"role": "user", "content": "1+1, output only the answer"}]
    }'
  ```

  ```powershell Windows theme={null}
  curl.exe https://aihubmix.com/v1/messages `
    -H "content-type: application/json" `
    -H "anthropic-version: 2023-06-01" `
    -H "x-api-key: $env:ANTHROPIC_AUTH_TOKEN" `
    -d "{\"model\":\"claude-sonnet-4-5\",\"max_tokens\":16,\"messages\":[{\"role\":\"user\",\"content\":\"1+1, output only the answer\"}]}"
  ```
</CodeGroup>

如果返回 `200` 且内容为 `2`，说明 AIHubMix Key 与 Claude 模型可用。随后可以运行：

```bash theme={null}
claude -p "1+1, output only the answer" --model claude-sonnet-4-5
```

返回 `2` 即表示 Claude Code 端到端配置成功。

### 4. 开始使用

完成配置后，进入你的工作目录，在终端运行 `claude` 命令开始使用 Claude Code。

```bash theme={null}
$ cd /path/your-project
> claude
```

如果启动后看到 `Not logged in · Please run /login`，或进入 Anthropic 登录选项，通常说明 Claude Code 没有读取到可用的 AIHubMix 配置，或首次引导尚未完成。请先确认上一步最小请求可返回 `2`，并检查 `ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_BASE_URL`、`ANTHROPIC_MODEL` 是否被旧的全局环境变量覆盖。确认 Key 可用后，如仍进入登录流程，可按以下步骤跳过首次引导：

<img src="https://mintcdn.com/aihubmix/HZpz50Qb6hBBcBVb/public/cn/cc-7.jpg?fit=max&auto=format&n=HZpz50Qb6hBBcBVb&q=85&s=0d1309bcea8f4170809d104bc2b380a6" alt="Claude Code 首次启动时提示登录或继续配置的终端界面" width="1622" height="438" data-path="public/cn/cc-7.jpg" />

1. 定位用户主目录下的 `.claude.json` 文件，具体路径如下：
   * macOS / Linux: `~/.claude.json`
   * Windows: `C:\Users\%USERNAME%\.claude.json`
2. 设置`hasCompletedOnboarding` 字段的值为 `true`

```json theme={null}
{
  "hasCompletedOnboarding": true
}
```

3. 保存文件，然后在终端中重新运行 `claude` 。

#### （可选）更多配置模型的方式

Claude Code 支持以下模型配置方式，**按优先级从高到低排列**，优先级高的配置会覆盖优先级低的配置。

1. **对话期间：** 执行`/model <模型名称>`命令切换模型。适用于临时切换模型。

```text theme={null}
/model claude-sonnet-4-5
```

2. **启动 Claude Code 时：** 执行`claude --model <模型名称>`指定模型。适用于单次会话。

```text theme={null}
claude --model claude-sonnet-4-5
```

3. **设置环境变量**：可按任务复杂度配置不同级别的模型，Claude Code 会根据任务类型自动选择合适的模型。适用于全局生效。

```shellscript theme={null}
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-5"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-5"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5"
```

其中：

* `ANTHROPIC_DEFAULT_OPUS_MODEL`：用于复杂推理、架构设计等高难度任务。
* `ANTHROPIC_DEFAULT_SONNET_MODEL`：用于代码编写、功能实现等日常任务。
* `ANTHROPIC_DEFAULT_HAIKU_MODEL`：用于语法检查、文件搜索等简单任务。

4. **在 settings.json 配置文件中永久设置**：在 Claude Code 的用户配置文件（如 `~/.claude/settings.json`，Windows 为 `C:\Users\%USERNAME%\.claude\settings.json`）或项目级配置中写入模型配置信息，可分别进行用户级或项目级的永久配置。

<Note>
  **兜底配置：** 如果前面的 `/model`、启动参数、环境变量或 CC Switch 配置没有生效，或 Claude Code 仍读取旧模型，可直接编辑 `settings.json`。下面示例同时设置 `ANTHROPIC_MODEL` 和顶层 `model`，并保留 Opus、Sonnet、Haiku 三个槽位的模型名称。
</Note>

```json theme={null}
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "<AIHUBMIX_API_KEY>",
    "ANTHROPIC_BASE_URL": "https://aihubmix.com",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "gemini-3.5-flash",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME": "gemini-3.5-flash",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "gemini-3.5-flash",
    "ANTHROPIC_DEFAULT_OPUS_MODEL_NAME": "gemini-3.5-flash",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "gemini-3.5-flash",
    "ANTHROPIC_DEFAULT_SONNET_MODEL_NAME": "gemini-3.5-flash",
    "ANTHROPIC_MODEL": "gpt-5.5"
  },
  "model": "gpt-5.5"
}
```

将 `<AIHUBMIX_API_KEY>` 替换为你自己的真实 Key。保存后需要重新启动 Claude Code，再输入 `/models` 查看当前会话可切换的模型。

## 如何通过 CC Switch 配置？

1. 运行 CC Switch，先在左侧选择 **Claude Code**，再点击「添加供应商」。

<img src="https://mintcdn.com/aihubmix/l2uHw7hd14guDu0f/public/cn/cc-1.jpg?fit=max&auto=format&n=l2uHw7hd14guDu0f&q=85&s=257b71ad7c6f876ac31147b7fd81f169" alt="CC Switch 首页中点击添加供应商入口的界面" width="2068" height="1370" data-path="public/cn/cc-1.jpg" />

2. 在预设列表中选择「AiHubMix」。请确认当前配置的是 Claude Code 侧的 Provider。

<img src="https://mintcdn.com/aihubmix/l2uHw7hd14guDu0f/public/cn/cc-2.jpg?fit=max&auto=format&n=l2uHw7hd14guDu0f&q=85&s=16dcb0697fdbf6438d4452ff8c39e485" alt="CC Switch 供应商预设列表中选择 AiHubMix 的界面" width="2072" height="1376" data-path="public/cn/cc-2.jpg" />

3. 在「API Key」栏中填写你的真实密钥。

<img src="https://mintcdn.com/aihubmix/qVeqJ54P7wCzwnj-/public/cn/cc-3.jpg?fit=max&auto=format&n=qVeqJ54P7wCzwnj-&q=85&s=30deb64e7737ba515d70b161ee19ea58" alt="CC Switch AiHubMix 配置表单中填写 API Key 的界面" width="2070" height="1372" data-path="public/cn/cc-3.jpg" />

4. 配置完成后，先使用 `claude-sonnet-4-5` 作为模型 ID，点击「添加」保存设置。确认健康检查通过后，可在 Claude Code 中通过 `/models` 或 `/model` 切换其他 Claude 模型。
   <Frame>
     <img src="https://mintcdn.com/aihubmix/KvaXxbOiAML2UsXS/images/img_v3_02116_2b161aa5-e317-4cbb-800f-5933d520b55g.jpg?fit=max&auto=format&n=KvaXxbOiAML2UsXS&q=85&s=167988610ef93d855b40f8618f23f9e4" alt="AIHubMix 模型列表中复制 Claude 模型 ID 的界面" width="3008" height="1632" data-path="images/img_v3_02116_2b161aa5-e317-4cbb-800f-5933d520b55g.jpg" />
   </Frame>
5. 返回首页，在供应商列表中选择「AiHubMix」，点击「启动」即可使用。

<img src="https://mintcdn.com/aihubmix/l2uHw7hd14guDu0f/public/cn/cc-5.jpg?fit=max&auto=format&n=l2uHw7hd14guDu0f&q=85&s=4e765832e55e9737c91e2b40bf127c5d" alt="CC Switch 首页中选择 AiHubMix 并点击启动的界面" width="2068" height="1366" data-path="public/cn/cc-5.jpg" />

> <Frame>
>   <img src="https://mintcdn.com/aihubmix/mDZumr5HeEPTKpFC/images/image-68.png?fit=max&auto=format&n=mDZumr5HeEPTKpFC&q=85&s=a6dd56f69a939f0a6b174cefc371cee7" alt="Claude Code 终端中使用 status 和 models 命令查看模型配置" width="1142" height="1068" data-path="images/image-68.png" />
> </Frame>
>
> Tip: 终端打开 Claude Code后，输入 <kbd> /status </kbd>可查询模型ID，输入<kbd>/models </kbd>可选择配置的其他模型

<Warning>
  如果 CC Switch 提示「检测到系统环境变量冲突」，请优先处理 `ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_BASE_URL`、`ANTHROPIC_MODEL`。这些全局变量会覆盖当前 Provider 配置；其中 `ANTHROPIC_AUTH_TOKEN=AIHUBMIX_API_KEY` 这类占位符值会直接导致认证失败。确认不再需要全局变量后，可在 CC Switch 中删除冲突项，或手动删除系统/用户环境变量，然后重启终端。
</Warning>

## 如何通过 VS Code 插件配置？

1. 运行 VS Code，安装插件。

<Frame>
  <img src="https://mintcdn.com/aihubmix/XPAbnoWWzjetSWAU/images/iShot_2026-03-25_11.44.03.jpg?fit=max&auto=format&n=XPAbnoWWzjetSWAU&q=85&s=7fd42add3df2e072c3d8d85eb19c785d" alt="VS Code 扩展市场中安装 Claude Code 插件的界面" width="1958" height="724" data-path="images/iShot_2026-03-25_11.44.03.jpg" />
</Frame>

2. 按下 `Ctrl + Shift + P` (或 `Cmd + Shift + P`)，输入 `Settings` 打开设置。

<Frame>
  <img src="https://mintcdn.com/aihubmix/XPAbnoWWzjetSWAU/images/iShot_2026-03-25_11.47.48.jpg?fit=max&auto=format&n=XPAbnoWWzjetSWAU&q=85&s=c7b448a36e1886a4a1cdc9103f3844f6" alt="VS Code 命令面板中打开 Settings 设置页的界面" width="1772" height="976" data-path="images/iShot_2026-03-25_11.47.48.jpg" />
</Frame>

3. 搜索 `Claude Code` ，找到 `Claude Code: Environment Variable` → `Edit in settings.json` 。

<Frame>
  <img src="https://mintcdn.com/aihubmix/XPAbnoWWzjetSWAU/images/iShot_2026-03-25_11.49.37.jpg?fit=max&auto=format&n=XPAbnoWWzjetSWAU&q=85&s=3f5a87bc619bcb552eb4ed78da6527b6" alt="VS Code 设置中搜索 Claude Code 环境变量配置项的界面" width="1940" height="1248" data-path="images/iShot_2026-03-25_11.49.37.jpg" />
</Frame>

4. 在 `claudeCode.environmentVariables` 中填入 AIHubMix 相关信息。

<Frame>
  <img src="https://mintcdn.com/aihubmix/XPAbnoWWzjetSWAU/images/iShot_2026-03-25_11.53.07.jpg?fit=max&auto=format&n=XPAbnoWWzjetSWAU&q=85&s=9a1355dac10acd90f0834f2f091ac3a7" alt="VS Code settings.json 中配置 Claude Code 环境变量的示例" width="1156" height="304" data-path="images/iShot_2026-03-25_11.53.07.jpg" />
</Frame>

## [Wechat-Agent-SDK](https://github.com/AIhubmix/wechat-agent-sdk)

通过简单的接口调用，一键将 Claude Code、Codex、Kimi 等主流 AI 智能体接入微信。支持 ACP 协议，纯本地运行，无需服务器、无需数据库，内置断点续传、自动重连等企业级特性，让您的 AI 助手轻松在微信中智能对话。

> 安装地址：[https://github.com/AIhubmix/wechat-agent-sdk](https://github.com/AIhubmix/wechat-agent-sdk)

## 常见问题

### Q：提示 `401` 认证错误怎么办？

`401` 表示请求没有通过认证，但具体原因要看完整错误消息：

* `No token provided`：没有传入 Key。打开 Claude Code，输入 `/config`，找到 `Use custom API key` 选项，检查 Token 是否已配置。
* `invalid key: AIHUBMIX_API_KEY`：通常表示把示例占位符原样写入了环境变量。请在 AIHubMix 控制台重新复制真实 Key，并更新 `ANTHROPIC_AUTH_TOKEN`。
* `this key is not enabled`：请求已到达 AIHubMix，但当前 Key 尚未启用或没有调用权限。请在 [AIHubMix 控制台](https://console.aihubmix.com/token) 检查该 Key 是否启用、是否过期、是否有额度，并确认它可以调用你选择的 Claude 模型。

<img src="https://mintcdn.com/aihubmix/Sq3QhNkLGyt6npNr/public/cn/cc-6.png?fit=max&auto=format&n=Sq3QhNkLGyt6npNr&q=85&s=27b1369c8b3970c789b7585e060bde07" alt="Claude Code config 中检查自定义 API Key 的界面" width="1220" height="760" data-path="public/cn/cc-6.png" />

在 Windows 上还要检查用户环境变量或系统环境变量中是否保留了旧值：

```powershell theme={null}
[Environment]::GetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "User")
[Environment]::GetEnvironmentVariable("ANTHROPIC_BASE_URL", "User")
[Environment]::GetEnvironmentVariable("ANTHROPIC_MODEL", "User")
```

如果你使用 CC Switch 管理配置，建议删除这些全局 `ANTHROPIC_*` 变量，让 CC Switch 当前 Provider 接管配置。

注意：`/v1/models` 可能在无有效 Key 时也能返回模型列表，因此不能用它判断 Key 是否可用。请参考上文「如何验证配置是否生效？」中的最小消息请求；如果返回 `200` 且内容为 `2`，说明 Key 与模型可用，再重启 Claude Code 或通过 CC Switch 重新启动即可。

### Q：提示 `400 Incorrect model ID` 或 `Bad request (400)` 怎么办？

这通常表示请求格式已到达供应商侧，但模型 ID 不正确、模型名称与接口不匹配，或当前 Key 没有调用该模型的权限。请在 [AIHubMix 模型列表](https://aihubmix.com/models) 中重新复制完整模型 ID，确认没有手动拼写、大小写或系列名称错误。

如果你通过 CC Switch 配置，请回到对应 Provider，更新模型 ID 后保存，并重新启动 Claude Code。如果仍然报错，可先换用模型列表中确认可用的 Claude 模型完成健康检查，再切换到目标模型。

### Q：macOS 中安装成功后仍然报错：`zsh: command not found: claude`

这是因为 Claude CLI 已安装，但其可执行目录未加入系统 `PATH`。

1. 确认 Claude 安装路径。Claude Code 官方脚本通常安装在以下目录之一：

* `~/.claude/bin`
* `~/.local/bin`

在终端执行：

```shellscript theme={null}
ls -l ~/.claude/bin
或
ls -l ~/.local/bin | grep claude
```

如果看到 claude 文件，说明安装成功，只是 PATH 未配置。

2. 将安装目录加入 PATH。根据实际安装位置执行对应命令：

#### 情况 A：安装在 `~/.claude/bin`

```shellscript theme={null}
echo 'export PATH="$HOME/.claude/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

#### 情况 B：安装在 `~/.local/bin`

```shellscript theme={null}
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

3. 验证是否生效。执行：

```text theme={null}
which claude
claude -v
```

若能看到 `claude` 路径及版本号，说明安装成功。

### Q：Claude Code 无法连接 Anthropic 服务

升级到最新版本的 Claude Code 后，若出现无法连接 Anthropic 服务或认证失败的情况，通常是由于认证请求头名称已发生调整所致。新版本要求将请求头由 `ANTHROPIC_API_KEY` 修改为 `ANTHROPIC_AUTH_TOKEN`，API Key 的值无需更换，仅需更新请求头名称并重新加载配置即可。具体操作可参考本文档重新配置。

## 更多资源

* [Github](https://github.com/inferera/aihubmix/blob/main/packages/claude-code/README.md)
* [npm 包](https://www.npmjs.com/package/@aihubmix/claude-code)
* [官方最佳实践](https://www.anthropic.com/engineering/claude-code-best-practices)
* [官方配置指引](https://docs.anthropic.com/en/docs/claude-code/settings#settings-files)

祝您使用愉快！

最新更新日期：2026年6月9日