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

# Claude Code CLI

> 将 Claude Code CLI 连接到 AihubMax

## 概述

[Claude Code](https://docs.anthropic.com/en/docs/claude-code) 是 Anthropic 官方推出的命令行工具，可将 Claude 的智能直接带入你的终端。它能够理解你的代码库、编辑文件、运行命令，并帮助你更快地构建软件。

通过将 Claude Code CLI 连接到 [AihubMax](https://api.aihubmax.com/console)，你可以借助 AihubMax 稳定可靠的 API 基础设施来使用 Claude 的全部能力——**国内网络直连**、**按量付费余额不过期**、**渠道透明可溯源**。

<Info>
  我们提供了专为 Claude Code CLI 优化的端点。请使用 `https://api.aihubmax.com` 作为 Base URL 以获得最佳体验。
</Info>

## 前置条件

<CardGroup cols={2}>
  <Card title="Node.js 18+" icon="node-js">
    通过 npm 安装 Claude Code 需要 Node.js 18 或更高版本。[下载 Node.js →](https://nodejs.org/zh-cn/download/)
  </Card>

  <Card title="Git" icon="git-alt">
    Claude Code 运行时需要 Git 支持。[下载 Git →](https://git-scm.com/downloads)
  </Card>

  <Card title="AihubMax API Key" icon="key">
    你需要一个有效的 AihubMax API Key。获取方式见下方安装步骤。[前往 AihubMax →](https://api.aihubmax.com/console)
  </Card>

  <Card title="Python（可选）" icon="python">
    部分高级功能可能需要 Python 环境。[下载 Python →](https://www.python.org/downloads/)
  </Card>
</CardGroup>

安装完成后，打开终端（Windows 为 PowerShell）验证环境：

```bash theme={null}
node -v
git --version
```

<Tip>
  **Windows 用户注意**：如果执行命令报错，请以**管理员身份**运行 PowerShell，执行以下命令后选择 `A`：

  ```bash theme={null}
  Set-ExecutionPolicy RemoteSigned
  ```

  ![Windows 执行策略设置](https://zdaif.oss-cn-hangzhou.aliyuncs.com/asset/img/pages/aihubmax/20260328203750072.png)
</Tip>

## 安装与配置

<Steps>
  <Step title="第一步：安装 Claude Code CLI">
    根据你的操作系统选择安装方式：

    <Tabs>
      <Tab title="Windows（npm）">
        打开一个**新的** PowerShell 窗口，执行：

        ```bash theme={null}
        npm install -g @anthropic-ai/claude-code
        ```
      </Tab>

      <Tab title="macOS / Linux（推荐）">
        ```bash theme={null}
        npm install -g @anthropic-ai/claude-code
        ```
      </Tab>

      <Tab title="macOS / Linux（npm）">
        ```bash theme={null}
        npm install -g @anthropic-ai/claude-code
        ```
      </Tab>
    </Tabs>

    安装完成后，验证是否成功：

    ```bash theme={null}
    claude --version
    ```
  </Step>

  <Step title="第二步：获取 API Key">
    前往 [AihubMax 控制台](https://api.aihubmax.com/console)完成以下步骤：

    1. **注册账号**：访问 [api.aihubmax.com](https://api.aihubmax.com/console) 注册
    2. **创建密钥**：在控制台的 API 密钥页面，点击「创建密钥」

    <Warning>
      创建密钥时**必须选择「Claude-Max」分组**，这是 Claude Code 专用的官方渠道，效果最好。其他分组可能不支持 Claude Code 或存在功能限制。
    </Warning>
  </Step>

  <Step title="第三步：配置环境">
    推荐使用 **CC-Switch** 工具一键配置，也可以手动编辑配置文件。

    <Tabs>
      <Tab title="CC-Switch（推荐）">
        [CC-Switch](https://github.com/farion1231/cc-switch/releases) 是一款专为 Claude Code 打造的环境配置工具，支持一键导入 API Key。

        1. 前往 [CC-Switch GitHub Releases](https://github.com/farion1231/cc-switch/releases) 下载安装：
           * **Windows**：下载 `CC-Switch-xxxx-Windows.msi` 并安装
           * **macOS**：下载 `CC-Switch-xxxx-macOS.dmg` 并安装
        2. 打开 AihubMax 控制台的 API 密钥页面，点击 **「导入到 CCS」** 按钮即可自动完成配置

        ![通过 AihubMax 导入到 CC-Switch](https://zdaif.oss-cn-hangzhou.aliyuncs.com/asset/img/pages/aihubmax/20260329003930220.png)
      </Tab>

      <Tab title="配置文件（手动）">
        创建或编辑 Claude Code 配置文件 `~/.claude/settings.json`（Windows 为 `%USERPROFILE%\.claude\settings.json`）：

        ```json theme={null}
        {
          "env": {
            "ANTHROPIC_AUTH_TOKEN": "sk-your-foxapi-api-key",
            "ANTHROPIC_BASE_URL": "https://api.aihubmax.com",
            "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
          }
        }
        ```
      </Tab>

      <Tab title="环境变量（手动）">
        在 Shell 配置文件（`~/.bashrc`、`~/.zshrc` 等）中添加：

        ```bash theme={null}
        export ANTHROPIC_AUTH_TOKEN="sk-your-foxapi-api-key"
        export ANTHROPIC_BASE_URL="https://api.aihubmax.com"
        export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
        ```

        添加后执行 `source ~/.zshrc`（或对应的配置文件）使其生效。
      </Tab>
    </Tabs>

    <Warning>
      `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 设置是**必须的**。它会阻止 Claude Code 向 Anthropic 官方服务器发送遥测和其他非必要请求。如果不设置此项，这些请求会因缺少官方 API Key 而失败，可能导致异常。
    </Warning>
  </Step>

  <Step title="第四步：安装 VSCode 插件（可选）">
    如果你使用 VSCode，可以安装官方插件获得更好的集成体验：

    1. 下载安装 [VSCode](https://code.visualstudio.com/)
    2. 在扩展商店搜索 **Claude Code**，安装时注意确认作者为 **Anthropic**

    ![确认作者为 Anthropic](https://zdaif.oss-cn-hangzhou.aliyuncs.com/asset/img/pages/aihubmax/20260328204844201.png)

    3. 安装后在 VSCode 侧边栏即可看到 Claude Code 面板

    ![VSCode 中的 Claude Code 面板](https://zdaif.oss-cn-hangzhou.aliyuncs.com/asset/img/pages/aihubmax/20260328204857007.png)

    <Tip>
      如果没有出现右侧面板，便是环境变量没有配置好，或者 **AihubMax 账户欠费**。
    </Tip>

    <div style={{display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '16px'}}>
      <img src="https://zdaif.oss-cn-hangzhou.aliyuncs.com/asset/img/pages/aihubmax/20260329011614823.png" alt="环境变量未配置或账户欠费" />

      <img src="https://zdaif.oss-cn-hangzhou.aliyuncs.com/asset/img/pages/aihubmax/20260329011621373.png" alt="配置成功后的面板" />
    </div>
  </Step>

  <Step title="第五步：开始使用">
    <Tabs>
      <Tab title="终端交互模式">
        在你的项目目录中启动 Claude Code：

        ```bash theme={null}
        cd /path/to/your/project
        claude
        ```

        这将打开一个交互式会话，你可以在其中与 Claude 讨论你的代码库。

        ![Claude Code 正常工作界面](https://zdaif.oss-cn-hangzhou.aliyuncs.com/asset/img/pages/aihubmax/20260329011621373.png)
      </Tab>

      <Tab title="VS Code">
        在 VS Code 中打开命令面板（`Ctrl+Shift+P` / `Cmd+Shift+P`），搜索 `Claude: Open` 即可启动。

        ![VSCode Claude Code 面板入口](https://zdaif.oss-cn-hangzhou.aliyuncs.com/asset/img/pages/aihubmax/20260328204857007.png)
      </Tab>

      <Tab title="单次命令">
        无需进入交互模式，直接运行单次命令：

        ```bash theme={null}
        claude "解释一下这个项目的架构"
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

## 验证连接

运行以下命令确认 Claude Code 已正确通过 AihubMax 路由：

```bash theme={null}
claude "你好，请确认你正在正常工作。"
```

如果配置正确，Claude 会正常回复。如果看到错误信息，请查看下方的[常见问题](#常见问题)部分。

## 使用示例

<AccordionGroup>
  <Accordion title="探索代码库">
    ```bash theme={null}
    claude "给我一个这个项目架构的概览"
    ```
  </Accordion>

  <Accordion title="修复 Bug">
    ```bash theme={null}
    claude "登录流程中有一个 Bug，用户认证后被重定向到 404 页面，请找到并修复它。"
    ```
  </Accordion>

  <Accordion title="编写测试">
    ```bash theme={null}
    claude "为 UserService 类编写单元测试"
    ```
  </Accordion>

  <Accordion title="重构代码">
    ```bash theme={null}
    claude "将 src/repositories 中的数据库查询重构为参数化查询"
    ```
  </Accordion>
</AccordionGroup>

## 常见问题

<AccordionGroup>
  <Accordion title="错误：认证失败或 401 Unauthorized">
    * 仔细检查 `ANTHROPIC_AUTH_TOKEN` 的值，它应该是你的 AihubMax API Key（以 `sk-` 开头）。
    * 确认 API Key 未过期且账户余额充足。
    * 确认该 Key 在你的 AihubMax 账户中有权限访问 Claude 模型。
  </Accordion>

  <Accordion title="错误：连接被拒绝或超时">
    * 确认 `ANTHROPIC_BASE_URL` 设置为 `https://api.aihubmax.com`（末尾不要加斜杠）。
    * 检查你的网络连接，确保能够访问 `api.aihubmax.com`。
    * 如果你在公司代理后面，请确保代理允许 HTTPS 流量访问 `api.aihubmax.com`。
  </Accordion>

  <Accordion title="Claude Code 仍然尝试直连 Anthropic">
    * 确保 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 已设置为 `1`。
    * 如果使用 `settings.json`，确保 JSON 格式正确（没有多余的逗号、引号正确配对）。
    * 修改环境变量或配置文件后，重新启动终端。
  </Accordion>

  <Accordion title="配置文件不生效">
    * 确认文件位于 `~/.claude/settings.json`（不是项目目录内部）。
    * 使用 `jq` 等工具验证 JSON 格式：
      ```bash theme={null}
      cat ~/.claude/settings.json | jq .
      ```
    * 确保 Shell 配置文件中没有设置冲突的环境变量覆盖了配置文件的设置。
  </Accordion>
</AccordionGroup>

## 注意事项

<Note>
  * **不要将 API Key 提交到版本控制系统**。如果使用环境变量，请将其添加到 Shell 配置文件而非项目文件中。
  * **尽量使用专用 Key**。AihubMax 允许你创建多个 API Key，建议为 Claude Code 创建专用 Key，以便在需要时可以单独撤销。
  * **在 AihubMax 控制台监控用量**，以便及时发现异常消耗。
</Note>