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

# Claude Code

> 将 AIOHub 配置为 Claude Code 的模型服务商。

[Claude Code](https://www.anthropic.com/claude-code) 使用 Anthropic Messages API。AIOHub 接入 Claude Code 时，`ANTHROPIC_BASE_URL` 填网关根地址，Claude Code 会自行追加 `/v1/messages`。

## 前置条件

* 已安装 Claude Code（需要 Node.js 18+）
* 已 [创建 AIOHub API 令牌](/cn/account/create-token)
* API 令牌的分组包含 Claude / Anthropic-compatible 模型
* 账户有充足余额

## 配置方法

### 方法一：环境变量（推荐）

在终端中设置环境变量后启动 Claude Code：

```bash theme={"system"}
export ANTHROPIC_BASE_URL="https://api.aiohub.org"
export ANTHROPIC_AUTH_TOKEN="sk-你的API令牌"
export ANTHROPIC_MODEL="claude-sonnet-4-20250514"
claude
```

<Note>`ANTHROPIC_BASE_URL` 不要加 `/v1`。`ANTHROPIC_AUTH_TOKEN` 填完整的 `sk-` API 令牌值，不要手动加 `Bearer `；Claude Code 会通过 Authorization Bearer 鉴权发送。</Note>

### 方法二：写入 Shell 配置文件

将环境变量添加到 Shell 启动配置中，每次打开终端自动生效：

<Tabs>
  <Tab title="macOS / Linux (zsh)">
    ```bash theme={"system"}
    # 编辑 ~/.zshrc
    echo 'export ANTHROPIC_BASE_URL="https://api.aiohub.org"' >> ~/.zshrc
    echo 'export ANTHROPIC_AUTH_TOKEN="sk-你的API令牌"' >> ~/.zshrc
    echo 'export ANTHROPIC_MODEL="claude-sonnet-4-20250514"' >> ~/.zshrc
    source ~/.zshrc
    ```
  </Tab>

  <Tab title="macOS / Linux (bash)">
    ```bash theme={"system"}
    # 编辑 ~/.bashrc
    echo 'export ANTHROPIC_BASE_URL="https://api.aiohub.org"' >> ~/.bashrc
    echo 'export ANTHROPIC_AUTH_TOKEN="sk-你的API令牌"' >> ~/.bashrc
    echo 'export ANTHROPIC_MODEL="claude-sonnet-4-20250514"' >> ~/.bashrc
    source ~/.bashrc
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    ```powershell theme={"system"}
    [System.Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://api.aiohub.org", "User")
    [System.Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "sk-你的API令牌", "User")
    [System.Environment]::SetEnvironmentVariable("ANTHROPIC_MODEL", "claude-sonnet-4-20250514", "User")
    ```

    设置后重启终端生效。
  </Tab>
</Tabs>

### 方法三：别名

创建一个命令别名，在需要时快速启动：

```bash theme={"system"}
# 添加到 ~/.zshrc 或 ~/.bashrc
alias mycc="ANTHROPIC_BASE_URL=https://api.aiohub.org ANTHROPIC_AUTH_TOKEN=sk-你的API令牌 ANTHROPIC_MODEL=claude-sonnet-4-20250514 claude"
```

之后运行 `mycc` 即可启动使用 AIOHub 的 Claude Code。

### 方法四：settings.json

在 Claude Code 的 `settings.json` 中配置：

```json theme={"system"}
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.aiohub.org",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的API令牌",
    "ANTHROPIC_MODEL": "claude-sonnet-4-20250514"
  }
}
```

用户级配置位于 `~/.claude/settings.json`。项目私有配置可放在 `.claude/settings.local.json`，不要提交真实 API 令牌。

### 可选：1 小时 prompt caching

Claude API 的 prompt caching 默认 TTL 是 5 分钟。如果你经常在 Claude Code 中恢复长会话、处理大仓库上下文，或在 5 分钟后仍会复用同一段长前缀，可以在 `~/.claude/settings.json` 的 `env` 中加入 `ENABLE_PROMPT_CACHING_1H`，请求使用 1 小时 TTL：

```json theme={"system"}
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.aiohub.org",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的API令牌",
    "ANTHROPIC_MODEL": "claude-sonnet-4-20250514",
    "ENABLE_PROMPT_CACHING_1H": "1"
  }
}
```

<Note>1 小时 TTL 适合会反复复用长上下文的会话。Anthropic 的计费规则中，1 小时 cache write 按基础输入 token 价格的 2 倍计费，cache read 按较低价格计费；如果你总是在 5 分钟内继续会话，默认缓存通常已经够用。</Note>

### 可选：关闭 attribution header

Claude Code 默认会在系统提示词开头插入一段动态的 attribution header（包含客户端版本、prompt 指纹等），每次请求都会变化。通过网关转发时，这段变化的前缀会导致网关侧 KV cache 失效，拖慢推理速度。

在 `~/.claude/settings.json` 的 `env` 中设置 `CLAUDE_CODE_ATTRIBUTION_HEADER` 为 `"0"` 可以省略这段动态内容，提升 prompt cache 命中率：

```json theme={"system"}
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.aiohub.org",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的API令牌",
    "ANTHROPIC_MODEL": "claude-sonnet-4-20250514",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0"
  }
}
```

<Note>此设置仅影响网关/代理侧的缓存行为，Anthropic 官方 API 的 prompt caching 不受影响。如果你直连 Anthropic API 而非通过网关，无需设置此项。</Note>

## 验证配置

启动 Claude Code 后，发送一条消息。如果正常回复，说明配置成功。

先确认 Claude Code 命令可用：

```bash theme={"system"}
claude --version
```

也可以检查环境变量是否正确设置：

<Tabs>
  <Tab title="macOS / Linux">
    ```bash theme={"system"}
    test "$ANTHROPIC_BASE_URL" = "https://api.aiohub.org" && echo "base url ok"
    test -n "$ANTHROPIC_AUTH_TOKEN" && echo "api key configured"
    test -n "$ANTHROPIC_MODEL" && echo "model configured"
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    ```powershell theme={"system"}
    if ($Env:ANTHROPIC_BASE_URL -eq "https://api.aiohub.org") { "base url ok" }
    if ($Env:ANTHROPIC_AUTH_TOKEN) { "api key configured" }
    if ($Env:ANTHROPIC_MODEL) { "model configured" }
    ```
  </Tab>
