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 单机跑通 → 前置
一个 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 步用 ANTHROPIC_MODEL 对齐。「上游模型 ID」须是 Anthropic 真实存在的模型名，可用清单见 Anthropic 官方模型列表。

3. 配密钥组放行

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

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

4. 签发访问密钥

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

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

5. 配置 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 后端：

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

客户端协议与上游协议不同的组合，需要协议互通矩阵支持的方向。Anthropic → OpenAI 经 chat 互译支持。

跨协议时注意：

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

注入会话缓存键（可选）

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 哈希；两者皆空→省略写入。完整变量清单见模板变量速查。

常见问题

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 步。

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

Q：Claude Code 报 400 unsupported_feature？ 跨协议组合没有翻译器。检查协议互通矩阵支持的方向。

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

Q：plan 模式切换模型怎么配？ 见用脚本按 Claude Code plan 模式切换模型。Claude Code 的 plan 模式会在对话里注入 Plan mode is active / Exited Plan Mode 标记，可用脚本比较末次位置切换路由。

下一步：端点 · 认证 · 协议互通看完整端点清单；客户端接入与网关差异看各 SDK 接法和网关特有行为；协议互通矩阵看所有协议对支持情况。

Claude Code 经网关接入 ​

你将完成什么 ​

前置 ​

1. 建 anthropic 上游 ​

2. 建 claude 模型 ​

3. 配密钥组放行 ​

4. 签发访问密钥 ​

5. 配置 Claude Code ​

跨协议上游 ​

注入会话缓存键（可选） ​

常见问题 ​