Claude Code 的网络连接方式
Claude Code 是运行在终端中的开发工具,常见工作包括读取项目文件、分析代码结构、生成或修改代码、执行测试命令,以及在交互会话中调用远程模型服务。它与浏览器访问网页有一个重要区别:终端程序不会自动继承浏览器扩展里的代理设置,有些程序也不会读取 Clash Verge 的系统代理开关。因此,电脑浏览器能够正常打开相关服务,并不代表 Claude Code 一定可以建立连接。
在国内网络环境中使用这类终端工具时,连接失败通常不是代码本身的问题,而是请求没有进入 Clash,或者进入 Clash 后被错误地判定为直连。常见表现包括登录页面无法打开、设备授权回调超时、模型请求长时间停留在连接状态、流式输出中途断开,以及终端提示网络错误。排查时应先把问题拆成三层:Clash Verge 是否正在运行,终端是否把请求交给代理端口,规则是否把目标域名送到了可用策略组。
Clash Verge 在桌面系统上通常承担三项工作:运行 mihomo 内核,提供 HTTP、SOCKS 或 mixed-port 代理入口,以及通过系统代理或 TUN 模式接管应用流量。系统代理只对遵循操作系统代理设置的应用有效;终端里的 Node.js、Python、Git、curl 或基于 Electron 的工具,是否遵循该设置取决于它们使用的网络库。环境变量是更明确的方式,TUN 则是覆盖范围更广的兜底方案。
请确认所使用的模型服务、账号和网络方案符合当地法律法规、服务条款以及组织的安全政策。本文只讲终端代理的网络配置与故障定位,不提供绕过账号限制、地区限制或服务安全措施的方法。
准备 Clash Verge 与代理配置
开始前,先在 Clash Verge 中导入一份来源可靠的 Clash 配置或订阅,确认配置能够正常加载,并在「代理」页面看到可用节点或策略组。不同版本的 Clash Verge、Clash Verge Rev 界面名称可能略有差异,但核心概念一致:配置文件由 mihomo 内核读取,客户端只是负责下载配置、切换模式、控制系统代理与展示连接。
首先检查内核状态。Clash Verge 的状态页或托盘菜单应显示内核正在运行,日志中不能持续出现配置解析错误。若配置加载失败,先处理 YAML 缩进、策略组名称、节点参数或订阅内容问题,不要直接进入终端排查。可以在配置文件所在环境中使用 mihomo 的测试命令:
mihomo -t -d /path/to/config-directory命令中的目录应替换为实际配置目录。图形客户端通常会自行管理内核文件,普通用户不一定需要手动执行这条命令;它主要用于确认一份导出的配置在语法层面没有问题。
其次确认代理入口端口。Clash 配置中常见的端口字段如下,实际端口应以 Clash Verge 当前配置页面显示的值为准:
| 字段 | 作用 | 终端使用场景 |
|---|---|---|
mixed-port | 同时接受 HTTP 代理与 SOCKS5 请求 | 最适合给 curl、Node.js 等工具统一设置 |
port | HTTP 代理端口 | 需要 HTTP_PROXY 的程序 |
socks-port | SOCKS5 代理端口 | 支持 SOCKS5 的程序或测试命令 |
redir-port | 透明代理重定向入口 | 通常不直接填入终端环境变量 |
external-controller | 控制接口,不是普通代理端口 | 不应写入 HTTP_PROXY 或 HTTPS_PROXY |
以常见的 mixed-port 为例,假设端口是 7890,终端代理地址就是 127.0.0.1:7890。如果 Clash Verge 设置了认证信息,环境变量中的 URL 也必须带上用户名与密码;没有认证时不要凭空添加。控制接口的 9090、9097 等端口只供面板调用,把它当成代理端口会得到连接被拒绝或协议错误。
mixed-port: 7890
allow-lan: false
bind-address: 127.0.0.1
mode: rule
log-level: info在个人电脑上,终端与 Clash Verge 位于同一台设备时,监听本机回环地址已经足够,也更安全。只有当终端运行在虚拟机、容器或局域网另一台电脑中,才需要考虑 allow-lan 与监听地址。此时必须同时设置访问控制和控制接口密钥,不要为了省事把管理端口暴露给整个局域网,更不能直接映射到公网。
终端设置代理环境变量
这是最容易验证、也最适合新手的方案。它不修改 Claude Code 的项目文件,只告诉当前终端会话:访问 HTTP 或 HTTPS 资源时,先连接本机 Clash 代理。Claude Code 底层依赖的运行时或网络库是否读取这些变量,取决于具体版本;但 curl、npm、许多 Node.js 工具以及大量命令行程序都会读取它们。
Windows PowerShell 配置
在 PowerShell 中,可以先为当前窗口设置变量。下面的写法使用 mixed-port 7890,如果 Clash Verge 显示的是其他端口,请替换数字:
$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:ALL_PROXY = "socks5://127.0.0.1:7890"
$env:NO_PROXY = "localhost,127.0.0.1,::1"
curl.exe -I https://example.comHTTP_PROXY 和 HTTPS_PROXY 一般使用 HTTP 代理地址,即便目标网址是 HTTPS,也由 HTTP CONNECT 建立加密隧道。ALL_PROXY 用于某些只识别通用代理变量的程序,但 SOCKS5 支持并不统一,遇到程序行为异常时可以暂时只保留前两个变量。NO_PROXY 用来排除本机回调、局域网服务和开发服务器,避免登录回调或本地 API 被错误送入代理。
这些变量只对当前 PowerShell 窗口及其子进程有效。关闭窗口后设置会消失,这通常是好事,因为不同项目可能需要不同网络策略。若确认长期需要,可以使用系统环境变量设置,但不建议把代理地址写入项目的 .env、代码仓库或公开日志。
macOS 与 Linux Shell 配置
在 zsh、bash 或兼容 Shell 中,使用 export 写入当前会话:
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export ALL_PROXY="socks5://127.0.0.1:7890"
export NO_PROXY="localhost,127.0.0.1,::1"
curl -I https://example.com如果只希望本次启动 Claude Code 使用代理,可以把变量与命令写在同一行:
HTTP_PROXY="http://127.0.0.1:7890" \
HTTPS_PROXY="http://127.0.0.1:7890" \
NO_PROXY="localhost,127.0.0.1,::1" \
claude不同工具对变量名称的大小写处理并不完全一致。通常同时设置大写变量即可;遇到 Git、Python 或某个旧程序不认代理时,再补充小写形式。使用完后可以清理当前会话:
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY NO_PROXY若端口是 mixed-port,优先尝试 http://127.0.0.1:端口。若明确使用 SOCKS5 端口,可写 socks5:// 或 socks5h://;后者要求通过代理解析域名,但是否支持取决于调用方。把 SOCKS 端口误写成 HTTP,或把控制端口误写成代理端口,都是终端连接失败的高频原因。
动手验证:从端口到模型请求逐层检查
不要一上来反复重试 Claude Code。先用简单请求确认链路,每一步都只验证一个变量。以下步骤适用于 Windows、macOS 与 Linux,命令细节可按系统替换。
确认 Clash Verge 已启动
打开 Clash Verge 的代理页面,确认内核运行中,模式暂时设为 Rule,并选择一个可用的代理策略组。观察日志面板是否会在测试请求出现新连接。若客户端没有任何活动连接,问题多半在终端变量、端口或程序未读取代理设置。
检查本机端口
在 PowerShell 中可执行
Test-NetConnection 127.0.0.1 -Port 7890;在 macOS 或 Linux 中可执行nc -vz 127.0.0.1 7890。显示端口可达只说明有程序监听,不代表代理节点可用,但若端口拒绝连接,应回到 Clash Verge 检查端口配置。用 curl 检查代理请求
设置环境变量后执行
curl -I https://example.com。如果返回 HTTP 响应头,说明终端至少能够通过 Clash 建立 HTTPS 连接。若提示超时,查看 Clash 日志中的目标地址、策略组和错误原因;若提示代理认证失败,检查是否配置了用户名和密码。区分 DNS 与代理问题
如果日志显示连接根本没有创建,先检查环境变量;如果日志显示请求已进入但域名解析失败,再检查 Clash DNS、fake-ip 例外和上游 DNS。终端中直接执行
nslookup测到的是系统 DNS,不能单独证明 Claude Code 通过 Clash 的 DNS 工作正常。最后启动 Claude Code
保持同一个终端窗口,在变量仍然存在的情况下启动 Claude Code。先进行轻量登录或发送简单请求,不要立即让工具扫描整个大型项目。若 Claude Code 报错,记录错误发生时间,同时查看 Clash 连接列表中的域名、端口、策略组和失败原因,这样比只看终端的一行网络错误更容易定位。
测试完成后,可以用一条命令确认环境变量是否仍然存在。PowerShell 使用 Get-ChildItem Env: | Select-String PROXY,macOS 与 Linux 使用 env | grep -i proxy。如果 Claude Code 由 IDE、任务计划程序或其他图形启动器拉起,它可能不会继承你在某个 Shell 窗口里设置的变量,此时应在启动它的环境中配置,或者改用 TUN 模式。
规则分流、TUN 模式与稳定性取舍
终端代理配置成功后,还要决定哪些请求走代理。Clash Verge 的 Rule 模式会依照配置中的 rules 列表逐条匹配,第一条命中即停止。模型服务、登录服务、更新服务和遥测服务可能使用不同域名,只把一个主域名加入规则并不一定完整。更稳妥的做法是先在连接列表中观察实际请求,再把确认过的域名通过配置覆写或规则集处理。
规则的策略名称必须与配置中的代理组名称完全一致,包括大小写和空格。自定义规则应放在宽泛规则之前,而 MATCH 必须位于最后。示例中的域名仅用于说明写法,请根据实际服务域名和组织策略替换,不要把不存在的域名照抄进生产配置:
rules:
- DOMAIN-SUFFIX,example-model.invalid,Claude
- DOMAIN-SUFFIX,example-auth.invalid,Claude
- DOMAIN-SUFFIX,npmjs.org,DIRECT
- DOMAIN-SUFFIX,github.com,Claude
- MATCH,DIRECT如果终端程序完全不读取环境变量,或者它会启动多个子进程、使用原生 TLS、忽略系统代理,可以在 Clash Verge 中开启 TUN。TUN 通过虚拟网卡接管更底层的 IP 流量,覆盖面通常比系统代理更大,但也会带来更复杂的 DNS、路由和权限问题。启用前应确认系统允许创建虚拟网卡,Clash Verge 已获得必要权限,并保留关闭 TUN 后恢复网络的办法。
TUN 模式不是万能开关。某些程序使用固定 IP、QUIC、独立 DNS 或自带网络栈,仍可能需要单独配置;虚拟机、容器和 WSL 的流量也可能不在宿主机默认路由范围内。启用后若出现局域网打印机、公司内网、Git 私有地址无法访问,应优先检查 fake-ip-filter、dns-hijack、局域网网段直连规则和 NO_PROXY,而不是盲目切换节点。
| 方案 | 覆盖范围 | 优点 | 注意事项 |
|---|---|---|---|
| 系统代理 | 遵循系统设置的应用 | 开关简单,影响范围可控 | 终端程序可能完全不读取 |
| 环境变量 | 当前 Shell 及其子进程 | 明确、易撤销、便于排查 | 新开的 IDE 或服务可能不继承 |
| TUN | 更底层的系统流量 | 适合不支持代理变量的程序 | 需要权限,须处理 DNS 与局域网 |
常见故障定位与安全收尾
如果 Claude Code 仍然无法使用,可以按照「端口—变量—规则—DNS—服务」的顺序排查。首先确认代理端口没有被其他程序占用;其次确认变量指向的是本机地址而不是控制接口;再次检查 Clash 连接列表是否出现目标域名以及实际命中的策略组。若连接出现在列表中但迅速失败,问题可能是节点不可用、远端服务拒绝、TLS 握手失败或规则选择了错误出口。
终端工具常常会读取用户目录下的配置文件,也可能把请求地址、错误信息或环境变量打印到日志。不要把包含代理认证密码的命令复制到公共工单、截图或 Git 提交中。若使用带用户名和密码的代理 URL,在分享终端记录前应先脱敏。项目级配置只保存非敏感的开关和域名列表,代理凭据应放在操作系统环境变量、密码管理器或客户端安全存储中。
完成工作后,建议关闭不再需要的全局环境变量,恢复 Clash Verge 的模式与系统代理状态,并检查本地服务是否仍能直连。对于长期使用场景,可以保留一个专用的 Shell 启动脚本,脚本中只设置本地代理地址和必要的 NO_PROXY 范围,不要把节点订阅、控制接口密钥或账号令牌写入其中。这样既能让 Claude Code 通过稳定的终端链路工作,也能避免代理设置无意间影响浏览器、数据库客户端和其他开发服务。