# Claude Code

URL: https://docs.router.ezat.io/zh/tools/claude-code

> 设置 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 两个环境变量，就能用 EZAT Router 余额运行 Claude Code。

## 何时阅读本页

你在用 Claude Code，希望它的请求通过 EZAT Router 发送，并从你的 EZAT 余额中扣费。设置两个环境变量即可。Claude Code 自带的模型名称照常可用，其他都不用改。

## 准备工作

- 一个 EZAT API key（`ezat_sk_…`）。在控制台的 [API Key](https://router.ezat.io/zh/keys) 页面创建；说明见 [API key](https://docs.router.ezat.io/zh/api-keys.md)。
- 余额中有额度（[计费](https://docs.router.ezat.io/zh/billing.md)）。
- 照常安装好的 Claude Code。

## 设置

<Steps>
<Step>

### 设置 base URL 和你的 key

在你将要启动 Claude Code 的终端中（你的 key 已在 `EZAT_API_KEY` 中）：

```bash tab="macOS and Linux"
export ANTHROPIC_BASE_URL="https://api.router.ezat.io"
export ANTHROPIC_AUTH_TOKEN="$EZAT_API_KEY"
```

```powershell tab="Windows PowerShell"
$env:ANTHROPIC_BASE_URL = "https://api.router.ezat.io"
$env:ANTHROPIC_AUTH_TOKEN = $env:EZAT_API_KEY
```

Base URL 不带 `/v1`：Claude Code 会自己加上。

</Step>
<Step>

### 启动 Claude Code

在同一个终端中运行 `claude`，让它继承这些变量。

</Step>
<Step>

### 检查

在 Claude Code 中运行 `/status`。在 Status 标签页上：

- `Anthropic base URL` 显示 `https://api.router.ezat.io`；
- `Auth token` 显示 `ANTHROPIC_AUTH_TOKEN`。

然后随便发送一个提示词。能正常得到回答就说明配置成功，几秒钟内该请求就会出现在控制台的「用量」页面上。

</Step>
</Steps>

如果想不通过 Claude Code 测试 key 和 URL，可以用 Claude Code 使用的同一个请求头发送一个请求：

```bash tab="curl" test
curl --fail-with-body https://api.router.ezat.io/v1/messages \
  -H "Authorization: Bearer $EZAT_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "anthropic/claude-sonnet-5-5", "max_tokens": 16, "messages": [{"role": "user", "content": "Hi"}]}'
```

返回带有 `"type": "message"` 的 JSON，说明 key 和 URL 都正确。返回 `401` 说明 key 不对。

## 永久生效

Shell 中的 export 只在当前终端有效。要保留设置，可以把两行 `export` 加到你的 shell 配置文件（`~/.zshrc`、`~/.bashrc` 或 PowerShell 的 `$PROFILE`）中，或者放进 Claude Code 设置文件的 `env` 块：

```json title="~/.claude/settings.json"
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.router.ezat.io",
    "ANTHROPIC_AUTH_TOKEN": "ezat_sk_…"
  }
}
```

如果文件已经存在，把 `env` 中的条目加进去，不要替换整个文件。当一个变量同时在 shell 和设置文件中设置时，以设置文件为准。设置文件也会作用于 Claude Code 的后台 agent，而 shell export 不一定能。

| 文件 | 作用范围 | 能否放 key？ |
| --- | --- | --- |
| `~/.claude/settings.json` | 你自己，所有项目 | 可以 |
| 项目中的 `.claude/settings.local.json` | 你自己，仅该项目 | 可以，前提是该文件不纳入版本控制 |
| 项目中的 `.claude/settings.json` | 所有克隆该项目的人 | **不可以**。它会被提交并共享。这里只放 `ANTHROPIC_BASE_URL`。 |

Claude Code 只有在你信任该文件夹之后才会应用项目的 `env` 块。如果首次启动时它要求你登录，请改为把 key 放在 shell 中或 `~/.claude/settings.json` 里。

## 为什么用 ANTHROPIC_AUTH_TOKEN

两种方式 EZAT 都接受，但 `ANTHROPIC_AUTH_TOKEN` 更简单：

| 变量 | 发送方式 | 在 Claude Code 中的行为 |
| --- | --- | --- |
| `ANTHROPIC_AUTH_TOKEN` | `Authorization: Bearer <key>` | 立即取代已保存的 claude.ai 登录或 Console key。 |
| `ANTHROPIC_API_KEY` | `x-api-key: <key>` | 在交互式会话中先询问一次，确认后才生效。之前拒绝过的 key 会被直接忽略，不再询问。 |

设置了 token 时，Claude Code 不会使用你的 claude.ai 订阅：请求从你的 EZAT 余额扣费，订阅的限额也不适用。你的登录信息仍然保存着；取消设置该变量即可切回。只设置 `ANTHROPIC_BASE_URL` 是不够的，因为那样 Claude Code 会发送你的 claude.ai 凭据，而 EZAT 会拒绝它。

## 选择模型

你不需要设置模型。Claude Code 的别名（`opus`、`sonnet`、`haiku`、`fable`）会解析为 Anthropic 的模型名称，例如 `claude-opus-5-5`，而 EZAT 把这些名称当作自己 id 的别名接受。后台任务使用 `haiku` 别名指向的模型。

- **切换当前会话的模型**：`/model`（打开选择器），或 `/model opus`。
- **以指定模型启动**：`claude --model sonnet`，或设置 `ANTHROPIC_MODEL`。
- **固定一个确切版本**：使用 Anthropic 的完整名称，例如 `claude-opus-5-5`，配合 `/model`、`ANTHROPIC_MODEL` 或 `model` 设置使用。

| 变量 | 设置什么 |
| --- | --- |
| `ANTHROPIC_MODEL` | 设置了该变量时启动的会话所用的模型 |
| `ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_HAIKU_MODEL`、`ANTHROPIC_DEFAULT_FABLE_MODEL` | `opus`、`sonnet`、`haiku` 和 `fable` 别名解析到的模型。Haiku 这一个同时决定后台任务使用的模型。 |
| `CLAUDE_CODE_SUBAGENT_MODEL` | subagent 的默认模型 |

请使用 Anthropic 的名称（[模型](https://docs.router.ezat.io/zh/models.md)页面的别名一列），而不是 EZAT 的 `anthropic/…` id。Claude Code 根据模型名称设置上下文窗口和功能，所以需要一个它认识的名称。

## 提示缓存

Claude Code 会自己标记提示缓存（prompt caching）的断点，EZAT 会把每个对话保持在同一个部署上，让缓存能被读回。无需任何设置。缓存 token 显示在「用量」页面的「缓存（写入 / 读取）」下。见[提示缓存与会话](https://docs.router.ezat.io/zh/guides/prompt-caching.md)。

## 查看用量和费用

每个请求都会出现在控制台的「用量」页面上，并按模型和按 key 显示 token 和费用。给 Claude Code 单独分配一个 key，就能单独查看它的用量（「按 key」）；如果需要封顶，还可以给这个 key 设置消费上限（[API key](https://docs.router.ezat.io/zh/api-keys.md)）。

## 运行 Claude Code 的其他方式

**VS Code 扩展**。在 VS Code 的用户设置（Preferences: Open User Settings (JSON)）中设置这些变量。扩展在启动前会先从这项设置中检查凭据：

```json
{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://api.router.ezat.io" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "ezat_sk_…" }
  ]
}
```

**GitHub Actions**。把 key 存为仓库 secret，并作为 action 的 `anthropic_api_key` 输入传入。action 会以 `x-api-key` 发送它，EZAT 接受这种方式：

```yaml
env:
  ANTHROPIC_BASE_URL: https://api.router.ezat.io

steps:
  - uses: anthropics/claude-code-action@v1
    with:
      anthropic_api_key: ${{ secrets.EZAT_API_KEY }}
```

**无法通过 EZAT 使用**：网页版 Claude Code（云端会话）和 Slack 中的 Claude Code 不会应用这些变量，所以无法在 EZAT 上运行。Remote Control 和语音听写需要 claude.ai 登录，设置了 `ANTHROPIC_AUTH_TOKEN` 时 Claude Code 会关闭这两项功能。

## 常见问题

| 现象 | 原因 | 解决办法 |
| --- | --- | --- |
| Claude Code 打开登录界面 | key 没有传到它那里：没有在当前终端 export，或只写在尚未被信任的项目文件中 | 在当前终端 export，或写入 `~/.claude/settings.json` |
| `/status` 中没有 `Anthropic base URL` 这一行 | `ANTHROPIC_BASE_URL` 没有传到会话中 | 从 export 过变量的终端启动 `claude`，或使用设置文件 |
| 启动时出现警告，提到两个凭据来源 | token 和已保存的 claude.ai 登录同时存在 | 运行 `/logout` 以继续使用 EZAT，或取消设置 token 以使用登录 |
| `401` `Invalid API key` | key 输错或已吊销，或者 `ANTHROPIC_API_KEY` 也设置成了另一个 key：请求同时带有两个请求头时，EZAT 使用 `x-api-key` | 在「API Key」页面检查 key；运行 `unset ANTHROPIC_API_KEY` |
| 设置中有 `apiKeyHelper` 时出现 `401` | helper 的输出会通过两个请求头发送，并取代你的 EZAT key | 删除 `apiKeyHelper`，或让它输出你的 EZAT key |
| 设置了 `ANTHROPIC_API_KEY` 却被忽略 | 它需要批准，或你之前拒绝过 | 在 `/config` 中启用（Use custom API key），或改用 `ANTHROPIC_AUTH_TOKEN` |
| `402` `billing_error` | 余额已用完，或 key 达到了消费上限 | 在「账单」页面「充值」，或提高该 key 的上限 |
| `404` 且带有 `model: …` | EZAT 不认识这个模型名称 | 使用[模型](https://docs.router.ezat.io/zh/models.md)中的名称；检查 `ANTHROPIC_MODEL` 和 `ANTHROPIC_DEFAULT_*_MODEL` 变量 |
| `403` `This API key is not allowed to use …` | 该 key 只能使用部分模型 | 在 key 上允许该模型。Claude Code 的后台任务还需要 `haiku` 背后的模型。 |
| `400` 提到 `Extra inputs are not permitted`，或 `anthropic-beta` 出现 `Unexpected value(s)` | Claude Code 发送的某个预发布功能不被模型提供方接受 | 设置 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` |
| `This machine's managed settings require a first-party login` | 你所在组织的托管设置强制使用某种登录方式 | 联系你的管理员；托管登录和自定义 key 不能同时使用 |

更多情况见[故障排查](https://docs.router.ezat.io/zh/troubleshooting.md)。

## 给 AI agent 的说明

1. 不要让用户把 key 粘贴到对话里。从 `EZAT_API_KEY` 读取，或让用户自己设置。
2. 把 `ANTHROPIC_BASE_URL` 设为 `https://api.router.ezat.io`（不带 `/v1`），`ANTHROPIC_AUTH_TOKEN` 设为该 key，写在 `~/.claude/settings.json` 的 `env` 块中（合并到现有文件，不要覆盖），或写在 shell 配置文件中。
3. 不要把 key 写进项目的 `.claude/settings.json`：它会被提交。
4. 不要同时设置 `ANTHROPIC_API_KEY` 或 `apiKeyHelper`。如果 `ANTHROPIC_API_KEY` 中是另一个 key，取消设置它。
5. 不要设置模型。如需固定模型，使用[模型](https://docs.router.ezat.io/zh/models.md)页面别名中的 Anthropic 模型名称，而不是 `anthropic/…` id。
6. 用上面的 curl 请求验证，然后让用户运行 `/status`，检查 `Anthropic base URL` 和 `Auth token`。