Claude Code 接中转站 / 第三方 API 配置教程（2026）：settings.json、环境变量、模型名与常见报错

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://中转站地址",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的密钥"
  }
}

保存后重新运行 claude，不用登录就能用。最常见的三个坑：地址后面多写了 /v1；密钥放错了变量（服务商要求 x-api-key 时要改用 ANTHROPIC_API_KEY）；中转站的模型名和 Claude Code 默认请求的名字对不上。

下面每一步都在 2026 年 10 月 17 日用 Claude Code 2.1.300 实测过：我们在本机搭了一个记录请求的测试服务，把 Claude Code 实际发出的地址、请求头和模型名抓了下来；报错原文来自真实服务的返回。还没装 Claude Code 的，先看 Claude Code 安装教程。

接上中转站后，什么变了、什么没变

「中转站」在 Claude Code 官方文档里叫 LLM 网关（LLM gateway）：Claude Code 不直接连 Anthropic，而是把请求发给你指定的地址，由对方转发给模型并按用量收费。官方支持这种用法，靠的就是 ANTHROPIC_BASE_URL 这个设置。

准备：从服务商那里拿到两样东西

1. 地址（Base URL），比如 https://api.foo。
2. 密钥，通常以 sk- 开头。

另外确认一件事：这个服务商支持 Claude 原生接口（Anthropic Messages，路径是 /v1/messages）。Claude Code 只会用这种格式发请求，只提供 OpenAI 格式接口的服务商不能直接接。

以 api.foo 为例：地址是 https://api.foo；密钥在 控制台 → API 密钥 里点「创建 API 密钥」生成，以 sk- 开头。创建时确认这把密钥能用 Claude 模型（每个模型能在哪些分组使用，模型广场里能查到）。

方法一：写进 settings.json（推荐）

写进配置文件后，以后每次打开终端都不用再设置，Claude Code 的后台任务也能读到。官方也推荐这种做法。

放在哪个文件

打开文件

Mac / Linux 在终端里运行（没有就新建，然后用文本编辑打开）：

mkdir -p ~/.claude && touch ~/.claude/settings.json && open -e ~/.claude/settings.json

Linux 没有 open -e，把最后一段换成 nano ~/.claude/settings.json。

Windows 在 PowerShell 里运行：

mkdir "$env:USERPROFILE\.claude" -Force; notepad "$env:USERPROFILE\.claude\settings.json"

记事本提示「找不到文件，是否新建」时点「是」。

写入内容

以 api.foo 为例，完整写法：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.foo",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的密钥",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

• ANTHROPIC_BASE_URL：服务商的地址，写到域名为止，后面不加 /v1（原因见下文）。
• ANTHROPIC_AUTH_TOKEN：你的密钥，整串复制，前后不要有空格。
• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC：可选。关掉自动更新检查、使用统计、错误上报这些和干活无关的网络请求，网络连不上 Anthropic 时能少很多无用的连接尝试。代价是不再自动更新，记得隔段时间手动运行 claude update。

文件里已经有其他设置的，把这几行加进已有的 "env" 里，不要再写一个新的 { }。JSON 格式很严格：每行之间用英文逗号隔开，最后一行后面不能有逗号，引号必须是英文的 "。

保存后关掉正在运行的 Claude Code，重新运行 claude。

方法二：设成终端环境变量（适合先试一下）

只在当前这个终端窗口里有效，关掉窗口就没了，适合第一次接入时先试试。

Mac / Linux（zsh 或 bash）：

export ANTHROPIC_BASE_URL=https://api.foo
export ANTHROPIC_AUTH_TOKEN=sk-你的密钥
claude

Windows PowerShell：

$env:ANTHROPIC_BASE_URL = "https://api.foo"
$env:ANTHROPIC_AUTH_TOKEN = "sk-你的密钥"
claude

Windows CMD：

set ANTHROPIC_BASE_URL=https://api.foo
set ANTHROPIC_AUTH_TOKEN=sk-你的密钥
claude

几点要注意：

