2026年Claude Code 使用代理完整指南：3套配置命令与3步验收法

摘要：Claude Code 使用代理的核心路径是把 HTTP 代理地址写进环境变量或 settings.json 的 env 块，经 /status、实际请求、连接日志三步验收。

• 命令可复制：macOS/Linux 用 export，PowerShell 用 $env，settings.json 合并不覆盖，端口换本机实际 HTTP 端口。
• 验收三步缺一不可：/status 确认地址、简短请求有完整回答、日志有目标连接。
• 版本有边界：2.1.222 修复 https:// 代理启动检查，2.1.310 证书恢复属使用侧观察，OAuth 刷新失败是独立路径。

适用人群：终端或 IDE 中使用 Claude Code、需稳定出口的开发者团队。

Claude Code 使用代理这件事，多数经验内容停在「export 两个变量」这一步，真正卡人的地方往往在验收环节：变量写了、终端能回显，Claude Code 发出的请求却照旧直连。本文按「可复制命令 → 三步验收 → 边界对照」组织：给出 macOS/Linux、Windows PowerShell 与 settings.json 三套写法，讲清变量优先级、NO_PROXY 与多运行环境的差异，再说明 2.1.222 与 2.1.310 两个版本修复的适用范围，以及证书错误的正确处理方式。

与只讲原则的配置建议不同，本文每条命令都标注了生效范围与对应的验证方式，照做的同时也能知道每一步在验证什么。文中的端口均为示例，使用时请替换为本机实际的 HTTP 监听端口。

一、分清三种「代理」：网络代理、模型网关与任务代理

「代理」一词至少有三层含义，混用是多数配置失败的源头。第一层是 HTTP/HTTPS 网络代理，通过 HTTPS_PROXY、HTTP_PROXY、NO_PROXY 环境变量生效，本文主线只处理这一层。第二层是模型网关，即 ANTHROPIC_BASE_URL，它改变模型请求的目标地址，是另一类配置，既不是网络代理，也不是配置网络代理的必填项。第三层是任务层面的子代理，与网络链路无关。

官方文档明确不支持直接配置 SOCKS 代理，部分沙箱设置里的 socksProxyPort 也不是给模型 API 配置 SOCKS 的等价入口。本地工具若只提供 SOCKS 监听，应改用其实际支持的 HTTP 或 mixed 入口。

理清层级能避免两类典型弯路：把模型网关地址当成代理地址填入，或对着任务代理的设置项排查网络连通。网络代理的排查只围绕「地址是否写对、是否被读取、流量是否经过」三件事展开，其余层级各有独立的验证入口。同主题的系统性说明，也可对照Claude 网络指南。

二、Claude Code 代理设置：三套可直接复制的配置命令

Claude Code 设置 HTTP 代理最直接的做法是在启动 Claude Code 的同一个终端设置变量，macOS/Linux 用 export：

export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
claude --debug

Windows PowerShell 仅对当前终端及其子进程生效：

$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
claude --debug

有两个细节容易被误解。其一，HTTPS_PROXY 的变量名指它作用于 HTTPS 请求，不要求值以 https:// 开头：HTTP CONNECT 监听器填 http://，真正 TLS 代理才用 https://。其二，7890 只是示例端口，须换成本机实际 HTTP 或 mixed 监听端口，填错通常表现为连接拒绝。

长期生效写入 ~/.claude/settings.json 的 env 块：在现有 JSON 新增 env 字段并保留原内容，合并不覆盖，勿整文件替换。

{
  "env": {
    "HTTP_PROXY": "http://127.0.0.1:7890",
    "HTTPS_PROXY": "http://127.0.0.1:7890"
  }
}

前台 shell 变量在启动时读取，改动后新开会话验证；settings.json 适合后台或跨终端场景。settings 不生效而终端 export 有效时，对照所用版本与启动环境核查。

IPdodo长期服务 AI 开发团队的跨境网络接入，静态住宅IP资源按归属地与运营商逐项核验，适合需要固定出口的长期任务场景。

三、Claude Code 代理配好了怎么算生效：三步验收法

走完 Claude Code proxy 配置 的命令，「配好了」需要三条独立证据，缺一不可。第一步，在交互会话中运行 /status，确认 Proxy 一栏显示预期地址——这只能证明配置被读取，是配置证据，不能单独证明请求成功。第二步，发出一个简短的实际请求，收到内容完整的回答，证明模型链路真正走通。第三步，到代理软件的连接日志里，确认出现指向模型服务域名的目标连接记录，证明流量确实经由代理出口。

两个常见误判需要避开。claude –version 只输出版本号，不验证模型 API；对根域请求拿到 HTTP 响应，也只说明网络层可达，不等于 Claude Code 的模型请求恢复。登录与刷新类问题另有独立认证链路，需在对应域名上单独验证，不能与模型请求混为一谈。

