Claude Code 代理配置：网关与企业代理的区别及设置方法（2026）

「Claude Code 代理」其实指两件互不相干的事。一件是LLM 网关（API 中转），它自己应答模型请求，用 ANTHROPIC_BASE_URL 加一个凭据配置；另一件是企业 HTTP 代理，它只是网络强制的出口通道，用 HTTPS_PROXY 配置。两者可以叠加，出错方式完全不同。

把两者混为一谈，是大量接入卡壳的真正原因：有人被告知「我们所有流量都走代理」，于是把 ANTHROPIC_BASE_URL 指向企业代理地址，结果拿到 404 —— 因为那个地址根本不提供 /v1/messages。本文把两条路分开讲，给出各自的准确变量，并说明怎么确认到底哪一条生效。以下内容依据 Anthropic 的 Claude Code 官方文档（2026 年 9 月口径）；这些设置会随版本变动，把某个版本相关的细节当永久结论之前，请先核对当时的文档。

两种都叫「Claude Code 代理」的东西

	LLM 网关 / API 中转	企业 HTTP 代理
它做什么	自己应答模型请求	把 TCP 流量转发到原本要去的地方
谁在运维	平台团队，或托管式中转服务商	网络 / 安全团队
主变量	`ANTHROPIC_BASE_URL`	`HTTPS_PROXY`
还需要什么	网关签发的凭据	有时要 CA 证书，有时要客户端证书
会改变目的地吗	会——请求根本不到 `api.anthropic.com`	不会——目的地不变，只换了到达路径
典型报错	`401`、`404`、模型名未知	TLS 握手失败、连接被重置、请求挂起

一个好用的判别问题：这东西知道「模型」是什么吗？ 网关知道——它会校验你的身份、选上游、返回一个 Messages API 响应。HTTP 代理不知道，它只搬运字节。把 ANTHROPIC_BASE_URL 指向一个只会搬字节的东西，什么都跑不起来。

两者也可能同时需要：网关在内网，而访问内网要经企业代理。这种组合在文末单独讲。

路线一：把 Claude Code 指向网关

官方文档把这件事归结为两个值——base URL 和一个凭据。

export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
export ANTHROPIC_AUTH_TOKEN=sk-gateway-key

两个细节决定它能不能一次跑通。

base URL 只写域名，不带路径。 文档给出的验证请求是向「变量值 + /v1/messages」发 POST（完整命令见下文验证一节），说明 /v1/messages 是客户端自己拼的。变量里再写一次 /v1，路径会变成 /v1/v1/messages 并返回 404——这是最常见的一个坑，而且报错本身不会告诉你原因。

凭据放哪个变量，决定它进哪个 header。 按文档：ANTHROPIC_AUTH_TOKEN 走 Authorization: Bearer，ANTHROPIC_API_KEY 走 x-api-key，apiKeyHelper 命令的输出两个 header 都发。凭据放错变量，就会以网关不读的 header 送达，表现为 401。如果网关方没说是哪一种，文档建议先用 ANTHROPIC_AUTH_TOKEN，测试请求返回 401 再换另一个。

有些网关还要一个路由或租户 header，那是 ANTHROPIC_CUSTOM_HEADERS，每行一对 Name: Value；写进 JSON 配置文件时对之间用 \n 分隔，因为 JSON 字符串不能跨行。

提交前值得知道的两个副作用：网关凭据的优先级高于已保存的 claude.ai 登录态（登录态会保留但不被使用，取消变量即恢复）；文档还写明，网关凭据生效期间 Remote Control 与语音听写不可用，且 ANTHROPIC_BASE_URL 指向非 Anthropic 主机时 Remote Control 同样被禁用。

至于「为什么要用网关」——统一计费、协议转换、可用的网络路径——可以读Claude API 中转是什么，那篇讲的是品类与选型标准。端点后面换成非 Claude 模型会有哪些变化，见Claude Code 换用其他模型。

路线二：企业 HTTP 代理

这条路完全不碰 ANTHROPIC_BASE_URL。请求照样发往 api.anthropic.com（或你的网关），只是换了条路过去。

