Claude Code 网络连接指南:代理设置、TUN 模式与常见报错
浏览器能用 Claude,Claude Code 却一直超时?九成情况是终端没有走代理。本文给出三种配置方法,并说明如何区分网络问题与账号、服务端问题。
核心结论
- Claude Code 支持标准的
HTTPS_PROXY/HTTP_PROXY/NO_PROXY环境变量。 - 想长期生效,可以把环境变量写入 Claude Code 的
settings.json的env字段,或写入 shell 配置文件。 - TUN 模式无需单独配置,并且对 Claude Code 调用的其他命令(如 npm、git)同样生效。
429、529等错误不是网络问题,换节点无效。
- 确认代理端口在代理客户端设置中找到 HTTP / 混合代理端口,例如 Clash Verge Rev 默认的混合端口。
- 设置环境变量在终端中设置 HTTPS_PROXY 与 HTTP_PROXY 指向本地代理端口,并把 localhost 加入 NO_PROXY。
- 启动并验证运行 claude,发送一条简单消息,确认可以正常收到回复。
- 设置长期生效将环境变量写入 settings.json 的 env 字段,或改用 TUN 模式。
为什么 Claude Code 需要单独设置代理
Claude Code 运行在终端里。Windows「设置 → 网络 → 代理」和 macOS「系统设置 → 网络 → 代理」里配置的系统代理,主要是给浏览器这类图形应用读取的。大多数命令行程序不会主动读取它,于是请求直接从本地网络发出,表现为长时间无响应后超时。
解决方法有三种,按推荐程度排列:
| 方法 | 优点 | 缺点 |
|---|---|---|
| TUN 模式 | 一次开启,所有程序生效 | 需要管理员权限或安装服务 |
| settings.json 的 env | 只影响 Claude Code,长期生效 | Claude Code 调用的子命令不一定继承 |
| 终端环境变量 | 简单直接 | 每个新终端都要重新设置(除非写入配置文件) |
方法一:终端环境变量
首先在代理客户端里找到本地 HTTP 或混合代理端口。Clash Verge Rev 在「设置 → Clash 设置」中可以看到端口号,下文以 7897 为例,请替换为你的实际端口。
macOS / Linux(bash、zsh):
export HTTPS_PROXY=http://127.0.0.1:7897
export HTTP_PROXY=http://127.0.0.1:7897
export NO_PROXY=localhost,127.0.0.1
claude
Windows PowerShell:
$env:HTTPS_PROXY = "http://127.0.0.1:7897"
$env:HTTP_PROXY = "http://127.0.0.1:7897"
$env:NO_PROXY = "localhost,127.0.0.1"
claude
Windows CMD:
set HTTPS_PROXY=http://127.0.0.1:7897
set HTTP_PROXY=http://127.0.0.1:7897
claude
这些设置只在当前终端窗口有效。想要每次打开终端都自动生效,可以把 export 语句写入 ~/.zshrc 或 ~/.bashrc;Windows 可以写入 PowerShell 的 $PROFILE。
方法二:写入 Claude Code 的 settings.json
Claude Code 的设置文件支持 env 字段,用于为 Claude Code 会话设置环境变量。用户级设置文件位于 ~/.claude/settings.json(Windows 为用户目录下的 .claude\settings.json):
{
"env": {
"HTTPS_PROXY": "http://127.0.0.1:7897",
"HTTP_PROXY": "http://127.0.0.1:7897",
"NO_PROXY": "localhost,127.0.0.1"
}
}
这样做的好处是只影响 Claude Code,不改变其他程序的行为。具体字段以官方设置文档为准。
方法三:TUN 模式
在 Clash Verge Rev 中打开「虚拟网卡模式(TUN)」后,客户端会创建一张虚拟网卡接管系统流量,所有程序都会按规则分流,不需要再设置环境变量。
TUN 模式特别适合 Claude Code,因为它在工作中经常调用其他命令,例如 npm install、git clone、pip install,这些命令同样需要访问境外资源。详细步骤见 为终端 AI 工具配置代理。
环境变量与 TUN 模式不要同时混用不同的设置,否则排查问题时很难判断流量实际走了哪条路径。
验证配置是否生效
在同一个终端窗口中,用 curl 测试能否通过代理访问 Anthropic API:
curl -I https://api.anthropic.com
能收到 HTTP 响应头(即使是 401 或 404 这类状态码)就说明网络已经打通;如果长时间无响应或超时,说明请求没有经过代理,或者节点不可用。
常见报错与判断
| 报错或现象 | 类型 | 处理 |
|---|---|---|
| 长时间无响应后超时 | 网络(未走代理) | 按上文设置代理 |
ECONNRESET、Connection error |
网络(连接被重置) | 换节点,关闭自动切换,避开不稳定线路 |
| 回复中途停止 | 网络(长连接中断) | 固定稳定节点,参考 AI 工具连接超时诊断 |
| 证书相关错误 | 本地环境 | 检查系统时间;企业网络参考官方证书配置说明 |
429 |
用量限制 | 等待额度重置,与网络无关 |
529 overloaded |
服务端繁忙 | 稍后重试,查看 status.anthropic.com |
| 地区不受支持类提示 | 落地地区 | 更换为官方支持地区的节点 |
更系统的排查流程见 Claude 连接失败怎么办。
让长任务更稳定的小建议
- 固定节点:为 Anthropic 相关域名设置手动选择的策略组,不使用自动测速切换。
- 避开晚高峰波动大的线路:如果晚上频繁中断,换到专线或稳定性评分更高的节点。
- 留意任务规模:特别大的任务可以拆成几步,减少单次请求失败的影响。
选择适合 Claude Code 的网络服务,见 Claude 稳定机场 专题。
常见问题
Claude Code 会自动使用 Windows 或 macOS 的系统代理吗?
一般不会。系统代理主要被浏览器等图形应用读取,命令行程序通常需要通过环境变量或 TUN 模式才能走代理。
设置了 HTTPS_PROXY 还是连不上怎么办?
先确认端口号正确、代理客户端正在运行;再用 curl 测试同一代理能否访问 api.anthropic.com;如果 curl 也失败,问题在节点或规则;如果 curl 成功而 Claude Code 失败,检查是否在另一个终端窗口设置的变量。
公司网络有自己的代理和证书,Claude Code 怎么设置?
官方文档提供了企业代理配置说明,包括代理环境变量和自定义 CA 证书的设置方法。请参考 Anthropic 官方的企业网络配置文档,并遵守公司 IT 政策。