Claude Code 如何设置代理(HTTP_PROXY)?

文章导读
先说明一个前提:Claude Code 本身不提供图形化的代理开关,它读取的是系统环境变量。也就是说,代理配置是启动进程之前就要决定好的事,进入交互界面之后再改环境变量,通常不会对已经建立的连接生效。所以下面讲的都是启动前的设置方式,以及设置后怎么确认真的走通了代理。
📋 目录
  1. 一 先判断你的网络场景
  2. 二 最直接的设置方式:环境变量
  3. 三 临时生效还是永久生效
  4. 四 改完后看这几个信号
  5. 五 常见坑:认证、NO_PROXY 和证书
  6. 六 回滚和边界
A A

先说明一个前提:Claude Code 本身不提供图形化的代理开关,它读取的是系统环境变量。也就是说,代理配置是启动进程之前就要决定好的事,进入交互界面之后再改环境变量,通常不会对已经建立的连接生效。所以下面讲的都是启动前的设置方式,以及设置后怎么确认真的走通了代理。

先判断你的网络场景

需要代理,一般有两种情形。一种是本机有可用的 HTTP 代理端口,比如某个调试工具监听在 127.0.0.1:8080,你只需要把 Claude Code 的请求引到这个端口。另一种是公司内网环境,代理地址可能是网关或专门的服务端口,并且可能带有身份认证。两种场景的处理路径差不多,但第二种要额外注意证书和 NO_PROXY 问题,后文会说。

还有一点需要先确认:你用的代理是否支持 HTTPS 转发。Claude Code 的 API 请求基本都是 HTTPS,而代理如果只做普通 HTTP 转发,TLS 握手阶段就会出问题。如果拿不准,先用一个简单的测试命令来确定代理本身可用,再看 Claude Code。

最直接的设置方式:环境变量

在 Claude Code 中设置代理,最直接的方式是使用环境变量。在启动 Claude Code 之前,在终端执行 export HTTP_PROXY=http://127.0.0.1:8080(以及 HTTPS_PROXY),这样 Claude Code 发往后端 API 的请求就会走该代理。需要注意,程序读取代理时通常既看大写也看小写,但为了兼容,建议把 http_proxy 和 https_proxy 也一并设置。设置后不要忘了用 echo $HTTP_PROXY 确认变量已生效。

执行 export 之后,直接在当前终端运行 claude,这个进程以及它发起的子进程都会带着这几个环境变量。这里有个容易忽略的细节:导出变量是区分大小写的,某些程序只会读小写,某些只读大写,所以四条都写上更稳妥。另外,如果之前已经启动过 Claude Code,那么新开终端再设置即可,不需要重启电脑。

临时生效还是永久生效

如果希望代理配置在每次终端启动时都自动生效,可以将 export 命令写入 shell 的初始化文件。例如在 ~/.zshrc 或 ~/.bashrc 末尾追加两行。但这种方式会让代理全局生效,如果只在某个项目中使用 Claude Code,可能造成其他命令也被代理干扰。更好的做法是在需要时临时设置:在终端中使用 env HTTP_PROXY=... HTTPS_PROXY=... claude 命令启动,只对这一次运行有效。

如果只是偶尔用一次,env 前缀方式最干净,不会污染当前 shell 的后续命令。写进 shell 配置文件则适合那些长期需要代理的环境,但要注意新开的终端窗口才会加载新配置,已经在运行的终端需要手动 source 或重开。

改完后看这几个信号

设置代理后,不要立刻假设成功。先执行 curl -x http://127.0.0.1:8080 https://api.anthropic.com/v1/ -I 看看返回状态码。如果代理正常工作,curl 应该得到 200 或 403 等实际响应,而不是超时。同时可以设置 DEBUG=1 启动 Claude Code,观察日志中请求是否经过代理。注意,调试输出可能很冗长,建议先进行小规模请求验证。

还有一个观察点:Claude Code 的启动阶段可能有一些本地请求,比如检查更新或读取本地模型列表。如果代理设置不当,这些请求会变慢甚至失败。所以你还需要确认 NO_PROXY 是否覆盖了本地地址,否则很容易出现“代理通了但服务更不稳定”的现象。

常见坑:认证、NO_PROXY 和证书

常见的坑之一是代理 URL 中带有用户名密码,例如 http://user:password@proxy:8080。如果密码包含 @ 或 :,需要对这些字符进行 URL 编码,否则解析会出错。另一个坑是忘记设置 NO_PROXY,导致本应直连的本地服务也走了代理,从而连接失败。建议在 NO_PROXY 中至少包含 localhost、127.0.0.1 以及内网地址。还有,如果代理只支持 HTTP 转发,那么 HTTPS 流量可能会失败,需要先确认代理类型。

公司代理经常会出现证书问题。代理服务器为了审计,可能会用自签证书替换远端证书,此时 Claude Code 会因证书校验失败而拒绝连接。可以先用 curl 看看它是否接受证书,再决定是调整代理策略还是信任对应 CA。最不建议做的是一把关掉证书验证,那等于让请求在裸奔。如果只是开发环境临时用,可以保留验证但手动加入 CA;如果是经常要用的环境,请让网络管理员提供一个不做中间人解密或提供可信证书的代理入口。

回滚和边界

配置代理之后要保留一条明确的回滚路径。最简单的是记住你改过哪些文件:如果是 export 临时设置,关掉终端就自然回滚;如果写进了 ~/.zshrc 或 ~/.bashrc,删除对应行或注释掉即可。回滚后同样用 curl 验证直连是否恢复正常。

使用代理时,务必清楚流量经过第三方服务器。对于敏感的代码或私有仓库内容,如果代理服务不可信,可能导致数据泄露风险。另外,某些公司代理会拦截或篡改 HTTPS 证书,此时 Claude Code 可能因证书校验失败而拒绝连接。解决方案是确保代理没有做中间人解密,或者将代理的 CA 证书加入系统信任链。不要为了绕过证书问题直接关闭验证,那样会明显降低连接安全性。

如果试了以上方法仍然不通,不要急着换不同的代理工具,先检查代理软件本身是否只监听了 IPv6 或只支持某些协议。可以重启代理服务,再按顺序检查:环境变量是否被正确读取、代理端口是否可通、curl 测试是否成功、DEBUG 日志中请求目标地址是否符合预期。 Claude Code 本身没有内建的“代理自检”功能,所以每一步都要靠外部命令来确认。