# HTTPS 代理（推荐）
export HTTPS_PROXY=https://proxy.example.com:8080

# 没有 HTTPS 时用 HTTP 代理
export HTTP_PROXY=http://proxy.example.com:8080

# 指定主机绕过代理——空格或逗号分隔都可以
export NO_PROXY="localhost,192.168.1.1,example.com,.example.com"

文档里几条能省时间的细节：

小写变量同样有效，且 Claude Code 按 https_proxy、HTTPS_PROXY、http_proxy、HTTP_PROXY 的顺序取第一个已设置的。shell 配置里一条陈年的小写 export，会静默压过你刚设的大写那条。
NO_PROXY="*" 表示所有请求都绕过代理。
回环地址不用写。 到 localhost、::1、127.0.0.0/8 的 WebSocket 连接永远不走代理。
不支持 SOCKS 代理。
Basic 认证写在 URL 里：http://username:password@proxy.example.com:8080。文档提醒不要把密码硬编码进脚本。NTLM / Kerberos 这类认证方式，文档建议改用支持该方式的网关。

证书

做 TLS 检查的代理会出示自己的证书，企业环境真正翻车的地方多半在这里。

Claude Code 默认同时信任自带的 Mozilla CA 集合与操作系统证书库，所以根证书已装进系统信任库的代理无需额外配置即可工作。读取系统证书库要求运行时具备 tls.getCACertificates：原生安装包一定有；npm 安装则需要 Node 22.15 及以上。更老的 Node 上只有自带集合与 NODE_EXTRA_CA_CERTS 生效。

# 显式信任一个额外 CA
export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem

# 限定信任哪些证书库（默认 bundled,system）
export CLAUDE_CODE_CERT_STORE=bundled

如果代理要求客户端证书，mTLS 三个变量是 CLAUDE_CODE_CLIENT_CERT、CLAUDE_CODE_CLIENT_KEY，以及可选的 CLAUDE_CODE_CLIENT_KEY_PASSPHRASE。

放行名单

出口受限时，代理需要放行 Claude Code 依赖的主机。文档列出的包括：api.anthropic.com（API 请求）、claude.ai / claude.com / platform.claude.com（认证）、downloads.claude.ai（安装与更新）、registry.npmjs.org（npm 安装与 npx 拉起的 MCP server）。网络配置文档里的完整表格更长，定稿规则前请通读——放行名单只放一半，产生的故障看上去会像毫不相干的 bug。

这些值该放在哪一层

两条路读的都是普通环境变量，所以真正的问题是放进哪一层——这正是Claude Code 配置分层那篇讲透的问题。

shell export——用于试。它只对当前终端及由它启动的程序生效；从 Dock 或开始菜单启动的编辑器看不到。

配置文件的 env 块——用于任何要长期生效的设置：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-gateway-key",
    "HTTPS_PROXY": "https://proxy.example.com:8080"
  }
}

~/.claude/settings.json 对所有项目生效；.claude/settings.local.json 只对单个项目生效且不入库。文档明确要求：凭据不能放进项目里会被提交的 .claude/settings.json。当 shell export 与配置文件 env 块设了同一个变量，配置文件的值胜出。

有一种情况下用配置文件不只是更整洁，而是必须——后台 agent。它们跑在一个比你的 shell 活得更久的按用户 supervisor 进程里，所以只写在 shell 里的 export，只有当那个 shell 恰好冷启动了 supervisor 时才传得到，换个 shell 就静默失效。文档正是因此要求把网络类变量写进配置文件。

怎么确认真的生效了

别假设。Claude Code 读取这些设置时大多不做校验，值填错通常要等到后续某次请求才以报错形式暴露。

启动客户端之前，先直连网关打一发。这一步把「端点通不通、凭据对不对」和「客户端配没配对」分开：

curl -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": "."}]}'

