AI工具指南Claude Code 使用指南

Claude Code 网络连接指南:代理设置、TUN 模式与常见报错

浏览器能用 Claude,Claude Code 却一直超时?九成情况是终端没有走代理。本文给出三种配置方法,并说明如何区分网络问题与账号、服务端问题。

作者:机场博客编辑部发布:更新:约 3 分钟阅读

Claude Code 使用指南

核心结论

  • Claude Code 支持标准的 HTTPS_PROXY / HTTP_PROXY / NO_PROXY 环境变量。
  • 想长期生效,可以把环境变量写入 Claude Code 的 settings.json 的 env 字段,或写入 shell 配置文件。
  • TUN 模式无需单独配置,并且对 Claude Code 调用的其他命令(如 npm、git)同样生效。
  • 429、529 等错误不是网络问题,换节点无效。

步骤概览

预计用时:10 分钟需要:Claude Code、Clash Verge Rev 或其他代理客户端
  1. 确认代理端口在代理客户端设置中找到 HTTP / 混合代理端口,例如 Clash Verge Rev 默认的混合端口。
  2. 设置环境变量在终端中设置 HTTPS_PROXY 与 HTTP_PROXY 指向本地代理端口,并把 localhost 加入 NO_PROXY。
  3. 启动并验证运行 claude,发送一条简单消息,确认可以正常收到回复。
  4. 设置长期生效将环境变量写入 settings.json 的 env 字段,或改用 TUN 模式。

为什么 Claude Code 需要单独设置代理

Claude Code 运行在终端里。Windows「设置 → 网络 → 代理」和 macOS「系统设置 → 网络 → 代理」里配置的系统代理,主要是给浏览器这类图形应用读取的。大多数命令行程序不会主动读取它,于是请求直接从本地网络发出,表现为长时间无响应后超时。

终端 AI 工具与系统代理的关系

解决方法有三种,按推荐程度排列:

方法 优点 缺点
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 政策。

资料来源与数据性质

返回上级专题Claude 稳定机场怎么选Claude 网页版长回复与 Claude Code 终端任务对网络的要求、常见连接错误的成因,以及选择 Claude 稳定机场时应重点比较的指标。