</Tabs>

### 常用调试命令

在 Claude Code 会话内可以用这些命令定位客户端状态：

| 命令         | 用途             |
| ---------- | -------------- |
| `/status`  | 查看当前会话状态       |
| `/context` | 查看上下文 Token 用量 |
| `/clear`   | 清空当前会话后重新开始    |
| `/model`   | 查看或切换模型        |

## 协议说明

Claude Code 会向网关发送 Anthropic Messages 请求，常见路径是 `POST /v1/messages`。因此 Base URL 必须是 `https://api.aiohub.org`，而不是 `https://api.aiohub.org/v1`。如果你用 `curl` 手动验证，需要自己写完整路径和 Anthropic 版本头：

```bash theme={"system"}
curl https://api.aiohub.org/v1/messages \
  -H "Authorization: Bearer sk-你的API令牌" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 128,
    "messages": [{"role": "user", "content": "Hello from AIOHub"}]
  }'
```

## 常见问题

<AccordionGroup>
  <Accordion title="启动时反复弹出登录界面">
    检查当前 shell 是否真的带上 `ANTHROPIC_AUTH_TOKEN`。如果同时设置了 `ANTHROPIC_API_KEY`，Claude Code 可能按 API key 模式处理；AIOHub 推荐使用 `ANTHROPIC_AUTH_TOKEN`。

    如果你把配置写入 `settings.json`，可以加上 `apiKeyHelper`：

    ```json theme={"system"}
    {
      "apiKeyHelper": "echo 'sk-你的API令牌'",
      "env": {
        "ANTHROPIC_BASE_URL": "https://api.aiohub.org",
        "ANTHROPIC_AUTH_TOKEN": "sk-你的API令牌",
        "ANTHROPIC_MODEL": "claude-sonnet-4-20250514"
      }
    }
    ```
  </Accordion>

  <Accordion title="404 或 API Connect Error">
    确认 `ANTHROPIC_BASE_URL` 没有 `/v1`。如果填成 `https://api.aiohub.org/v1`，Claude Code 可能请求到 `/v1/v1/messages`。
  </Accordion>

  <Accordion title="400 错误">
    使用 `/clear` 清空会话后重试，并确认所选模型存在于你的 API 令牌的分组中。若错误与 Claude Code 实验特性有关，可以在启动环境中加入 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` 后重试。
  </Accordion>

  <Accordion title="上下文过大或会话变慢">
    使用 `/context` 查看上下文分布。必要时新建会话、清空会话，或减少自动压缩前的长历史内容。
  </Accordion>

  <Accordion title="余额不足错误">
    前往 [钱包管理](https://api.aiohub.org/console/topup) 查看余额并充值。
  </Accordion>
</AccordionGroup>

## 官方参考

* [Claude Code environment variables](https://code.claude.com/docs/en/env-vars)
* [Claude Code settings](https://code.claude.com/docs/en/settings)
* [Anthropic prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#ttl-support)