# Claude Code ANTHROPIC_BASE_URL 不生效：先看 /status 再按报错修复

> Claude Code 的 ANTHROPIC_BASE_URL 不生效时，先看 /status 里的地址和凭据，再用 curl 分清配置与网关问题；走网关且版本低于 2.1.299 的先升级。

- Source: https://www.aifreeapi.com/zh/posts/claude-code-anthropic-base-url-not-working
- Language: zh
- Published: 2026-10-15
- Updated: 2026-10-15
- Publisher: AI Free API (https://www.aifreeapi.com)

`ANTHROPIC_BASE_URL` 设了却不生效，先在 Claude Code 里运行 `/status`，看 **Status** 标签页上的两行：`Anthropic base URL` 是否显示你填的地址，`Auth token` 或 `API key` 是否指向你设的那个变量。两行里有一行不对，问题出在变量没进到这次会话、或者凭据没有生效；两行都对但发消息仍然报错，再用下面的 curl 请求和报错对照表去查地址、网络和网关。

最先排查的是这三处：

- **只设了地址，没设凭据，或凭据放错了变量。** 只有 `ANTHROPIC_BASE_URL` 不会替换你已登录的 claude.ai 账号；`ANTHROPIC_AUTH_TOKEN` 以 `Authorization: Bearer` 发送，`ANTHROPIC_API_KEY` 以 `x-api-key` 发送，放错了网关就回 401。
- **同一个变量在 `settings.json` 和终端里各有一个值。** 按官方规则，settings 文件 `env` 里的值会覆盖终端 `export` 的值，只改终端不会生效。
- **地址末尾多写了 `/v1`。** Claude Code 会自己在地址后面拼上 `/v1/messages`，只填根地址。

版本也要看一眼：2026 年 10 月 14 日发布的 2.1.299 修了 4 个只在自定义 `ANTHROPIC_BASE_URL` 下出现的问题，包括流式响应 180 秒没有数据就被中断。截至 2026 年 10 月 15 日，npm 上的 `latest` 是 2.1.300，`stable` 渠道仍是 2.1.292，跟 stable 渠道或用 Homebrew `claude-code` 安装的，目前还拿不到这些修复。

接 DeepSeek、GLM、Kimi 这类非 Claude 模型时还有一条边界：Anthropic 不支持通过任何网关把 Claude Code 接到非 Claude 模型。配置全对、某些功能仍然缺失或工具调用异常时，那是这条路线本身的限制，不是你的配置写错了。

## /status 里的两行：判断地址和凭据有没有进会话

`/status` 默认打开 **Status** 标签页。`Anthropic base URL` 这一行只有在设置了网关地址时才会出现；`Auth token` 或 `API key` 一行会写出生效的是 `ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_API_KEY` 还是 `apiKeyHelper`（见 [Claude Code 官方 LLM 网关连接文档](https://code.claude.com/docs/zh-CN/llm-gateway-connect)）。

| `/status` 显示 | 说明 | 下一步 |
| --- | --- | --- |
| 没有 `Anthropic base URL` 这一行 | 地址变量没有进到这次会话 | 看下文“settings.json 和终端 export”一节；在 VS Code 里出问题的看 VS Code 一节 |
| 有地址，但显示 `Login method` 和一个 claude.ai 账号 | 请求发往你的地址，用的却还是已登录账号的凭据 | 设置凭据变量，必要时运行 `/logout` |
| 地址和 `Auth token` / `API key` 都对，发消息报错 | 配置已经生效，问题在地址本身、网络或网关 | 先跑 curl，再查报错对照表 |

第二种情况容易被忽略：只设 `ANTHROPIC_BASE_URL`、不设网关凭据时，请求会发到你的地址，但生效的凭据仍是已保存的 claude.ai 登录，用量限制和计费也按这个账号算（[官方 LLM 网关说明](https://code.claude.com/docs/zh-CN/llm-gateway)）。

## 用 curl 发一条 1 token 请求：先把配置问题和网关问题分开

这条请求绕开 Claude Code，直接用终端里的变量打网关。它读的是 shell 变量，所以即使你把配置写在 settings 文件里，测试前也先在终端里 `export` 一遍。

```bash
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-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'
```

Windows PowerShell 用这一条：

```powershell
Invoke-RestMethod -Method Post -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `
  -Headers @{ "Authorization" = "Bearer $env:ANTHROPIC_AUTH_TOKEN"; "anthropic-version" = "2023-06-01" } `
  -ContentType "application/json" `
  -Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'
```

如果网关要求 `x-api-key`，把 `Authorization` 那一行换成 `x-api-key: $ANTHROPIC_API_KEY`。`model` 可以换成你的网关提供的模型名，不换也行。结果这样读：

| curl 返回 | 说明什么 |
| --- | --- |
| 以 `{"id":"msg_` 开头、带 `"content":[...]` 的 JSON | 地址可达，凭据被接受 |
| 报模型不存在或未知模型 | 地址和凭据都是通的：网关先通过了鉴权才去拒绝模型名 |
| `401` | 凭据被拒。变量是猜的就换另一个（Bearer 和 `x-api-key` 互换）再试；还是 401，就是密钥本身无效或已被吊销 |
| 一段 HTML 网页，或 `404` | 多半是路径不对，例如地址多写了 `/v1`，或者填成了供应商的网页地址（这是推断，具体返回什么因网关而异） |
| 连接被拒、域名解析失败、长时间无响应 | 网络路径不通：地址写错，或 VPN、防火墙挡住了到网关的路 |

curl 成功、Claude Code 仍然失败，说明问题出在 Claude Code 怎么读配置，或者真实会话发出的请求比这条 1 token 请求多了网关不接受的东西：额外字段、触发防火墙规则的长 prompt、证书。这几类都在下面的对照表里。

![ANTHROPIC_BASE_URL 不生效的三步排查图：先看 /status 有没有 base URL 行和凭据行，再看 curl 返回 msg_、401、HTML/404 或 ENOTFOUND，分别对应的修法](https://www.aifreeapi.com/posts/zh/claude-code-anthropic-base-url-not-working/img/status-curl-diagnosis.webp)

## 报错对照表：Claude Code 走自定义地址时的常见报错

报错原文按 [官方网关排障表](https://code.claude.com/docs/zh-CN/llm-gateway-connect) 保留英文，方便直接搜索；不同版本的措辞可能略有差别。

| 你看到的 | 原因 | 修法 |
| --- | --- | --- |
| 设了地址，启动时仍要求登录 | Claude Code 没拿到凭据：可达的地址不算凭据；项目 `.claude/settings.json` 里的 `env` 在首次向导和信任提示之后才生效 | 把 `ANTHROPIC_AUTH_TOKEN` 放进终端 export 或 `~/.claude/settings.json` |
| 启动警告列出两个凭据来源，以 `auth may not work as expected` 结尾（旧版是 `Auth conflict: Both a token (SOURCE) and an API key (SOURCE) are set`） | 网关凭据和已保存的登录同时存在 | 运行 `/logout`，只留网关凭据 |
| `ANTHROPIC_API_KEY` 设了却被忽略，也没有任何提示 | 这个变量在交互模式下要确认一次，之前拒绝过就会被静默忽略 | `/config` 里打开 `Use custom API key` |
| `401`，提示 token 无效或无法识别 | 密钥不是这个网关发的，或者放在了网关不读的请求头里 | 换变量，或到网关重新生成密钥 |
| `Connection refused … (ConnectionRefused)`、`Can't reach the API server … (ENOTFOUND)` | 地址上没有服务响应，或域名解析不了 | 用 curl 复现，核对地址和网络 |
| `API returned an empty or malformed response (HTTP 200)` | 网关或中间的代理返回了不是 API 响应的内容，常见是 HTML 错误页或登录页 | 用 curl 看实际返回，修正地址或网关路由 |
| `403` 加一段 HTML（例如 `403 Forbidden`），网关日志里却没有这条请求 | 网关前面的 WAF 或反向代理按请求体规则拦了请求；Claude Code 的 prompt 带 XML 风格标签和源代码，短的 curl 能过，真实会话过不了 | 让 `/v1/messages` 路径跳过请求体检查（AWS WAF 的 `CrossSiteScripting_Body` 规则） |
| `SSL certificate verification failed`、`Self-signed certificate detected`，curl 却正常 | Claude Code 的运行时不信任 curl 用的那个 CA，常见于公司 TLS 检查代理 | 把 `NODE_EXTRA_CA_CERTS` 设为 CA 证书文件路径 |
| `400`，提到 `context_management` 或 `Extra inputs are not permitted` | 网关的上游不接受 Claude Code 发的预发布字段 | `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` |
| `400`，提到 `thinking` 或 `adaptive` | 上游模型版本不支持 adaptive thinking | 升级网关上游；Opus 4.6、Sonnet 4.6 可设 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` |
| `400`，用网关自己的话说上下文超限（如 `ContextWindowExceededError`） | 网关的上下文比模型小，Claude Code 认不出这条报错，不会自动压缩 | `/compact` 恢复会话，再设 `CLAUDE_CODE_AUTO_COMPACT_WINDOW` |
| `Prompt is too long · automatic compaction failed`，接近 200K tokens 时出现 | 2.1.299 之前，使用网关专用模型名的会话会这样结束 | 升级到 2.1.299 或更新版本 |
| 本地模型或慢网关长时间停顿后，流式响应被中断 | 2.1.299 之前是 180 秒没有数据就中断 | 升级；停顿超过 5 分钟再看 `API_FORCE_IDLE_TIMEOUT` |
| `/model` 里找不到网关提供的模型 | 网关的模型名不在 Claude Code 内置列表里 | `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` |

`401` 和“还是要求登录”最常见，下面两节先展开；`400` 系列和版本问题放在后面。

## 设了 ANTHROPIC_BASE_URL，Claude Code 还是要求登录 claude.ai 账号

可达的地址不是凭据。Claude Code 自己没有凭据时，就会回到 claude.ai 登录，哪怕 curl 已经测通。按下面的顺序检查：

1. **有没有设凭据变量。** 至少要有 `ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_API_KEY` 或 `apiKeyHelper` 之一。不确定网关要哪种，先用 `ANTHROPIC_AUTH_TOKEN`，它设了就立即优先于已保存的登录。
2. **凭据是不是写在项目的 `.claude/settings.json` 或 `.claude/settings.local.json` 里。** 交互会话里，项目设置文件的 `env` 要等首次向导和文件夹信任提示走完才生效，所以第一次启动会先要你登录。把凭据移到终端 export、`~/.claude/settings.json`（Windows 是 `%USERPROFILE%\.claude\settings.json`）或托管设置里。会被提交进仓库的项目 `.claude/settings.json` 本来也不该放密钥。
3. **用的是 `ANTHROPIC_API_KEY` 吗。** 这个变量在交互模式下第一次出现时要确认；以前选过拒绝，它就会被静默忽略、不再询问。到 `/config` 打开 `Use custom API key`，或者改用 `ANTHROPIC_AUTH_TOKEN`。
4. **启动时有没有凭据冲突警告。** 变量和已保存的登录同时在，请求会用变量，但旧登录可能带来意料之外的认证行为。运行 `/logout` 清掉已保存的登录。

公司电脑上如果看到 `This machine's managed settings require a first-party login`，是托管设置里配置了 `forceLoginMethod` 或 `forceLoginOrgUUID`，它们和网关凭据不能同时使用，只能由管理员去掉这些设置，或者你改用托管设置要求的登录方式。

想换回官方账号时，取消网关凭据变量即可，Claude Code 会回到之前保存的登录。登录本身报 OAuth 错误，看 [Claude Code 登录失败怎么办：排查 OAuth 500、403 与 Invalid code](/zh/posts/claude-code-oauth-error)。

## 报 401、提示 key 不对：把密钥放进网关读取的那个变量

两个变量把同一个密钥放进不同的请求头：

| 变量 | 发送方式 | 网关文档里一般这样写 |
| --- | --- | --- |
| `ANTHROPIC_AUTH_TOKEN` | `Authorization: Bearer <密钥>` | bearer token、Authorization 请求头 |
| `ANTHROPIC_API_KEY` | `x-api-key: <密钥>` | API key、x-api-key |
| `apiKeyHelper` | 两个请求头都发 | 密钥会轮换或来自密钥库 |

密钥放进了网关不读的请求头，网关就回 401。供应商文档写了用哪个就照写；没写就先用 `ANTHROPIC_AUTH_TOKEN`，curl 返回 401 再换另一个。

换了变量还是 401，再查两种“残留”：

- **旧的 `ANTHROPIC_API_KEY` 还在。** 以前直连 Anthropic 时写进 `~/.zshrc`、`~/.bashrc` 或 Windows 用户环境变量的真实密钥，会以 `x-api-key` 一起发出去。在启动 `claude` 的同一个终端里用 `echo $ANTHROPIC_API_KEY`（PowerShell 用 `echo $env:ANTHROPIC_API_KEY`）看一眼。[OpenRouter 的 Claude Code 接入文档](https://openrouter.ai/docs/cookbook/coding-agents/claude-code-integration) 的做法是显式写 `ANTHROPIC_API_KEY=""`；注意 `/logout` 只清已保存的登录，清不掉 shell 里的变量。
- **变量展开成了空值。** `export ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY"` 在加载配置文件的那一刻展开。如果 `OPENROUTER_API_KEY` 定义在它后面、另一个文件里，或者由密钥管理工具稍后注入，`ANTHROPIC_AUTH_TOKEN` 就是空字符串，每个请求都会鉴权失败。

## settings.json 和终端 export 不一致：settings 文件里的值生效

同一个变量既在终端 `export`、又写在 settings 文件的 `env` 里时，大多数会话用的是 settings 文件的值：Claude Code 会把 `env` 里的每一项写进进程环境，替换从 shell 继承来的值（[官方环境变量文档](https://code.claude.com/docs/zh-CN/env-vars)）。所以“终端里改了地址却没变化”，先查 `~/.claude/settings.json` 和项目里的 `.claude/settings.local.json` 有没有留着旧的 `ANTHROPIC_BASE_URL` 或凭据。托管设置里的同名变量又会覆盖用户和项目设置。

![同一个变量写在多处时的生效顺序：托管设置高于 settings 文件的 env，再高于终端 export；右侧列出 VS Code 扩展、Claude 桌面版和项目 .claude/settings.json 三个例外](https://www.aifreeapi.com/posts/zh/claude-code-anthropic-base-url-not-working/img/env-precedence-surfaces.webp)

几条跟“改了没反应”有关的规则：

- **保存 settings 文件后**，正在运行的会话会应用新增和修改的值；但从文件里删掉一个变量，不会在当前会话里取消它，要等下次启动 `claude`。切换供应商后，退出再重新运行最稳妥，然后用 `/status` 确认。
- **终端 export 只对当前终端和从它启动的程序有效。** 从程序坞或开始菜单打开的编辑器拿不到；只靠 shell 变量也不能稳定传给后台代理，需要一直走网关的放进 settings 文件。
- **Windows 的永久变量**：PowerShell 用 `[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://你的网关地址", "User")`，CMD 用 `setx`，设完要开一个新终端才生效。
- **原生安装版的 Claude Code 不读项目目录里的 `.env` 文件**（OpenRouter 文档的提醒），写在 `.env` 里的变量进不了会话。
- **用切换工具管理多个供应商时**，Claude Code 认的仍然只是环境变量和它自己的 settings 文件。切换后重开 `claude`，看 `/status` 里的地址是否已经变了。

`env` 里的值按原样复制，不经过 shell，`~`、`$HOME` 这类写法不会被展开。

## 接口地址只填根地址：Claude Code 会自己拼 /v1/messages

`ANTHROPIC_BASE_URL` 对应的是 Anthropic Messages 格式，Claude Code 的推理请求发往地址后面的 `/v1/messages`（[官方网关兼容说明](https://code.claude.com/docs/zh-CN/llm-gateway-protocol)）。因此：

- **只填根地址。** OpenRouter 文档给的是 `https://openrouter.ai/api`，不是 `.../api/v1`；Ollama 本地是 `http://localhost:11434`。有的供应商文档还会专门提醒只填域名、不带 `/v1`。地址已经以 `/v1` 结尾时，实际请求会变成 `/v1/v1/messages`（推断），返回 404 还是 HTML 页面取决于网关。
- **供应商要提供 Anthropic 格式的接口。** 只给 OpenAI 格式（`/chat/completions`）地址的服务，填进 `ANTHROPIC_BASE_URL` 不会工作，要用它专门给 Claude Code 的 Anthropic 兼容地址。
- **对照用的正确取值**（来自各自文档，供核对，不是完整教程）：

| 路线 | `ANTHROPIC_BASE_URL` | 凭据 |
| --- | --- | --- |
| OpenRouter | `https://openrouter.ai/api` | `ANTHROPIC_AUTH_TOKEN` 填 OpenRouter 密钥，`ANTHROPIC_API_KEY=""` |
| Ollama 本地 | `http://localhost:11434` | `ANTHROPIC_AUTH_TOKEN=ollama`，`ANTHROPIC_API_KEY=""` |
| Ollama 云端 | `https://ollama.com` | `ANTHROPIC_AUTH_TOKEN` 填 `OLLAMA_API_KEY` 的值 |

报 `ConnectionRefused` 或 `ENOTFOUND` 时，地址上根本没有服务响应：本地模型没启动、端口不对、域名拼错，或者 VPN、防火墙挡住了。注意 `HTTP_PROXY` 这类变量设置的是网络代理，跟 `ANTHROPIC_BASE_URL` 指向的 API 网关是两回事。

## 终端能用、VS Code 不行：改 claudeCode.environmentVariables

VS Code 扩展在启动前用自己的设置检查凭据。`~/.claude/settings.json` 里的值能传给它启动的进程，却过不了扩展自己的登录检查，所以会出现终端正常、VS Code 要求登录的情况。用命令面板的 **Preferences: Open User Settings (JSON)** 打开 VS Code 用户设置，加上：

```json
{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://llm-gateway.example.com" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-gateway-key" }
  ]
}
```

其他入口各有各的读法：

- **Claude 桌面版不读 `ANTHROPIC_BASE_URL`，也不读 `settings.json`。** 它用自己的第三方推理配置：管理员下发，或者 Help → Troubleshooting → Enable Developer Mode，再到 Developer → Configure Third-Party Inference 填地址。启动时报 `Gateway was unreachable`，就是连不上配置的地址。
- **GitHub Actions** 从 workflow 的 `env` 读 `ANTHROPIC_BASE_URL`；密钥作为 `anthropic_api_key` 输入传入，会以 `x-api-key` 发送。网关要 Bearer 时，`env` 里再放一份 `ANTHROPIC_AUTH_TOKEN`。
- **Agent SDK（TypeScript）** 设置 `options.env` 会整个替换子进程环境，要先展开 `...process.env`，否则网关变量会丢；Python 版是合并，不需要这样做。

## 网关返回 400：Extra inputs、adaptive 与上下文超限

curl 能通、真实会话报 400，通常是 Claude Code 发出的请求里有网关上游不接受的内容。按报错里出现的词处理：

**`context_management`、`Extra inputs are not permitted`，或其他无法识别的字段。** 设 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`，它会去掉大部分预发布的 `anthropic-beta` 请求头和对应字段。只是会话标题、记忆召回、提示词钩子失败的，可以只关结构化输出：`CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS=1`（2.1.288 起可用）。

**`thinking` 或 `adaptive`，例如 `Input tag 'adaptive' found`。** 网关上游的模型版本不支持 adaptive thinking，要升级上游；用 Opus 4.6、Sonnet 4.6 时可以改设 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1`。

**网关用自己的话说上下文或 token 超限。** 例如 `ContextWindowExceededError` 或 `prompt token count of N exceeds the limit of M`。网关限制的上下文比模型原生窗口小，并改写了上游报错，Claude Code 认不出这是“prompt 太长”，就不会自动压缩重试。先运行 `/compact` 救回会话，再把 `CLAUDE_CODE_AUTO_COMPACT_WINDOW` 设成网关的上限（只接受纯数字，例如 `180000`），同时把 `CLAUDE_CODE_MAX_OUTPUT_TOKENS` 设得低于网关模型的输出上限。这个值最小只能是 100,000，网关上限低于 10 万时只能靠手动 `/compact`。另外，从 2.1.285 起，自定义地址下的会话会使用支持 1M 上下文的模型的完整窗口，网关只到 200K 时运行 `/autocompact 200k`。

GitHub 上还有两条与此相关、尚未关闭的用户报告，Anthropic 没有确认原因：

- [#95087](https://github.com/anthropics/claude-code/issues/95087)：自定义地址下，会话的第一个请求带着 `tool_addition` 内容块，严格的 Anthropic 兼容网关以 400 拒收，Claude Code 随后静默去掉它们重试。2026 年 10 月 13 日有人在 2.1.296 上补充，遇到的网关上这个回退没有触发，会话无法继续。
- [#101897](https://github.com/anthropics/claude-code/issues/101897)：2026 年 10 月 13 日，一位用户从 2.1.269 升级到 2.1.296 后，自建模型的会话报 OpenAI 风格的 maximum context length 400 错误，压缩既没能预防也没能恢复；报告者退回 2.1.269 后不再出现。

遇到同样情况，先按上面的官方办法处理；还不行，可以参考这两条报告里的抓包和版本信息，到 issue 下补充自己的复现。

## 更新后才出问题：2.1.299 修了哪些网关问题，stable 还停在 2.1.292

[Claude Code 更新日志](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md) 里，2.1.299（npm 发布时间为北京时间 2026 年 10 月 14 日 08:23）修了 4 个与自定义 `ANTHROPIC_BASE_URL` 有关的问题：

| 2.1.299 之前 | 2.1.299 之后 |
| --- | --- |
| 发往 Anthropic 的功能开关、启动、fast mode、个人资料和反馈请求，会带上你给第三方网关配置的 API 密钥 | 不再带网关密钥（Anthropic 的 API 密钥照常发送） |
| 托管设置文件里设置了 `ANTHROPIC_BASE_URL` 时，向 Anthropic 请求服务器托管设置也会带上网关密钥 | 已修复 |
| 经自定义地址的流式响应 180 秒没有数据就被中断 | 改为等待 300 秒，与功能开关是否加载无关 |
| 使用网关专用模型名的会话，在接近 200K tokens 时以 `Prompt is too long · automatic compaction failed` 结束，请求根本没有发出 | 正常发送请求 |

第一条在更新日志里没有写对应的报错现象，不要把别的报错归到它头上；不过网关密钥本来就不该发往 Anthropic，单凭这一条，走网关的用户也值得升级。同一天还发布了 2.1.300。

升级前先确认自己在哪个渠道：

- 运行 `claude --version` 看当前版本。
- 默认的 `latest` 渠道立即收到新版本；`stable` 渠道一般用大约一周前的版本，并跳过有重大回归的版本。截至 2026 年 10 月 15 日，npm 的 `stable` 标签仍是 2.1.292。由此推断，`stable` 渠道的用户在 stable 跟进到 2.1.299 以上之前没有这些修复，具体什么时候跟进没有公布。
- Homebrew 的 `claude-code` 跟 stable，`claude-code@latest` 跟 latest；Homebrew、WinGet、apt 默认不自动更新，要手动 `brew upgrade` 或 `winget upgrade Anthropic.ClaudeCode`。
- 设置了 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` 的（只放行网关出口的网络会用到它），自动更新也一起关掉了，需要手动更新。

要直接装指定版本，原生安装版可以这样做（详见 [官方安装文档](https://code.claude.com/docs/zh-CN/setup)）：

```bash
curl -fsSL https://claude.ai/install.sh | bash -s 2.1.299
```

```powershell
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 2.1.299
```

如果你把 `autoUpdatesChannel` 改回 `stable`，`minimumVersion` 可以防止被降级。各版本具体改了什么、怎么回退，看 [Claude Code 更新日志：新版改了什么，该用哪个版本](/zh/posts/claude-code-changelog)。

本地模型或慢网关两段输出之间停顿超过 5 分钟，即使升级后也会被中断。这时可以设 `API_FORCE_IDLE_TIMEOUT=0` 关掉这个空闲超时，但独立运行的流式看门狗仍会中断特别长的停顿；单个请求的总超时由 `API_TIMEOUT_MS` 控制，默认 600000 毫秒（10 分钟）。

更早几个版本也有网关相关的修复：2.1.290 修了网关用 400 以外的状态码拒收 beta 请求头时请求失败的问题。还在 2.1.290 以前版本的，一并升级。

## 接 DeepSeek、GLM、Kimi 等非 Claude 模型：哪些问题不是配置写错

[Anthropic 官方说明](https://code.claude.com/docs/zh-CN/llm-gateway) 写得很直接：它不背书、不维护、不审计第三方网关，也不支持通过任何网关把 Claude Code 接到非 Claude 模型。OpenRouter 只保证 Claude Code 在 Anthropic 官方供应商上可用；Ollama 文档说明托管的 WebSearch 和高级工具控制没有完整支持，模型也要选支持工具调用的。

所以 `/status` 正常、curl 正常、基本对话也正常，但出现下面这些情况时，不要再反复改变量：

- **按设计关闭的功能。** 地址指向非 Anthropic 主机时，MCP 工具搜索默认关闭，MCP 工具改为一次性全部加载（网关能转发 `tool_reference` 块时可设 `ENABLE_TOOL_SEARCH=true`）；Remote Control 从 2.1.196 起在这种情况下停用；Remote Control 和语音听写在网关凭据生效期间都不可用。
- **模型名问题。** `/model` 里看不到网关的模型，设 `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` 让 Claude Code 去网关的 `/v1/models` 取列表；模型选择器的更多情况见 [Claude Code 看不到 Fable 5.1？按提示找原因](/zh/posts/claude-code-fable-5-1-not-available)。
- **工具调用、思考、长上下文表现异常。** 这些取决于上游模型和供应商对 Anthropic 格式的兼容程度，Claude Code 一侧能调的只有上一节那些开关。

什么时候该停：变量、凭据、地址都确认无误，报错又落在上面这几类，就去找供应商确认它支持哪些字段和功能，或者换一条支持 Claude 模型的路线，而不是继续在本地改配置。网关返回 529 或 500 时，先分清报错来自哪一层，可参考 [Claude 529 overloaded_error 是什么？怎么处理：先看报错来自哪一层](/zh/posts/claude-529-overloaded-error) 和 [Claude API 500 错误：别盲目重试，先保存 request_id](/zh/posts/claude-api-error-500)。

## 重启、变量选择与订阅额度：几个相邻问题

### 改了 settings.json 里的 ANTHROPIC_BASE_URL，要重启 Claude Code 吗？

保存后，正在运行的会话会应用新增和修改的值；但删掉的变量要等下次启动才会消失，只在启动时读取变量的功能也要重开才更新。排查时直接退出、重新运行 `claude`，再用 `/status` 看地址，最省事。

### ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY 用哪个？

看网关要哪个请求头：要 `Authorization: Bearer` 用 `ANTHROPIC_AUTH_TOKEN`，要 `x-api-key` 用 `ANTHROPIC_API_KEY`。不确定时先用 `ANTHROPIC_AUTH_TOKEN`，它设了就生效，不需要额外确认；curl 返回 401 再换。两个不要同时放真实密钥。

### Claude Code 的环境变量设了是临时的还是永久的？

终端里直接 `export`（或 PowerShell 的 `$env:`、CMD 的 `set`）只在这个终端窗口有效，关掉就没了。要长期生效，写进 `~/.zshrc`、`~/.bashrc`，Windows 用 `[Environment]::SetEnvironmentVariable(..., "User")` 或 `setx` 后开新终端；更稳的是写进 `~/.claude/settings.json` 的 `env`，从哪里启动 Claude Code 都能读到。

### 走自定义地址时，Claude Code 订阅的 5 小时额度还算吗？

网关凭据生效时，请求按网关的计费走，不占 claude.ai 账号的额度；只设地址、没设凭据时，用的仍是已登录账号，用量限制和计费照旧按订阅算。订阅额度本身的规则见 [Claude Code 速率限制与额度：5 小时窗口、周限额，用完怎么办](/zh/posts/claude-code-rate-limit)。