返回以 {"id":"msg_ 开头，说明 URL 与凭据都没问题。返回「模型未知」同样能证明这一点——网关是先通过了鉴权才拒绝模型名的，这个测试不需要你事先知道它服务哪些模型。

进到会话里，跑 /status，看文档点名的这几行：

Anthropic base URL——只有设置了网关地址才出现。没有这一行，说明变量根本没传进会话。
Auth token / API key——会写明是 ANTHROPIC_AUTH_TOKEN、ANTHROPIC_API_KEY 还是 apiKeyHelper。如果看到的是写着 claude.ai 账号的 Login method 行，说明网关凭据没生效。
Proxy——显示当前代理 URL；无法解析的值会被标为 invalid 并忽略。
mTLS client cert / mTLS client key——只有文件加载成功才出现，缺行即等于加载失败。
Additional CA cert(s)——只显示 NODE_EXTRA_CA_CERTS 路径，并不校验文件是否加载成功。这一项要去 debug 日志里确认。

status 行定不了的事，开 debug 日志。输出不打到终端，而是写进 ~/.claude/debug/<session-id>.txt：

claude --debug

日志里会有 CA certs: Appended extra certificates from NODE_EXTRA_CA_CERTS (...)、mTLS: Loaded client certificate from CLAUDE_CODE_CLIENT_CERT 这类确认行；读取失败则是一行 Failed to read 加原因。

确实存在一项启动期校验：代理 URL 在启动时会被解析，缺少 http:// 之类的写法会直接中断启动，并在报错里点名该改哪个变量。

两者同时存在时

内网网关 + 做检查的企业代理，需要两套变量同时配，而且不冲突——网关决定请求去哪，代理决定怎么到。这个组合有两点要注意。

非必要的后台流量——版本检查、遥测、发行说明——仍会离开网关路径，发往 Anthropic 与第三方主机。在只允许出口到网关的网络里，这些请求会失败并在出口监控里表现为被拦连接。与网关变量一起设 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 可以关掉它们，代价是自动更新一并停用，得另行安排更新路径。

fast mode 的可用性检查仍然请求 api.anthropic.com 而不是网关 base URL，但它会遵循已配置的 HTTP 代理——所以若原因是网络封锁，在代理里为该主机加一条放行即可。

常见问题

Claude Code 代理到底指什么？

它涵盖两件不同的事：一是 LLM 网关，负责应答模型请求，用 ANTHROPIC_BASE_URL 加凭据配置；二是流量要经过的企业 HTTP 代理，用 HTTPS_PROXY 配置。只有前者会改变你的请求最终由谁应答。

配置 Claude Code 代理要用哪些环境变量？

网关侧：ANTHROPIC_BASE_URL 加 ANTHROPIC_AUTH_TOKEN 或 ANTHROPIC_API_KEY，需要时再加 ANTHROPIC_CUSTOM_HEADERS。网络代理侧：HTTP_PROXY、HTTPS_PROXY、NO_PROXY，涉及证书时还有 NODE_EXTRA_CA_CERTS 与 CLAUDE_CODE_CLIENT_CERT 这一组。

ANTHROPIC_BASE_URL 要不要带 /v1？

不要。客户端会自己拼 /v1/messages，变量结尾再带 /v1 会得到重复路径和 404。只填到域名为止。

Claude Code 支持 SOCKS 代理吗？

不支持。文档明确写明不支持 SOCKS 代理，请改用 HTTP / HTTPS 代理，或改走网关。

代理设了却没生效，为什么？

最常见的是变量根本没传进会话：环境变量在启动时读取，运行中的会话不会捡起之后的 shell 改动；也可能是配置文件里某条小写 https_proxy 压过了你设的那条；或者值只写在 shell export 里，而后台 agent 的 supervisor 从没继承到。先跑 /status 看 Proxy 与 Anthropic base URL 两行，再动别的。

代理和网关配置能写进 settings.json 吗？

能——本文提到的每个变量都可以写进配置文件的 env 块，而且这是唯一能可靠传到后台 agent 的形式。凭据放 ~/.claude/settings.json 或不入库的 .claude/settings.local.json，绝不要放进项目里会被提交的配置文件。

ROIBest AI 在 Anthropic 兼容端点上提供 Messages API 形态，所以把 Claude Code 接过来走的就是上文路线一的配置——一个 base URL 加一个凭据，放在与你所需持久度相称的那一层。