> 原始 Markdown 孪生体（构建期从源 Markdown 生成）。渲染页：https://docs.gatellm.io/zh-CN/quickstart/claude-code-via-gateway · 文档索引：https://docs.gatellm.io/zh-CN/llms.txt


# Claude Code 经网关接入

Claude Code 是 Anthropic 官方的命令行 AI 编码助手。它默认调用 `https://api.anthropic.com`，但通过环境变量 `ANTHROPIC_BASE_URL` 把 base URL 指向网关，就能让所有请求经网关走——既可以用 Anthropic 上游（同协议直发），也可以跨协议用 OpenAI / Gemini / Bedrock 等上游（网关翻译）。

## 你将完成什么

- 一个 `anthropic` 上游 + 与 Claude Code 默认模型 ID 对齐的模型（本教程用 `claude-sonnet-4-5`，跨协议则用 `gpt-4o` 等）
- 一把网关访问密钥
- Claude Code 经网关调用成功，看到回复

## 前置

- 网关已运行（`http://localhost:7890`），能登录控制台
- 已设 `ENCRYPTION_KEY`——下面要保存的上游 API key 与访问密钥都落库前加密，没设会在保存时报 `encryption_key not set in config`。见 [Docker 单机跑通 → 前置](/zh-CN/quickstart/docker-single-node.md#prereq)
- 一个 Anthropic API key（或上游是 OpenAI / Gemini / Bedrock 等，用对应凭证）
- 已装 Claude Code（`npm install -g @anthropic-ai/claude-code` 或类似方式）

## 1. 建 anthropic 上游

控制台 → **上游服务** → **新建**：

| 字段 | 值 | 说明 |
|------|-----|------|
| 名称 | `anthropic` | 上游唯一标识 |
| 协议 | `anthropic` | 决定执行器与请求 schema |
| 基础 URL | `https://api.anthropic.com` | 上游真实地址，结尾不带 `/` |
| API Key | Anthropic 的 key | 点「添加」可加多把，按权重分布 |
| 启用 | ✓ | |

保存。

## 2. 建 claude 模型

在上游 `anthropic` 行点 **展开** → 模型子表 → **新建模型**：

| 字段 | 值 | 说明 |
|------|-----|------|
| 名称 | `claude-sonnet-4-5` | 对外暴露给客户端的模型名 |
| 上游 | `anthropic` | 选刚建的上游 |
| 上游模型 ID | `claude-sonnet-4-5` | Anthropic 真实模型名 |
| 启用 | ✓ | |

保存。

> **为什么模型名直接用 `claude-sonnet-4-5`？** Claude Code 发请求时带的是它**自己配置的默认模型 ID**（如 `claude-sonnet-4-5`），不是你随便起的网关名。若网关模型叫别的名字（如 `claude-sonnet`），Claude Code 的第一条消息就会 404 `model_not_found`。把网关模型**命名为 Claude Code 实际会请求的模型 ID** 是最省事的对齐方式——不这样做也行，见 [第 5 步](#configure-claude-code) 用 `ANTHROPIC_MODEL` 对齐。「上游模型 ID」须是 Anthropic 真实存在的模型名，可用清单见 [Anthropic 官方模型列表](https://docs.anthropic.com/en/docs/about-claude/models)。

## 3. 配密钥组放行

控制台 → **访问密钥** → **密钥组** 页签 → **新建**：

| 字段 | 值 | 说明 |
|------|-----|------|
| 名称 | `default` | 分组名 |
| 模型 | 选 `claude-sonnet-4-5`，或 `*`（全部） | 决定该组密钥能调哪些模型 |
| 启用 | ✓ | |

## 4. 签发访问密钥

控制台 → **访问密钥** → **新建**：

| 字段 | 值 | 说明 |
|------|-----|------|
| 名称 | `claude-code-key` | 密钥的标识，用于管理与审计 |
| API 密钥 | 点「生成」 | 自动生成一串，客户端调用时带的凭证 |
| 分组 | `default` | 决定这把密钥能访问哪些模型 |
| 启用 | ✓ | |

## 5. 配置 Claude Code {#configure-claude-code}

Claude Code 读以下环境变量：

```bash
export ANTHROPIC_BASE_URL=http://localhost:7890
export ANTHROPIC_API_KEY=<你的访问密钥>

# 注意：base_url 填到根（不带 /v1），因为 Claude Code 自己拼 /v1/messages
```

或写在 shell 配置里（`~/.zshrc` / `~/.bashrc`）持久化。

**对齐模型名（关键一步）**：Claude Code 发请求时带的是**它自己配置的默认模型 ID**，不是任意网关模型名。二者必须一致，否则第一条消息就 404 `model_not_found`。两种对齐方式，任选其一：

- **方式 A（推荐，零额外配置）**：网关模型直接命名为 Claude Code 会请求的模型 ID。本教程第 2 步即如此（`claude-sonnet-4-5`），无需再设任何变量。
- **方式 B**：网关模型用自定义名（如 `claude-sonnet`），则设 `ANTHROPIC_MODEL` 指向该网关名：

  ```bash
  export ANTHROPIC_MODEL=claude-sonnet  # 网关上的自定义模型名
  ```

  （也可在 Claude Code 内用 `/model` 命令切换，但不如环境变量省事。）

启动 Claude Code：

```bash
claude
```

发一条消息，看到模型回复即跑通。所有 Claude Code 的请求都经网关。

## 跨协议上游

如果上游是 OpenAI / Gemini / Bedrock，需要协议互译——Claude Code 走 Anthropic 协议（`/v1/messages`），网关翻译成上游协议发给上游，响应再翻译回 Anthropic 格式。

例如用 OpenAI 上游当 Claude Code 后端：

1. 建上游 `openai`（协议 `openai`，URL `https://api.openai.com/v1`）
2. 建模型 `claude-sonnet-4-5`（上游 `openai`，上游模型 ID `gpt-4o`）——客户端的 Anthropic 请求会被网关**自动翻译**成 OpenAI 上游协议，无需模型层协议覆盖。模型名仍建议与 Claude Code 默认模型 ID 对齐（同第 2 步），否则用 `ANTHROPIC_MODEL` 对齐。

> 客户端协议与上游协议不同的组合，需要 [协议互通矩阵](/zh-CN/reference/protocol-matrix.md) 支持的方向。Anthropic → OpenAI 经 chat 互译支持。

跨协议时注意：

- 工具调用：`tool_call_id` 在跨协议往返中必须保留原值
- 流式：网关把上游 SSE 流翻译成 Anthropic SSE 流；上游推理时间长时插入 `:keep-alive` 注释
- 流异常：上游流中途断时插入 `_gateway_warning` 扩展字段，告诉你中断原因

## 注入会话缓存键（可选） {#session-cache-key}

Claude Code 会在对话里注入 `x-claude-code-session-id` 头。可以用 `request_payload` 的表达式把头值注入到上游的私有缓存键字段，让同一会话的多次请求命中上游缓存：

```json
[
  {
    "path": "prompt_cache_key",
    "mode": "overwrite",
    "value": "{{header:x-claude-code-session-id|system_prompt_hash}}"
  }
]
```

逐级降级：有会话头→用头（同会话同键）；无头但 system 提示词存在→用 system 哈希；两者皆空→省略写入。完整变量清单见 [模板变量速查](/zh-CN/reference/template-variables.md)。

## 常见问题 {#faq}

**Q：Claude Code 报 `connection refused`？**
检查 `ANTHROPIC_BASE_URL` 是否指向正确的网关地址，网关是否在监听。Docker 部署的网关用 `http://host.docker.internal:7890` 或局域网 IP。

**Q：Claude Code 报 401？**
`ANTHROPIC_API_KEY` 没填对。检查填的是网关访问密钥（不是 Anthropic 的 `sk-...`）。

**Q：Claude Code 报 404 model_not_found？**
模型名没对齐。Claude Code 发的是它自己的默认模型 ID（如 `claude-sonnet-4-5`），网关上必须有**同名**模型。两种修法：① 把网关模型命名为 Claude Code 会请求的模型 ID；② 设 `ANTHROPIC_MODEL=<你的网关模型名>`。见 [第 5 步](#configure-claude-code)。

**Q：Claude Code 报 403 model_access_denied？**
密钥所在的密钥组「模型」列表没包含 `claude-sonnet-4-5`。回到密钥组把该模型加进去，或改成 `*`。

**Q：Claude Code 报 400 unsupported_feature？**
跨协议组合没有翻译器。检查 [协议互通矩阵](/zh-CN/reference/protocol-matrix.md) 支持的方向。

**Q：跨协议调用时工具调用丢了？**
`tool_call_id` 在跨协议往返中必须保留原值——检查多轮工具对话里回传的 `tool_call_id` 是否和网关给你的完全一致。

**Q：plan 模式切换模型怎么配？**
见 [用脚本按 Claude Code plan 模式切换模型](/zh-CN/howto/script-switch-model-by-plan-mode.md)。Claude Code 的 plan 模式会在对话里注入 `Plan mode is active` / `Exited Plan Mode` 标记，可用脚本比较末次位置切换路由。

**下一步**：[端点 · 认证 · 协议互通](/zh-CN/reference/endpoints.md) 看完整端点清单；[客户端接入与网关差异](/zh-CN/reference/clients-and-gateway-diffs.md) 看各 SDK 接法和网关特有行为；[协议互通矩阵](/zh-CN/reference/protocol-matrix.md) 看所有协议对支持情况。