• 想每次打开终端都生效，把 export 那两行加到 ~/.zshrc（Mac 默认）或 ~/.bashrc 里。但从程序坞、开始菜单直接打开的编辑器读不到这些变量，所以长期使用还是推荐方法一。
• 两边都设了，以 settings.json 为准。我们实测：settings.json 指向一个地址、终端里又 export 了另一个地址，请求还是发到了 settings.json 里的那个。改了终端变量却不生效时，先看看 settings.json 里是不是已经写了。

方法三：用 CC Switch 一键切换

如果你经常在几个服务商、或者官方账号和中转站之间来回切换，可以用 CC Switch 这类图形界面工具管理，它会帮你改写 Claude Code 的配置文件。api.foo 控制台里每把密钥的「⋯」菜单都有「CC Switch」，点一下就能把地址和密钥导入。详细步骤见 CC Switch 安装与配置教程。

怎么确认真的接上了

1. 运行 claude，不出现登录界面，直接进入对话，说明它读到了密钥。
2. 输入 /status，在 Status 页看两行：
   • Anthropic base URL：显示你填的服务商地址。没有这一行，说明地址没生效。
   • Auth token 或 API key：写着 ANTHROPIC_AUTH_TOKEN 或 ANTHROPIC_API_KEY，说明用的是服务商的密钥，而不是以前登录的官方账号。
3. 随便发一句话，正常回复就说明全通了。

如果第 3 步报错，可以绕开 Claude Code，用一条命令直接测试地址和密钥（这是官方文档给的测试方法，需要先按方法二把两个变量 export 到当前终端里）：

curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-haiku-5-5", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

怎么看结果：

