让 Claude Code 只用聚合站跑单个项目：项目级最小配置怎么落地

为什么要做项目级配置

把 Claude Code 指向聚合站，最常见的做法是在 shell 里 export ANTHROPICBASEURL 和 ANTHROPICAUTHTOKEN。这能跑起来，但会污染全局：同一台机器上其他项目、其他终端都会跟着走聚合站，想切回官方认证时又得手动 unset 或改 profile，来回折腾。

更稳的做法是把配置收敛到单个项目目录。项目内有效，离开目录即失效，全局登录态（官方账号授权）保持原样。

先搞清楚 Claude Code 读哪些配置

Claude Code 的配置大致分三层，优先级从低到高：

• 用户级：~/.claude/settings.json，对当前用户所有项目生效。
• 项目级：项目根目录下的 .claude/settings.json（可提交、团队共享）和 .claude/settings.local.json（本地私有、通常加进 .gitignore）。
• 进程环境变量：启动 claude 进程时所在 shell 的环境变量，覆盖面最广。

关键在于：环境变量的优先级通常高于 settings 文件，所以只在项目里写 settings 还不够，要确保 shell 里没有残留的全局变量在抢。

落地步骤

1. 清理全局残留

先确认 shell 配置（~/.zshrc、~/.bashrc、~/.profile 等）里没有长期存在的 ANTHROPICBASEURL、ANTHROPICAUTHTOKEN、ANTHROPICAPIKEY。有就删掉或注释掉，重新开一个终端。这是整套方案能成立的前提——否则项目级配置会被全局变量压制。

2. 在项目里写 settings.local.json

在项目根目录创建 .claude/settings.local.json，把聚合站的接入参数放进去。Claude Code 通过环境变量字段读取 Anthropic 兼容端点的地址和密钥，聚合站提供的是 Anthropic 兼容的 base URL 和一枚 API key：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://你的聚合站域名/api",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的聚合站key"
  }
}

具体的 base URL 路径以聚合站文档为准，不同实现的挂载点可能不同，写错会直接连不上。

3. 把本地文件排除出版本库

.claude/settings.local.json 含密钥，务必加入 .gitignore。如果团队要共享非敏感配置（比如只共享模型名映射），把不含密钥的部分放进 .claude/settings.json，密钥只留在 local 文件里。

4. 从项目目录启动

只有从项目根目录（或其子目录）启动 claude，项目级 settings 才会被加载。养成 cd 进项目再启动的习惯，比记一堆环境变量可靠。

切回官方认证为什么不用改环境变量

因为官方登录态从来没有被改动过。Claude Code 的账号授权信息存在用户级配置里，项目级 settings 只是给这个项目注入了另一套端点与凭证。换到别的项目目录启动，读到的仍是原来的用户级配置，走官方认证；回到这个目录，读到项目级覆盖，走聚合站。

这就是“不动全局登录态”的实际含义：两套认证路径并存，靠工作目录区分，而不是靠手动切换环境。

几个容易踩的坑

• 子目录启动不一定生效：尽量从项目根目录启动，避免因目录层级判断导致的配置未加载。
• 密钥进了版本库：settings.local.json 忘加 .gitignore 是高频事故，提交前用 git status 检查一遍。
• 优先级记反：以为项目 settings 一定压过 shell 变量。实际上环境变量常常优先，先清干净全局再谈项目级。
• base URL 少写路径：聚合站的兼容端点通常带路径前缀，只填域名会 404。
• 把模型名写死在不该写的地方：如果聚合站对模型标识有约定，按文档填；模型清单与别名以官方说明为准，不要凭记忆猜。

和聚合站计费方式的关系

这套配置只是把请求指向聚合站，计费口径不变：用户按官方价 ×1.3 扣费；贡献 key 的一方按官方价 ×1.1（优质 key ×1.2）返 USDC。充值走 Base 上的 USDC，无需 KYC。一个 API key 可以调多个模型，所以项目级配置里通常只需要一枚 key 和一个 base URL，不必为每个模型单独配环境。

小结

核心就三点：清掉全局环境变量、把接入参数写进项目级 settings.local.json、从项目根目录启动。这样聚合站配置被限制在项目边界内，官方登录态不受影响，切换时不需要反复改环境变量。