三步证据按顺序收集，每步缺失都对应不同方向：地址不对回查变量名与拼写，请求失败回查版本与证书，日志无记录回查运行环境与 NO_PROXY。

如果你前面已经在国内长期使用过 Claude Code，已发布的 国内使用 Claude Code 怎么更稳 也值得一起补上。那篇更偏安装和登录，这篇重点放在代理和长期调用链路。

四、变量优先级、NO_PROXY 与多运行环境的 127.0.0.1 边界

机器上可能同时存在多份代理变量，官方选取顺序是 https_proxy → HTTPS_PROXY → http_proxy → HTTP_PROXY，取首个已设置的值。大小写变量可能同时存在的环境要格外留意，Windows 环境变量通常不区分大小写，不能机械照搬多值写法；改动只针对确认不再需要的残留值，不要把包含账号密码的变量值贴到任何公开位置。

NO_PROXY 是反向规则：目标地址命中匹配项会绕过代理，NO_PROXY=”*” 则全部绕过。诊断时只处理误匹配相关服务的条目，不要顺手清空企业内网所需的排除项。

配置范围按入口区分：Claude Desktop 管理的会话只读取 managed settings 与用户级 ~/.claude/settings.json，不读取仓库级网络变量；后台 agents 由共享 supervisor 启动，可能沿用首次启动时的终端环境，网络变量应放进用户级或 managed settings，而非依赖某次临时 export。在 VSCode、WSL 或容器中，127.0.0.1 指向该环境本身，能否访问宿主代理需实测。

这解释了「终端有效、IDE 无效」的常见现象：两边读取的变量来源不是同一份。

五、Claude Code 版本差异与证书错误：2.1.222 与 2.1.310 的修复边界

2.1.222 更新日志明确修复了 https:// 代理下的启动检查（Checking connectivity）失败：旧版应升级后再对照，而非认为工具不支持 HTTPS 代理。2.1.310 有多位使用者证书恢复记录，但更新日志未列对应条目，属使用侧观察而非官方承诺。

证书错误通用处理路径：管理员提供可信 CA 文件，启动前设置 NODE_EXTRA_CA_CERTS，以 debug 日志显示 CA 已加载、原请求恢复为准。NODE_TLS_REJECT_UNAUTHORIZED=0 与 curl -k 不作通用办法。

export NODE_EXTRA_CA_CERTS="/path/to/approved-ca.pem"
claude --debug

OAuth 刷新失败是独立路径：api.anthropic.com 连通时，platform.claude.com 的 oauth 刷新仍可能失败，不能用启动检查修复覆盖。直接入口含 api.anthropic.com、claude.ai、claude.com、platform.claude.com，SSO 另涉 sso.claude.com，账号风险见Claude 账号风险指南。

核对无误仍复现差异时，固定账号与请求，在两条获准路径对照，每次只改一个变量。一条路径成功只说明路径相关；确需稳定出口的团队，固定出口的静态住宅IP才有对照意义。

六、Claude Code 代理配置常见问题

Claude Code 支持直接配置 SOCKS5 代理吗？

官方不支持直接配置 SOCKS，用本地工具实际的 HTTP 或 mixed 监听端口填入 HTTP_PROXY 与 HTTPS_PROXY。

/status 已显示代理地址，为什么请求还是失败？

/status 只是配置被读取的证据，不能单独证明请求成功。还需发出简短请求收到完整回答，并在代理连接日志看到目标连接；仍失败时对照版本、证书与 OAuth 刷新链路。

HTTPS_PROXY 的值为什么可以写成 http:// 开头？

变量名表示它作用于 HTTPS 请求，值取决于监听器：HTTP CONNECT 填 http://，真正的 TLS 代理才用 https://。

settings.json 里写了代理为什么不生效？

常见原因有四类：整文件覆盖丢了原有配置、有优先级更高的同名残留变量、运行环境读不到该文件（Desktop 会话只读 managed settings 与用户级 settings.json），或 127.0.0.1 在 WSL、容器中指错环境。

更新到 2.1.310 后证书错误就解决了吗？

该版本有多位使用者证书错误恢复记录，但更新日志未列对应条目，属使用侧观察而非官方承诺。稳妥做法是更新到受支持版本对照，证书错误仍按 NODE_EXTRA_CA_CERTS 处理。

相关文章推荐

	Claude Code Connection refused怎么办？2026年curl正常却连不上API的6步排查
	Claude Code报错Connection closed mid-response怎么办？2026解决指南
	Claude Code ECONNRESET怎么办？2026年按路径分流的6步排查与恢复

总结

Claude Code 使用代理的完整链路：分清代理类型，用三套命令写对地址，按 /status、实际请求、连接日志三步验收，再对照版本与证书边界处理残留问题。变量优先级、多运行环境与版本边界，决定配置能否被读取、哪些报错该升级，需要对照资源的开发者可注册IPdodo海外AI网络。