BYOK 加 Claude Code：自有 key 藏在聚合站后面，环境变量怎么只配一份

为什么会有「key 放在哪」这个问题

Claude Code 默认直连 Anthropic 官方端点，读的是环境变量里的 Anthropic key。当你通过一个 LLM API 聚合站来调用时，请求的出口变成了聚合站，鉴权凭证也换成了聚合站签发的 key。

如果这个聚合站本身又托管了你贡献的厂商 key（也就是 BYOK：Bring Your Own Key，把自有厂商 key 交给平台代管），那么你的机器上其实不需要再存一份厂商 key。你只需要一份聚合站凭证，剩下的路由和鉴权由服务端处理。

问题就出在：很多人会同时配两套变量，一套留给官方 SDK，一套留给聚合站，结果改 key 的时候不知道改哪一个，或者改了没生效。

两个变量，各管一段

Claude Code 走 Anthropic 兼容协议时，关键配置只有两个方向：

• 端点（base URL）：告诉客户端把请求发到哪里。指向聚合站的兼容入口，而不是官方域名。
• 鉴权（API key）：请求头里带的凭证。这里放的是聚合站签发的 key，不是厂商 key。

两者通常通过环境变量注入，常见命名是 ANTHROPICBASEURL 和 ANTHROPICAPIKEY（或聚合站文档里指定的等价变量名）。具体变量名和路径以聚合站文档为准，不要凭记忆写。

关键概念：客户端只知道聚合站，不知道你的厂商 key。厂商 key 存在聚合站侧，由它去和上游模型通信。

实操：只配一份

1. 确认聚合站的兼容端点

聚合站一般会提供一个 Anthropic 兼容的 base URL。它需要满足：路径结尾与 SDK 拼接规则一致（常见坑是多写或少写 /v1），并且支持 Anthropic 的请求格式。

如果聚合站同时支持 OpenAI 兼容协议，注意区分两个入口——Claude Code 用的是 Anthropic 那一个。

2. 注入环境变量

推荐把配置放在 shell 的启动文件或项目级的环境文件里，而不是每次手动 export。二选一的思路：

• 用户级（全局）：写在 ~/.zshrc、~/.bashrc 之类的位置，所有终端会话生效，适合只有一套凭证的个人使用。
• 项目级：用 .env 或目录级工具（如 direnv）管理，适合不同项目走不同聚合账号或不同模型池。

原则是同一个变量名只在一个地方定义。如果全局和项目级都写了，后加载的会覆盖前一个，出问题时很难排查。

3. 验证链路

配好后做一次最小验证：发起一次简单请求，确认返回正常。如果报鉴权错误，先确认 key 是不是聚合站的 key；如果报 404 或路径错误，先怀疑 base URL 的路径拼接。

换 key 时要改哪些地方

这是 BYOK 方案下最容易踩的坑。要分清两种情况：

情况 A：换的是聚合站的 key

聚合站 key 是你本地唯一持有的凭证。换它只需要改一处：

• 更新环境变量里的那个 key 值（全局或项目级，取决于你当初写在哪）。
• 重新加载 shell 配置，或重启终端 / 编辑器，让新值生效。
• 如果 key 写进了某个 IDE 插件或工具的独立配置文件，也要同步改，否则会出现「命令行能用、插件不能用」。

base URL 不用动，模型列表也不用动。

情况 B：换的是厂商 key（复用同一个聚合站 key）

厂商 key 存在聚合站侧，本地完全不感知。这时候：

• 本地环境变量什么都不用改。
• 到聚合站控制台更新或替换对应的厂商 key 即可。

这正是「key 藏在聚合站后面」的价值：换厂商 key 时，所有下游客户端零改动。

切换模型的改动点

如果只是想在 Claude、GPT、DeepSeek、Qwen、GLM、Kimi 之间切换：

• 端点通常不变（同一聚合入口）。
• 需要变的是模型标识符：命令行参数、会话内命令，或工具配置里的 model 字段。
• 具体可用的模型名以聚合站文档为准，不同上游的命名风格不统一，照抄容易写错。

排查清单

改动后如果行为不符合预期，按顺序检查：

1. 当前 shell 里这个变量的实际值是什么（直接打印出来看，别靠回忆）。
2. 有没有第二处定义在悄悄覆盖它。
3. base URL 的路径拼接是否与客户端预期一致。
4. 你改的是聚合站 key 还是厂商 key——两者的改动位置完全不同。
5. 编辑器 / IDE 是否使用了独立的环境，没继承终端变量。

小结

BYOK 加聚合站的核心是把凭证收拢到一处：本地只留聚合站 key 和聚合站端点，厂商 key 交给平台代管。只要坚持「一个变量名只定义一次」，换 key 时就能清楚知道该改哪一行，而不是在两套配置之间反复试探。