Claude Code 接第三方网关的配置要点
文章介绍如何用环境变量或设置文件将 Claude Code 接入兼容 Anthropic Messages API 的网关,并解释配置优先级和凭据管理。文中还讨论替换模型后的上下文压缩行为,以及如何验证和撤销配置。
AI 深度解读
Claude Code 可以通过 Anthropic Messages API 接入第三方模型网关。临时试跑只要设置地址和密钥,日常使用则要弄清谁决定实际的地址、密钥和模型,以及对话何时会被压缩。否则,即使能正常对话,也可能还在用旧凭据,或有部分请求仍按 Claude 模型计费。
原文作者运营 UberLLM,示例用的是自家网关。这套排查思路也适用于其他兼容端点,尤其适合遇到「直接请求 API 能通,Claude Code 却跑不起来」的时候。
先在一个终端验证地址和密钥
下面三行适合在 zsh 或 Bash 里做一次临时试跑,配置只在当前终端会话里生效。
export ANTHROPIC_BASE_URL=https://api.uberllm.dev
export ANTHROPIC_AUTH_TOKEN=ull_your_key
claude
第一行最容易填错。示例里的 Anthropic 风格 base URL 以域名结尾,OpenAI 风格的地址才带 /v1。后面直接请求 Messages API 时才写完整的 /v1/messages 路径。PowerShell 用 $env:ANTHROPIC_BASE_URL 和 $env:ANTHROPIC_AUTH_TOKEN 赋值,最后同样运行 claude。
长期使用时,可以把地址留在设置文件的 env 里,再用 apiKeyHelper 读取密钥。作者的做法是把 ~/.uberllm 目录权限设为 700,把 ~/.uberllm/key 文件权限设为 600,然后将 apiKeyHelper 设为 cat ~/.uberllm/key。Claude Code 会把脚本输出同时用于 Authorization: Bearer 和 x-api-key,默认缓存五分钟,可用 CLAUDE_CODE_API_KEY_HELPER_TTL_MS 调整。看到 Your apiKeyHelper script is failing 时,先检查文件是否存在、当前用户能否读取。
设置、密钥和模型各有一套优先级
按原文,设置从高到低依次是公司托管设置、claude --settings <file>、<project>/.claude/settings.local.json、<project>/.claude/settings.json 和 ~/.claude/settings.json。只在一个项目试用时,配置可以放在该项目里。Claude Code 要等你信任目录后才会读取项目设置。全新安装如果还卡在登录提示,作者建议先把配置放进用户级的 ~/.claude/settings.json。
设置文件 env 里的同名变量在多数会话中会盖过 shell 变量。排查密钥时,还得看取值顺序 ANTHROPIC_AUTH_TOKEN → ANTHROPIC_API_KEY → apiKeyHelper。上次试跑时导出的 token 仍可能优先于这次配好的 helper。模型则按 /model → claude --model → ANTHROPIC_MODEL → model 设置取值。作者建议迁移完成后,把试跑留下的 ANTHROPIC_* 从当前 shell 和 ~/.zshrc、~/.bashrc 等启动文件中清掉。
换模型时,五个槽位和上下文都得核对
默认情况下,Claude Code 仍会请求 opus、sonnet、haiku 等 Claude 模型名。原文说切换到其他模型时要映射五个槽位,但没有列全五项配置名。只改 ANTHROPIC_MODEL 时,其他未映射的槽位仍可能请求 Claude,在提供 Claude 的多模型网关上就可能按 Claude 价格计费。模型还要支持工具调用,因为 Claude Code 靠它编辑文件和执行命令。UberLLM 的 GET /v1/models 用 supports_tools 标记这项能力,发给不支持工具调用的模型会收到 400 tools_not_supported。
原文称 Claude Code 对非 Claude 模型默认按 200,000 tokens 估算上下文,并在达到上限前压缩对话,也就是把较早的对话整理成摘要,腾出后续可用空间。模型支持 100 万 tokens 时,可以在模型 ID 后加 [1m],例如 deepseek/deepseek-v4-pro[1m]。其他窗口大小则用 CLAUDE_CODE_MAX_CONTEXT_TOKENS 填实际值,例如 "400000"。
要调压缩时机,可把 autoCompactWindow 或 CLAUDE_CODE_AUTO_COMPACT_WINDOW 设为 100,000 到 1,000,000 tokens,再用 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 指定窗口的 1 到 100 百分比。autoCompactEnabled: false 会关闭自动压缩。上下文上限照模型实际容量填,填大了可能前几轮都能跑,直到对话超过模型容量才报错。
用 /status 和直连请求缩小故障范围
先用 /status 看 Claude Code 当前显示的 API 地址,再用同一把密钥发一个最小的 Messages API 请求。
curl https://api.uberllm.dev/v1/messages \
-H "Authorization: Bearer $(cat ~/.uberllm/key)" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"claude-haiku-4-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'
最后一行只让 claude-haiku-4-5 回一条最多 16 tokens 的消息。能收到响应,说明这条路径、这把密钥和这个模型可以完成一次基础请求。Claude Code 仍报错时,先查配置优先级,再看实际选中的模型及其工具调用能力。
切到第三方端点后,会话无法使用依赖 claude.ai 登录的 connectors、/schedule 和 Remote Control。客户端成本按 Anthropic 标价在本地估算,实际费用看供应商的用量页面。UberLLM 的状态栏脚本最多每分钟读一次 GET /v1/balance,平台采用预付费且没有免费档。
回退时,从设置里删掉 apiKeyHelper 和 ANTHROPIC_*,再清掉当前终端中已导出的变量,下次启动就会恢复 Anthropic 登录。用 curl -fsSL https://uberllm.dev/install/claude-code.sh | sh 安装的,对应回退命令是 curl -fsSL https://uberllm.dev/install/claude-code.sh | sh -s -- --uninstall。用 npx uberllm init 安装的,执行 npx uberllm init --undo。要让密钥失效,还需要在供应商后台撤销。
我的判断
把测试分成「客户端实际用了什么配置」和「网关能否处理这次请求」,是原文最实用的做法。但 ping 成功只验证了示例请求。原文没有给不同模型的长会话、压缩前后或工具调用成功率的对照数据。能接上网关、会调用工具、能稳定完成跨文件修改,是三个需要分别验证的问题。压缩参数可以作为调试起点,其效果还得看实际任务。
只试一个模型家族时,模型厂商自己的兼容端点也能走这套流程,并少经过一层网关。用多模型网关则要核对请求最终交给谁、账单按哪个模型记。apiKeyHelper 解决的是密钥存放问题,会话读到的代码和文件内容仍会发给提供推理服务的一方。涉及客户数据或凭据时,这条数据路径比配置是否好用更重要。
能拿来做什么
- 在无敏感数据的前端或 Node 小项目里,先用临时环境变量接通端点,再让 Claude Code 修改一个文件并跑一次现有测试,顺手验证工具调用。
- 打算长期在单个仓库用第三方模型时,把地址和模型配置放在项目本地设置里,用
apiKeyHelper读密钥,并用/status核对最终生效的地址。 - 做跨文件重构前,按供应商给出的实际容量设置上下文,再用同类任务检查压缩后能否继续遵守原有约束,并到供应商用量页面核对实际模型与费用。