• 返回内容以 {"id":"msg_ 开头：地址和密钥都没问题，问题出在 Claude Code 的配置上。
• 返回「模型不存在」之类的报错：地址和密钥也是对的（服务商先验证了密钥才去找模型），换一个服务商支持的模型名再试。
• 最后一行是 401：密钥不对，或者服务商要求 x-api-key 请求头，见下一节。

地址后面要不要加 /v1

不加。我们抓到的请求显示，Claude Code 会自己在地址后面拼上 /v1/messages，实际发出的是：

POST https://你填的地址/v1/messages?beta=true

所以地址只写到域名（或者服务商说明里写到的那一层）。多写了 /v1，就会变成 /v1/v1/messages，大多数服务商会返回 404。也不要把 /v1/messages 整个写进去。

ANTHROPIC_AUTH_TOKEN 还是 ANTHROPIC_API_KEY

两个变量都是放密钥的，区别在于放进哪个请求头：

放错了，服务商在它读的那个请求头里找不到密钥，就会报 401。服务商没说明的，先用 ANTHROPIC_AUTH_TOKEN，报 401 再换成 ANTHROPIC_API_KEY 试试。api.foo 两种都认。

和已登录的官方账号同时存在时：

• 设了 ANTHROPIC_AUTH_TOKEN，它立刻优先，请求走服务商，官方订阅额度不再消耗；官方登录信息还保存在电脑上，删掉这个变量就回到官方账号。
• 设了 ANTHROPIC_API_KEY，交互模式下第一次启动会问你是否使用这个密钥。如果你点了拒绝，以后它会被默默忽略，要到 /config 里打开「Use custom API key」才能恢复。

模型名：Claude Code 默认请求哪个模型

这是接中转站最容易出问题的地方：Claude Code 按自己的模型名发请求，服务商那边必须有同名的模型。我们实测 2.1.300 版本发出的模型名如下：

另外，生成会话标题这类后台小任务用的是 haiku 对应的模型。

切换方法和官方一样：会话里输入 /model 打开选择列表，或者启动时用 claude --model sonnet。

服务商的模型名对不上时

服务商的模型列表里正好有上面这些名字，就什么都不用设（api.foo 的 Claude 模型名和官方一致，可以直接用）。名字不一样时，用下面几个变量把别名对应到服务商的名字，同样写在 settings.json 的 "env" 里：

{
  "env": {
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "服务商的 Opus 模型名",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "服务商的 Sonnet 模型名",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "服务商的 Haiku 模型名",
    "ANTHROPIC_DEFAULT_FABLE_MODEL": "服务商的 Fable 模型名"
  }
}

我们实测：设置 ANTHROPIC_DEFAULT_SONNET_MODEL=my-sonnet 后选 sonnet，请求里的模型名就变成了 my-sonnet。如果这个名字 Claude Code 不认识，启动时会提示：

Claude Code doesn't recognize the model "my-sonnet", so it assumes a context window of 200k tokens.

意思是它不知道这个模型的上下文有多长，先按 20 万 token 处理，对话太长时会提前自动压缩。不影响正常使用；确实需要更长上下文的，按官方说明设置 CLAUDE_CODE_MAX_CONTEXT_TOKENS。

其他几个和模型有关的设置：

• CLAUDE_CODE_SUBAGENT_MODEL：子代理默认用的模型，可以设成便宜一点的模型省钱。
• ANTHROPIC_DEFAULT_MODEL：新会话默认用哪个模型（2.1.236 及以上版本）。

让 /model 列表显示服务商的全部 Claude 模型

在 settings.json 的 "env" 里加上 "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"，Claude Code 每次启动时会向服务商请求一次模型列表（我们抓到的是 GET /v1/models?limit=1000），把服务商的模型加进 /model 选择列表。

实测要点：

• 只保留名字里带 claude 或 anthropic 的模型。我们故意在列表里放了一个 GPT 模型，被 Claude Code 过滤掉了。
• 结果缓存在 ~/.claude/cache/gateway-models.json，下次启动时刷新。
• 服务商 3 秒内没响应、或者这个地址发生了跳转，就静默跳过，列表不变。

api.foo 的 /v1/models 返回的是这把密钥能用的模型，格式符合 Claude Code 的要求。

VS Code 插件、桌面版和远程服务器

VS Code 插件

插件启动前会自己检查登录状态，这个检查不读 ~/.claude/settings.json 里的密钥，所以只改 settings.json 的话，插件可能还是让你登录。按官方说明，在 VS Code 的用户设置里配置：

1. 按 Cmd+Shift+P（Windows：Ctrl+Shift+P），输入并选择 Preferences: Open User Settings (JSON)。
2. 加入下面几行（文件里已有内容的，放进最外层的 { } 里）：

{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://api.foo" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-你的密钥" }
  ],
  "claudeCode.disableLoginPrompt": true
}

disableLoginPrompt 就是设置界面里的「Disable Login Prompt」，作用是不再弹出登录提示，官方说明里写明是给接第三方服务的人用的。

Claude 桌面版

桌面版不读 ANTHROPIC_BASE_URL 和 settings.json，要在它自己的界面里设置：菜单 Help → Troubleshooting → Enable Developer Mode，应用重启后多出一个 Developer 菜单，选 Developer → Configure Third-Party Inference，填服务商地址。

远程服务器（SSH 登录的 Linux）

在服务器上装好 Claude Code 后，在你自己的用户目录里建 ~/.claude/settings.json，内容和方法一一样。这个文件在你自己的目录下，不需要 root 权限。没有 root 权限时 npm 全局安装可能报权限错误，解决办法见安装教程里的权限错误一节。

长任务、超时和自动重试

• 请求超时：Claude Code 默认等 10 分钟（API_TIMEOUT_MS=600000）。网络慢、经常超时的，可以在 "env" 里调大。
• 100 秒限制：很多服务商前面套了 Cloudflare，单个请求超过 100 秒没有返回任何数据会被断开，报 524。Claude Code 用的是流式输出，一般不会碰到；真碰到了，问服务商有没有不经过 Cloudflare 的地址。api.foo 的直连线路是 https://dc.api.foo，没有这个限制，长任务可以把地址换成它。
• 自动重试：请求失败时 Claude Code 默认自动重试 10 次，每次等得更久。我们用错误的密钥实测，服务器上看到它隔 1、2、3、5、10、18、35 秒……一次次重试，几分钟后才把错误显示出来。所以密钥填错时，Claude Code 看起来像「卡住了」。排查问题时可以临时设 CLAUDE_CODE_MAX_RETRIES=0，错误会立刻显示。

