为什么 Claude Code 需要单独设置代理
很多人第一次使用 Claude Code 时会遇到这样的情况:浏览器里 Claude 网页一切正常,终端里运行 Claude Code 却提示连接失败。原因在于大多数代理客户端默认使用系统代理模式,而系统代理只对浏览器等主动读取系统设置的程序生效,终端里的命令行程序通常不会自动使用。
因此,Claude Code 能否使用取决于两件事:一是节点出口 IP 在 Anthropic 支持的地区内(中国大陆和香港不在其中),二是终端流量确实经过了这个节点。前者看机场,后者看本机设置。
让终端走代理的两种方式
方式一:设置环境变量。 Claude Code 支持读取标准的代理环境变量。在 macOS 或 Linux 的终端中执行:
export HTTPS_PROXY=http://127.0.0.1:7897
export HTTP_PROXY=http://127.0.0.1:7897
Windows PowerShell 中可以使用:
$env:HTTPS_PROXY="http://127.0.0.1:7897"
示例中的 7897 只是演示端口,需要换成你的代理客户端实际使用的 HTTP 或混合端口,可在客户端设置页查看。这种方式只对当前终端窗口生效,想长期生效可以写入 shell 配置文件。需要注意,如果你的项目里还有访问内网或本地服务的请求,可以通过 NO_PROXY 排除。
方式二:开启 TUN 模式。 TUN 模式会在系统层面接管网络流量,终端、IDE、后台进程都会经过代理,无需逐个程序配置。它的优点是一次设置、全局生效,适合同时使用多种开发工具的用户。不同客户端开启 TUN 的方法可参考 Clash Verge Rev 教程。
两种方式选一种即可。环境变量更可控,TUN 模式更省心;如果设置了环境变量仍然连不上,用 TUN 模式测试一下,可以快速判断是不是代理没有生效。
安装阶段的网络问题
使用 npm 安装 Claude Code 时,下载依赖同样需要网络。如果安装缓慢或超时,可以为 npm 单独设置代理:
npm config set proxy http://127.0.0.1:7897
npm config set https-proxy http://127.0.0.1:7897
也可以开启 TUN 模式后直接安装。安装完成后如果不希望 npm 一直走代理,可以用 npm config delete proxy 和 npm config delete https-proxy 恢复。官方也提供了其他安装方式,具体以 Anthropic 官方文档为准。
登录阶段同样要注意:Claude Code 会打开浏览器完成授权,但最终换取凭据的请求由终端发出,终端没有走代理就会一直停在等待状态。
长连接与流式输出对节点的要求
和网页对话相比,Claude Code 的网络负载有几个特点:
| 特点 |
对节点的要求 |
| 回答以流式方式持续输出 |
连接需要稳定保持数十秒到数分钟 |
| 一个任务包含多轮连续请求 |
中间任何一次失败都会打断任务 |
| 会读取和上传较多代码上下文 |
上行带宽和稳定性同样重要 |
| 常在后台长时间运行 |
节点不能频繁切换或掉线 |
因此选 Claude Code 节点时,IP 的稳定性和线路质量比峰值速度更重要。建议在客户端中为 Anthropic 相关域名指定一个固定节点,关闭按延迟自动切换,并避免电脑休眠时断网。经常需要长时间运行任务的用户,可以优先考虑线路更稳定的专线机场,具体支持情况见上方支持矩阵。
快速排查清单
遇到 Claude Code 连接问题时,可以按顺序确认:先在同一个终端里用 curl 访问一个境外网站,判断终端是否真的走了代理;再查看代理客户端的连接日志,确认请求命中的是哪个节点、出口在哪个地区;最后检查是否有公司网络、安全软件或其他 VPN 同时接管流量,造成代理链路冲突。三步都没问题仍然报错,再考虑更换节点。
如果你同时使用 OpenAI 的命令行工具,设置思路基本相同,可参考 Codex 机场。