Claude Code 经网关接入

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

你将完成什么

一个 anthropic 上游 + claude-sonnet 模型（或跨协议上游）
一把网关访问密钥
Claude Code 经网关调用成功，看到回复

前置

网关已运行（http://localhost:7890），能登录控制台
一个 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`	对外暴露给客户端的模型名
上游	`anthropic`	选刚建的上游
上游模型 ID	`claude-sonnet-4-...`	Anthropic 真实模型名
启用	✓

保存。

3. 配密钥组放行

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

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

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：

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（上游 openai，上游模型 ID gpt-4o）——客户端的 Anthropic 请求会被网关自动翻译成 OpenAI 上游协议，无需模型层协议覆盖。

客户端协议与上游协议不同的组合，需要协议互通矩阵支持的方向。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 报 403 model_access_denied？ 密钥所在的密钥组「模型」列表没包含 claude-sonnet。回到密钥组把该模型加进去，或改成 *。

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 ​

跨协议上游 ​

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

常见问题 ​