---
title: "Claude Code"
description: "让 Claude Code 走 pirouter：ANTHROPIC_BASE_URL 设为 https://api.pirouter.ai（不带 /v1），ANTHROPIC_AUTH_TOKEN 设为 pirouter 的 key，模型写 claude-sonnet-5-5 这样的连字符别名。"
canonical: "https://pirouter.ai/zh/docs/integrations/claude-code"
last-updated: "2026-10-18"
lang: "zh"
source: "content/docs/zh/integrations/claude-code.mdx"
---

# Claude Code

让 Claude Code 走 pirouter：ANTHROPIC_BASE_URL 设为 https://api.pirouter.ai（不带 /v1），ANTHROPIC_AUTH_TOKEN 设为 pirouter 的 key，模型写 claude-sonnet-5-5 这样的连字符别名。

[Claude Code](https://code.claude.com/docs/en/overview) 不需要插件就能走 pirouter：设两个环境变量，`ANTHROPIC_BASE_URL` 指向 pirouter，`ANTHROPIC_AUTH_TOKEN` 填 pirouter 的 key，模型写 `claude-sonnet-5-5` 这样的连字符别名。Claude Code 只用 Anthropic 协议，请求发到 `POST /v1/messages`。

## 前提

- 一个 pirouter API key。还没有的话，按[快速开始](https://pirouter.ai/zh/docs/quickstart.md)创建一个，并存进环境变量：

```bash
export PIROUTER_API_KEY="sk-pi-..."
```

- Claude Code v2.1.293 及以上。Sonnet 5.5 要 v2.1.284 起，Opus 5.5 要 v2.1.280 起，Haiku 5.5 要 v2.1.293 起。本页在 v2.1.302 上验证。

* 还没安装的话，macOS、Linux、WSL 上运行：

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

Windows 用 `winget install Anthropic.ClaudeCode`，其他安装方式见 [Claude Code 安装说明](https://code.claude.com/docs/en/setup)。已经装了的，运行 `claude update` 升级。

## 配置

把下面这段写进 `~/.claude/settings.json`，`ANTHROPIC_AUTH_TOKEN` 换成你的 pirouter key。文件里已经有别的设置的话，把这几项并进已有的 `env` 块：

`~/.claude/settings.json`:

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.pirouter.ai",
    "ANTHROPIC_AUTH_TOKEN": "sk-pi-...",
    "ANTHROPIC_MODEL": "claude-sonnet-5-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-5-5"
  }
}
```

写在这个文件里，所有项目、包括后台 agent 都用这套配置。shell 里导出的同名变量和这里冲突时，以这个文件为准。key 不要写进项目里的 `.claude/settings.json`，那个文件会随仓库提交。

每一项的作用：

- `ANTHROPIC_BASE_URL` 填 `https://api.pirouter.ai`，不带 `/v1`，Claude Code 会自己拼上 `/v1/messages`。
- `ANTHROPIC_AUTH_TOKEN` 填 pirouter key，Claude Code 把它放在 `Authorization: Bearer` 请求头里发出，网关从这个头读 key。
- `ANTHROPIC_MODEL` 是主模型。
- `ANTHROPIC_DEFAULT_HAIKU_MODEL` 固定后台任务用的模型。Claude Code 会在后台发一些短请求，比如生成会话标题和摘要；走 pirouter 时它们默认用主模型，设了这一项就改用更便宜的 Haiku 5.5。

### 只在当前终端用

不想改配置文件，就在启动 Claude Code 的终端里导出同样的变量：

```bash
export ANTHROPIC_BASE_URL="https://api.pirouter.ai"
export ANTHROPIC_AUTH_TOKEN="$PIROUTER_API_KEY"
claude --model claude-sonnet-5-5
```

### 模型写连字符别名

模型写 `claude-sonnet-5-5`、`claude-opus-5-5`、`claude-haiku-5-5` 这样的连字符别名，不写 `anthropic/claude-sonnet-5.5` 这样的全 ID。日志和账单里记的仍是全 ID，比如 `anthropic/claude-sonnet-5.5`，见[别名](https://pirouter.ai/zh/docs/models.md#别名)。

原因在 Claude Code 这一侧：它按自己内置的 Anthropic 模型 ID 识别模型，ID 里包含哪个内置 ID，就当成哪个模型，再据此决定上下文窗口和能力。连字符别名和内置 ID 写法一致，能被正确识别，Sonnet 5.5 按 1M 上下文运行。点号写法的全 ID 会被认错：`anthropic/claude-opus-5.5` 里包含的是 `claude-opus-5`，Claude Code 把它当成 Opus 5。请求照样能成功，但 Claude Code 按 Opus 5 的设定来跑。

### 能用哪些模型

Claude Code 只用 Anthropic 协议，Anthropic 官方也只支持它调用 Claude 模型。网关不做协议转换，所以用 Claude 系列，见[模型与协议](https://pirouter.ai/zh/docs/models.md#每个模型接受哪些协议)的协议表里 Anthropic 一列。

## 验证

在一个空目录里运行：

```bash
claude -p "Reply with the single word: ok"
```

你应该看到终端打印 `ok`。让它读一个文件、调用一次工具，同样能完成，提示缓存也会生效。

在控制台的[日志](https://pirouter.ai/zh/docs/guides/logs.md)里能看到这次请求，**端点** 一栏是 `/v1/messages`，模型是全 ID。

交互模式下运行 `/status`，能看到当前使用的 base URL 和凭证来源。

## 排障

### 401 invalid\_api\_key

多半是只设了 `ANTHROPIC_BASE_URL`，没设 `ANTHROPIC_AUTH_TOKEN`。这时 Claude Code 仍用你登录的 Claude 订阅凭证，把它发给 pirouter；网关先读 `Authorization`，那里的值不是 pirouter key，请求直接返回 `401`。

把 `ANTHROPIC_AUTH_TOKEN` 设成 pirouter key，运行 `/status` 确认凭证来源是它。其他鉴权失败见[鉴权与 API key](https://pirouter.ai/zh/docs/authentication.md#鉴权失败时的返回)。

### 400，提到 context\_management 或 Extra inputs are not permitted

Claude Code 默认会带上一些实验性的 beta 功能和配套的请求字段。上游不接受时返回 `400`，`message` 里常见 `context_management`、`output_config` 或 `Extra inputs are not permitted`。在启动 Claude Code 的环境里设下面这个变量，Claude Code 就不再发这些实验性功能：

```bash
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
```

也可以把 `"CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"` 加进 `~/.claude/settings.json` 的 `env` 块。

### 启动时提示模型不被识别

启动时出现 `Model "..." isn't recognized · context assumed to be 200k tokens`：Claude Code 认不出你写的模型 ID，按 200K 上下文运行，提前压缩对话。把模型改成连字符别名，比如 `claude-sonnet-5-5`。别名已经写对还出现这个提示，多半是 Claude Code 版本比模型旧，运行 `claude update`。

### 422 validation\_failed

返回 `422`，错误码 `validation_failed`，`message` 以 "This model is not served on the endpoint you called." 开头：这个模型不接受 Anthropic 协议，例如 `openai/gpt-6.1-sol`。换一个 Claude 模型。要用 OpenAI 的模型写代码，可以用 [Codex](https://pirouter.ai/zh/docs/integrations/codex.md)。

## 目前没有验证的用法

- 别家接受 Anthropic 协议的模型（协议表里 Anthropic 一列为「支持」的非 Claude 模型）配 Claude Code 能不能正常工作，没有验证过；Anthropic 官方不支持这种用法。
- 长时间的思考任务、多个子 agent 并行、MCP 工具较多的会话，没有专门验证过。
- `/context` 显示的 token 数是估算值：网关没有提供 `POST /v1/messages/count_tokens`，Claude Code 改用按字符估算，不报错。

## 相关链接

- [Claude Code](https://github.com/anthropics/claude-code)（GitHub）
- [Claude Code 安装说明](https://code.claude.com/docs/en/setup)
- [连接 LLM 网关](https://code.claude.com/docs/en/llm-gateway-connect)：Claude Code 官方的网关配置说明
- [模型配置](https://code.claude.com/docs/en/model-config)：模型别名、上下文窗口与相关环境变量