# Claude Code

> 在 Claude Code 中使用平台的模型：安装、settings.json 配置、模型映射、上下文窗口与常见报错的处理。

来源：https://www.scirouter.cn/docs/claude-code · 更新于 2026-10-24

Claude Code 通过 Anthropic Messages 格式（`POST /v1/messages`）调用平台的模型，平台上的对话模型均可使用。配置前先完成[编程工具概览](https://www.scirouter.cn/docs/coding-tools)「准备」中的三步。

## 安装

```bash
npm install -g @anthropic-ai/claude-code
claude --version
```

输出版本号表示安装成功。Windows 需先安装 WSL 或 Git for Windows。

## 配置

Claude Code 从 `settings.json` 的 `env` 字段读取环境变量，写在这里对所有终端生效：

| 系统 | 文件路径 |
|---|---|
| macOS / Linux | `~/.claude/settings.json` |
| Windows | `C:\Users\<用户名>\.claude\settings.json` |

文件不存在时新建。写入以下内容，将 `YOUR_API_KEY` 换成 SciRouter 的 Key、`YOUR_MODEL_ID` 换成平台的模型 id：

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.scirouter.cn",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
    "ANTHROPIC_MODEL": "YOUR_MODEL_ID",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "YOUR_MODEL_ID"
  }
}
```

文件中已有其他设置时，只合并 `env` 中的这几项。**`ANTHROPIC_BASE_URL` 不带 `/v1`**：Claude Code 在其后拼接 `/v1/messages`。

也可只在当前终端设置，不写入文件：

```bash
export ANTHROPIC_BASE_URL="https://api.scirouter.cn"
export ANTHROPIC_AUTH_TOKEN="$SCIROUTER_API_KEY"
export ANTHROPIC_MODEL="YOUR_MODEL_ID"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="YOUR_MODEL_ID"
claude
```

### 环境变量

| 环境变量 | 取值 | 说明 |
|---|---|---|
| `ANTHROPIC_BASE_URL` | `https://api.scirouter.cn` | 不带 `/v1` |
| `ANTHROPIC_AUTH_TOKEN` 或 `ANTHROPIC_API_KEY` | SciRouter 的 API Key | 设置其一。前者以 `Authorization: Bearer` 发送，后者以 `x-api-key` 发送 |
| `ANTHROPIC_MODEL` | 平台的模型 id | 启动时使用的模型 |
| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | 平台的模型 id | `haiku` 别名对应的模型；Claude Code 执行后台小任务时也使用它 |
| `ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL` | 平台的模型 id | `sonnet`、`opus` 别名对应的模型，见[多个模型](#多个模型) |
| `CLAUDE_CODE_SUBAGENT_MODEL` | 平台的模型 id | 子代理未另行指定模型时使用的模型，见[多个模型](#多个模型) |
| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 所选模型的输出上限 | 见[输出上限](#输出上限) |
| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | 所选模型的上下文窗口 | 见[上下文窗口](#上下文窗口) |
| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | `1` | 见[模型发现](#模型发现) |
| `CLAUDE_CODE_ATTRIBUTION_HEADER` | `0` | 不发送归因块，见[归因块](#归因块) |
| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | `1` | 见[上游为其他厂商的兼容接口](#上游为其他厂商的兼容接口) |

`ANTHROPIC_AUTH_TOKEN` 与 `ANTHROPIC_API_KEY` 的变量名由 Claude Code 定义，取值为 SciRouter 控制台创建的 API Key（以 `sk-sr-` 开头），不能使用 Anthropic 官方的 Key。两者都设置且不是同一个 Key 时，请求返回 401；其中一个为空串时（发出空的 `Authorization: Bearer`）按未携带处理。shell 中已设置 `ANTHROPIC_API_KEY` 为官方 Key 的，删除该变量或改为 SciRouter 的 Key。

## 启动

```bash
cd my-project
claude
```

首次进入目录时选择信任该目录。发送一条消息，收到回答即接入成功；该请求出现在控制台[调用日志](https://www.scirouter.cn/console/logs)中，调用格式为 Anthropic。

首次启动仍出现登录引导时，在 `~/.claude.json`（Windows 为 `C:\Users\<用户名>\.claude.json`）中加入以下一项后重新启动。文件已存在时只加这一项，不覆盖其他内容：

```json
{
  "hasCompletedOnboarding": true
}
```

## 多个模型

`haiku`、`sonnet`、`opus` 三个别名可分别映射到平台的不同模型，在会话中输入 `/model` 切换：

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.scirouter.cn",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
    "ANTHROPIC_MODEL": "YOUR_MODEL_ID",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "YOUR_MODEL_ID",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "YOUR_MODEL_ID",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "YOUR_MODEL_ID",
    "CLAUDE_CODE_SUBAGENT_MODEL": "YOUR_MODEL_ID"
  }
}
```

- `haiku` 用于后台小任务（生成标题、摘要等），宜映射到响应快、单价低的模型。
- Claude Code 在检索代码、规划任务时会启动内置的子代理（如 Explore、Plan）。子代理所用的模型没有映射到平台的模型 id 时，请求可能返回 404 `model_not_found`；设置 `CLAUDE_CODE_SUBAGENT_MODEL` 后，未另行指定模型的子代理改用它。
- 切换到未映射的别名时，Claude Code 请求 Anthropic 的模型名；平台没有为该名称配置别名时返回 404 `model_not_found`。

## VS Code 与 JetBrains

Claude Code 的 IDE 插件使用同一份 `settings.json`，完成上文配置后在 IDE 的插件市场搜索 Claude Code 安装即可。

## 输出上限

Claude Code 不识别平台的模型 id 时，默认每次请求 32000 个输出 token。超过模型或套餐的单次上限时，平台按上限发出，不返回错误，处理方式见 [Messages（Anthropic 格式）](https://www.scirouter.cn/docs/messages)「max_tokens」。回答达到上限时 `stop_reason` 为 `max_tokens`，与厂商截断时相同。

将 `CLAUDE_CODE_MAX_OUTPUT_TOKENS` 设为模型的输出上限后，Claude Code 按真实上限规划。上限见[模型中心](https://www.scirouter.cn/models)的详情页。

## 上下文窗口

Claude Code 对不识别的模型 id 一律按 20 万 token 计算压缩对话的时机。所选模型的窗口更小时，用 `CLAUDE_CODE_MAX_CONTEXT_TOKENS` 写明真实窗口（见[模型中心](https://www.scirouter.cn/models)的详情页），Claude Code 才会按时压缩。

未设置时由平台兜底：输入、或输入加 `max_tokens` 放不进窗口的请求，平台在发出前返回 400 `context_window_exceeded`，Claude Code 根据 `message` 处理后重发。

| 情况 | `message` 包含 | Claude Code 的处理 |
|---|---|---|
| 输入超过窗口 | `prompt is too long: N tokens > M maximum` | 按两个数字压缩历史后重发 |
| 输入未超过窗口，加上 `max_tokens` 后超过 | ``input length and `max_tokens` exceed context limit`` | 调小 `max_tokens` 后重发 |

兜底方式每次多一个往返，建议设置 `CLAUDE_CODE_MAX_CONTEXT_TOKENS`。

## 模型发现

设置 `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` 后，Claude Code 启动时读取一次平台的模型列表并放入 `/model`，只保留 id 中含 `claude` 或 `anthropic` 的模型。其他模型通过 `ANTHROPIC_MODEL` 与别名映射直接填写平台的模型 id。

## 归因块

Claude Code 在 `system` 开头带一块归因信息（客户端版本与提示指纹）。使用非 Anthropic 的模型时，可设置 `CLAUDE_CODE_ATTRIBUTION_HEADER=0` 不发送。未设置时，平台走其他入口转换时去掉该块，响应头 `X-SciRouter-Param-Actions` 中记 `reshaped=…`。

## 厂商服务端工具

WebSearch 是厂商的服务端工具，平台不支持，请求返回 400，`details.reason` 为 `server_tool_unsupported`。Claude Code 自身的 WebSearch / WebFetch 不受影响。

## 上游为其他厂商的兼容接口

Claude Code 发送 Claude 官方接口支持的全部字段：`thinking` 的 `adaptive`、对话中途的 `system` 消息、`context_management`、`output_config`。线路背后是其他厂商的 Anthropic 兼容接口时，请求原样转发，厂商不支持这些字段时返回 400：

- 前几项由 Claude Code 自行去掉后重试。
- `context_management` 等提示类参数：厂商的报错中能识别出参数名时，平台去掉该参数，在同一条线路重发一次，`X-SciRouter-Param-Actions` 中记 `healed=context_management`；识别不出时仍返回 400。
- 400 `context_management: Extra inputs are not permitted` 一类报错反复出现时，设置 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`。

转换方式（线路没有 Anthropic 入口）不受影响：`context_management` 中的 `clear_tool_uses_*` 由平台补实现，其余编辑去掉并留痕。

平台拒绝请求时的两种标记（`capability_rejected`、`policy_blocked`）及 Claude Code 的处理见 [Messages（Anthropic 格式）](https://www.scirouter.cn/docs/messages)「错误」。