Claude Code 为什么要接网关
Claude Code 可以直连 Anthropic，也可以放在企业网络、云厂商或 LLM Gateway 后面。Anthropic 官方企业部署文档把 LLM Gateway 定义为 Claude Code 和云提供商之间的一层，用来做集中鉴权、路由、用量追踪、团队限额和预算管理。
对国内开发者和小团队来说，网关价值主要是四件事：
- 不把上游原始 key 发到每台开发机。
- 每个项目使用独立子 key，方便停用和限额。
- 统一查看 token 用量、错误码和余额。
- 把 Claude Code、Agent 项目和 OpenAI-compatible SDK 接到同一个账单体系。
边界也要放前面：网关不承诺稳定，也不改变官方政策。它能做的是把鉴权、路由、账单、排障边界摆清楚。
接入前先对这 4 个变量
1. ANTHROPIC_BASE_URL
Anthropic 的 Claude Code 模型配置文档明确提醒：ANTHROPIC_BASE_URL 改变的是请求发往哪里，不改变哪个模型回答。也就是说，只改 base URL 不等于模型映射自动正确。
如果你把 base URL 指向 AIRelay 或其它网关，先确认这个网关暴露的是 Anthropic Messages 格式，还是 OpenAI-compatible 格式。Claude Code 直接走 Anthropic Messages 格式最省事；如果网关只提供 OpenAI-compatible，就需要一层协议转换。
2. ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY
Claude Code 鉴权文档说明，路由到自定义 API endpoint 时可以设置 ANTHROPIC_BASE_URL。网关使用 bearer token 时，用 ANTHROPIC_AUTH_TOKEN；没有 auth token 时，通常会用 ANTHROPIC_API_KEY 作为 x-api-key。
团队里尽量用网关发的项目子 key，不要把上游原始 Anthropic key 分发给每个人。
3. 模型发现
Claude Code 的 LLM gateway 文档说明：当 ANTHROPIC_BASE_URL 指向 Anthropic Messages 格式网关时，Claude Code 可以在启动时查询网关的 /v1/models，把返回模型加入 /model 选择器。这个能力需要设置 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1，并且默认关闭。
默认关闭有它的道理：共享 key 背后的所有模型，不应该自动暴露给所有用户。
4. 模型别名
模型名不只是展示文本，它决定网关怎么路由。常见错误有这几种：
- Claude Code 传入官方模型名，但网关只认识自定义别名。
- 网关返回了模型列表，但项目子 key 不允许其中某个模型。
ANTHROPIC_BASE_URL指向网关后，仍然以为官方模型名一定可用。
排障时把三列列出来：Claude Code 当前 model、网关支持 model、项目子 key 允许 model。三列一致，再往下查。
最小配置清单
不要在聊天记录、截图或仓库里贴真实 token。下面只写变量名：
| 项 | 要确认什么 |
|---|---|
| base URL | 指向网关域名和 API 路径 |
| auth token | 使用网关项目子 key，避免分发上游原始 key |
| model | Claude Code 选择器里看到的模型能被项目子 key 使用 |
| discovery | 是否需要启用模型发现 |
| logs | 控制台能看到时间、模型、input/output token、错误码 |
| budget | 项目是否设置日限额、月限额或单 key 限额 |
如果你接的是 AIRelay API Credit，先用一个低风险测试项目跑通，再接真实代码仓库。别第一步就把团队主项目的所有调用切过去。
5 个高频配置错误
错误 1：只改 base URL，没有改鉴权
官方 key 打到网关，或者网关 key 打到官方端点，都会 401。错误消息可能看起来像"key invalid"，实际要查的是 key 和端点是否匹配。
错误 2：模型名不在网关范围
Claude Code 里选了新模型，但网关还没上架，或者项目子 key 没开这个模型，常见结果是 model not found / permission error。
错误 3：团队共用一个 key
一个 key 放在所有成员电脑上，短期省事，长期无法限额、追责和停用。更稳的做法是每个项目或环境一个子 key。
错误 4：不知道请求 body 是否落盘
Claude Code 会把代码上下文发给模型。网关是否保存请求正文、调试日志是否默认开启、保留多久，都要先写清楚。AIRelay 的公开口径是默认只保留计量日志，不保存请求 body；需要调试时按授权处理。
错误 5：把 429 当成模型坏了
Claude Code 很容易在大仓库里一次性塞入大量上下文。429 可能是输入 token 突增、并发过高、项目预算触顶或网关限额。先看 token 和并发，再判断是否换模型。
接到 AIRelay 时
AIRelay 主要接这几类 Claude Code 场景：
- 国内团队要用人民币充值和项目子 key。
- 小团队想按项目拆账单和额度。
- 需要统一接入 Claude Code、OpenAI-compatible SDK 和 Agent 服务。
- 需要有人按 request_id / trace id 帮忙看错误码。
先看 API Credit 合规说明、API key vs API Credit 和 API 401 / 429 排障清单。已经有具体报错时，把脱敏字段发到 卡点自查 或 加入社群。