在国内用：需要知道的几件事

• 安装：官方安装脚本在国内网络下经常下载失败，用 npm 国内镜像几秒钟就能装好，见 Claude Code 安装教程。
• 不需要 Claude 账号：接中转站后，你的电脑不登录 Anthropic 账号，也就不存在你自己的官方账号被封的问题。风险转到了服务商一侧：它的上游出问题，服务会中断。所以挑服务商时要看稳定性和计费是否透明，方法见 API 中转站怎么选。
• 网络：模型请求只发往你填的地址。设了 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 后，自动更新、统计这类连接也会关掉。还有一个例外：Claude Code 抓取网页（WebFetch 工具）前，会先连 api.anthropic.com 做一次安全检查，连不上时，在 settings.json 里加 "skipWebFetchPreflight": true（和 "env" 同一层）。
• 会看到的一条英文提示：接中转站后，启动时可能出现一段以 We're changing auto mode to no longer charge for classifier requests 开头的提示，后面写着 Nothing breaks: auto mode keeps working。意思是官方给「自动模式」做了计费调整，你的请求经过第三方服务，享受不到这个调整，自动模式照常可用。不影响使用，可以忽略。

切回官方账号

1. 把 settings.json 里的 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN（或 ANTHROPIC_API_KEY）删掉，终端里 export 过的也删掉，或者重开一个终端。
2. 重新运行 claude。以前登录过的官方账号会自动恢复，没登录过的按提示用 /login 登录。

反过来，只想用中转站、并把电脑上保存的官方登录清掉，在 Claude Code 里输入 /logout。

常见报错和解决办法

下面的报错原文都可以直接复制到页面里搜索（Mac 按 Cmd+F，Windows 按 Ctrl+F）。

401 无效的令牌：服务商不认这个密钥

Failed to authenticate. API Error: 401 无效的令牌 (request id: …)

别家服务商的原文可能是 invalid x-api-key、Invalid API key，意思一样。常见原因：密钥复制错了或多了空格；放错了变量（服务商要 x-api-key，你用的是 ANTHROPIC_AUTH_TOKEN，或者反过来）；密钥已被删除、禁用、过期，或者这把密钥自己的额度用完了。

怎么办：重新完整复制密钥；换 ANTHROPIC_AUTH_TOKEN / ANTHROPIC_API_KEY 试试；到服务商控制台看密钥状态。前面说过，这个错误要先自动重试几分钟才显示，排查时设 CLAUDE_CODE_MAX_RETRIES=0 能立刻看到。

启动警告 auth may not work as expected：两套身份同时存在

启动时出现一段以 auth may not work as expected 结尾的警告，旧版本是：

Auth conflict: Both a token (…) and an API key (…) are set

原因是电脑上同时有服务商的密钥和已登录的官方账号。怎么办：只用服务商，就在 Claude Code 里输入 /logout 清掉官方登录；只用官方，就删掉密钥变量。

设好了还是出现登录界面

Claude Code 启动时没读到密钥。常见原因：写在了项目的 .claude/settings.json 里（项目文件夹的设置要等你确认信任这个文件夹后才生效）；文件没保存；JSON 格式有错。怎么办：写进用户目录的 ~/.claude/settings.json，检查逗号和引号都是英文的。

设了 ANTHROPIC_API_KEY 却没反应，也不提示

交互模式下第一次用这个变量会问你要不要用，你以前点过拒绝，之后就会被默默忽略。怎么办：输入 /config，打开「Use custom API key」。

模型不存在、无可用渠道

可能看到的报错：

There's an issue with the selected model …
分组 xxx 下模型 xxx 无可用渠道

Claude Code 请求的模型名服务商那里没有，或者这把密钥用不了这个模型。怎么办：对照服务商的模型列表，用 ANTHROPIC_DEFAULT_*_MODEL 把别名对应过去（见模型名一节），或者换一把能用这个模型的密钥。

提示 doesn't recognize the model：只是提示

Claude Code doesn't recognize the model "xxx", so it assumes a context window of 200k tokens.

用了 Claude Code 不认识的模型名，它按 20 万 token 上下文处理。不影响使用，见模型名一节。

404 或 Invalid URL：地址多写了 /v1

Invalid URL (POST /v1/v1/messages)

地址后面多写了 /v1，路径重复了。怎么办：地址只写到域名。

API returned an empty or malformed response (HTTP 200)：地址指到了网页

地址填成了服务商的官网、控制台这类网页地址，返回的是网页而不是 API 数据。怎么办：用服务商文档里写明的 API 地址。

Connection refused、ENOTFOUND：连不上

Connection refused — a firewall or proxy may be blocking it (ConnectionRefused)
Can't reach the API server — check your internet or DNS (ENOTFOUND)

地址写错了，或者网络到不了这个地址。怎么办：用上面的 curl 命令测试，能立刻看到同样的错误；检查地址拼写、代理和防火墙。

400：context_management、Extra inputs are not permitted

服务商的上游不认识 Claude Code 新加的请求字段。怎么办：在 "env" 里加 "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"。

400：thinking、adaptive

比如报错里有 Input tag 'adaptive' found。服务商的上游不支持 Claude 新模型的自适应思考。怎么办：联系服务商升级。用 Opus 4.6、Sonnet 4.6 的，可以设 CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1 绕过。

400：上下文或 token 超限

报错用服务商自己的话说「上下文太长」「超过 token 上限」。服务商限制的上下文比模型本身小，Claude Code 认不出这是「对话太长」，不会自动压缩。怎么办：输入 /compact 压缩对话；或者把 CLAUDE_CODE_AUTO_COMPACT_WINDOW 设成服务商的上限（最小只能设到 10 万 token）。

403，返回一个 HTML 页面

比如返回 403 Forbidden 网页，而服务商说没收到你的请求。服务商前面的防火墙把请求内容拦了：Claude Code 的提示词里有大量代码和标签，容易被当成攻击。怎么办：联系服务商处理，这一项用户这边改不了。

用户额度不足、预扣费额度失败

用户额度不足, 剩余额度: ¥…

账户余额不够这次请求。怎么办：充值后重试。

429：请求太多、负载已饱和

请求太频繁，或者服务商的上游正忙。怎么办：稍等再试，Claude Code 自己也会自动重试。

524，或者长时间没反应后断开

单个请求超过了服务商的超时时间。怎么办：换服务商不经过 Cloudflare 的地址（api.foo 是 https://dc.api.foo）；网络慢的调大 API_TIMEOUT_MS。

/fast 显示 Fast mode unavailable

Fast mode unavailable due to network connectivity issues

快速模式的可用性检查直接连 Anthropic 官方，不走你的服务商。不影响普通对话；需要快速模式的见官方说明。

SSL 证书错误

SSL certificate verification failed

或者 Self-signed certificate detected。常见于公司网络：公司在检查 HTTPS 流量，Claude Code 不信任公司的证书。怎么办：设置环境变量 NODE_EXTRA_CA_CERTS，指向公司的证书文件。

中文报错原文（无效的令牌、无可用渠道、用户额度不足 等）是 api.foo 这类基于 New API 搭建的服务返回的，其他服务商措辞会不同，原因是一样的。更多报错见 API 报错排查大全。

相关阅读

• Claude Code 安装教程：Mac、Windows、Linux 三种装法与国内常见问题
• CC Switch 安装与配置：一键切换 Claude Code、Codex 的服务商
• API 中转站是什么？怎么选不踩坑
• API 报错排查大全
• Codex 安装与配置

参考资料

• Claude Code 官方文档：连接 LLM 网关、网关兼容性说明、模型配置、设置文件、环境变量、VS Code 插件
• 本文实测：2026-10-17，macOS（Apple 芯片），Claude Code 2.1.300；请求记录来自本机测试服务，报错原文来自 api.foo 的真实返回。