故障排查 预计阅读 9 分钟

Claude Code国内使用遇到连接问题？用Clash Verge配置终端代理

使用 Claude Code 时遇到登录失败或终端请求超时？本文整理 Clash Verge 的基础设置与排查步骤，带你检查代理模式、规则、DNS 和终端环境变量，找到更适合 Claude Code 的连接方案。服务可用性仍受地区政策、账号资格和网络环境影响。

先判断连接问题出在哪一层

Claude Code 登录失败或请求超时，不一定是 Clash Verge 没有代理。终端程序不会必然跟随浏览器代理设置；即使浏览器能打开网页，命令行也可能仍在直连。排查时先区分客户端是否运行、代理端口是否监听、终端是否使用该端口，以及当前规则是否把目标请求送往预期的策略组。

Claude Code 的认证、网页登录和模型请求可能涉及不同的服务域名与连接阶段。登录回调成功，不代表后续 API 请求一定可用；终端出现超时，也不等于账号或订阅配置错误。服务可用性还会受到地区政策、账号资格和网络环境影响。请遵守适用的服务条款与当地规定，不要把代理配置视为访问资格或服务可用性的保证。

现象 优先检查 暂时不要推断
浏览器可以访问，CLI 超时 终端代理环境变量、端口、规则命中 不代表账号认证已经完成
ECONNREFUSED 或连接被拒绝 Clash Verge 是否运行、监听地址与端口 不一定是远端服务拒绝连接
ENOTFOUND 或解析失败 DNS、当前网络与代理解析路径 不等同于节点延迟高
登录完成后 API 请求失败 请求域名的规则、所选节点、账号与服务状态 不一定需要重新安装 CLI
401、403 等 HTTP 状态 账号资格、认证状态、服务返回内容 不应只靠更换代理端口处理

开始前记下 Clash Verge 和内核版本、运行模式、当前配置名称、混合端口及报错时间。分享日志前删除账号标识、令牌、代理订阅地址和请求正文；不要把含认证信息的终端输出粘贴到公开场所。

在 Clash Verge 确认本地代理

先启动 Clash Verge，并确认已选择有效配置、内核正常运行。客户端版本不同，设置入口名称可能略有变化；通常可在设置或端口配置区域查看 HTTP、SOCKS 或混合端口，也可以在连接页面观察请求。本文用 7890 举例，它只是常见值，不保证与你当前配置相同。

  1. 在 Clash Verge 的设置中查看实际监听端口，确认端口未被其他程序占用。
  2. 确认系统代理已开启，或记下本地代理地址和端口，以便之后在终端显式设置。终端变量方式不要求开启 TUN。
  3. 检查运行模式。规则模式会根据域名、IP 和规则集选择出站；全局模式则通常让请求统一经过指定策略。切换模式只用于对照测试，测试后应恢复原设置。
  4. 打开连接记录或日志，准备在发起测试后核对请求是否到达内核、命中了哪条规则以及使用了哪个策略组。

若配置使用 mixed-port，该端口可接收 HTTP 与 SOCKS 代理请求。终端变量的写法应与所选协议相符。对基于 Node.js 的命令行工具，建议先用本地 HTTP 代理进行可重复测试；不要默认所有程序都会读取系统代理设置或支持 SOCKS 环境变量。

设置终端代理并完成对照测试

先用显式代理变量启动一个新的终端会话，再测试请求。下面以 macOS、Linux 常见的 Bash 或 Zsh 为例，假设 Clash Verge 的 HTTP 混合端口实际为 7890。若客户端显示其他端口，必须替换命令中的端口。

export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export NO_PROXY="localhost,127.0.0.1,::1"
export no_proxy="$NO_PROXY"

# 检查当前终端中的代理变量
env | grep -iE '^(http_proxy|https_proxy|no_proxy)='

HTTP 代理地址可用于 HTTPS 目标：客户端通过 HTTP CONNECT 建立隧道，TLS 仍由终端程序与目标服务完成。这里不是把 HTTPS 请求内容明文发送给代理，也不需要安装陌生根证书。NO_PROXY 保留本机回环地址，避免本地登录回调被错误转发；如果已有自己的绕过列表，应合并而不是覆盖。

先做一般连通性测试，再按实际需要测试 Claude Code 相关域名。以下命令只能证明代理路径获得了 HTTP 响应，不能验证账号、地区资格或完整 CLI 工作流：

curl -Iv --connect-timeout 10 --max-time 20 \
  --proxy http://127.0.0.1:7890 \
  https://api.anthropic.com/

# Windows PowerShell 使用 curl.exe，避免命令别名差异
curl.exe -Iv --connect-timeout 10 --max-time 20 `
  --proxy http://127.0.0.1:7890 `
  https://api.anthropic.com/

如果收到 HTTP 状态码，通常表示 DNS、代理连接和 TLS 至少已经推进到服务器响应阶段；根路径返回错误状态也不等同于代理故障。若命令在连接本地地址时立即被拒绝，先核对端口和客户端运行状态。若 TLS 或域名解析失败，再查看 Clash Verge 日志及所选网络路径。测试不需要提交 API 请求，也不要在命令行中写入 API 密钥。

Windows PowerShell 可在当前窗口设置进程级变量，关闭窗口后通常不会保留：

$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:http_proxy = $env:HTTP_PROXY
$env:https_proxy = $env:HTTPS_PROXY
$env:NO_PROXY = "localhost,127.0.0.1,::1"
$env:no_proxy = $env:NO_PROXY

变量设置后，必须从这个终端窗口启动 Claude Code，已经运行的进程不会自动读取后来新增的环境变量。完成测试后，可在 macOS 或 Linux 执行 unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy NO_PROXY no_proxy；PowerShell 可用 Remove-Item Env:HTTP_PROXY,Env:HTTPS_PROXY,Env:http_proxy,Env:https_proxy,Env:NO_PROXY,Env:no_proxy -ErrorAction SilentlyContinue 清除当前会话中的变量。

检查规则模式、策略组与 DNS

显式设置代理只负责让终端连接本地端口，不会自动决定远端出口。Clash Verge 处于规则模式时，目标域名仍会按当前配置匹配规则。启动 CLI 并触发一次请求后，查看连接页里的域名、匹配规则、策略组和出站节点；如果请求显示为 DIRECT，说明终端确实连接到了本地代理，但该请求最终仍被规则安排为直连。

  • 规则命中直连：先确认域名与规则集是否匹配，再检查配置的规则顺序和策略组选择。若需要修改规则，优先使用客户端支持的覆写或合并功能，避免直接改动会被订阅更新覆盖的原始配置。
  • 策略组没有可用节点：在客户端手动选择一个已确认可用的候选节点，重试同一测试。一次只改变一个条件，避免同时换模式、节点和 DNS。
  • DNS 解析失败或结果异常：检查内核 DNS 设置、当前网络解析情况与域名规则。启用 TUN 可能改变 DNS 和路由路径，但不是终端代理的必需条件，也不应作为所有错误的通用修复。
  • 登录回调卡住：确认 localhost、127.0.0.1 没有被代理变量绕过列表删除；终端访问外部服务需要代理，并不代表本机回调地址也应该经由远端节点。

DNS、规则和终端代理是不同环节。能解析域名不代表连接已代理；能连接本地端口也不代表选中了可用出站。借助 Clash Verge 的连接记录，将终端报错时间与对应域名对上，通常比直接更换整份配置更容易定位原因。

按现象逐项缩小故障范围

连接本地端口失败

出现 ECONNREFUSED 时，检查 Clash Verge 是否仍在运行、实际端口是否与环境变量一致，以及端口是否只监听在本机可访问的地址。不要把控制面板端口误当成 HTTP 或混合代理端口。若端口配置被修改，重新打开终端核对变量后再测。

代理路径建立但请求超时

在连接记录里查找目标域名。如果完全没有对应记录，CLI 可能没有读取变量、请求走了其他网络路径，或尚未发起到该服务的连接。如果记录存在但出站超时，尝试在规则允许的前提下手动选择另一个节点，并保持其他设置不变。不要因一次超时就判断订阅、DNS 和账号同时故障。

返回认证或服务错误

收到 401 或 403 时，先区分请求是否已经到达服务端，再检查 CLI 的登录状态、账号资格、服务返回信息及适用政策。代理更换不会自动修复无效凭据或不符合服务条件的账号。避免把令牌写进共享终端、截图、脚本仓库或公开日志；怀疑凭据泄露时按服务方提供的流程撤销或更新。

恢复到可控的日常配置

问题解决后，保留必要的终端代理变量即可，不必为了单个 CLI 一定启用 TUN 或全局模式。若希望每次打开终端都自动设置变量，可将配置写入个人 Shell 启动文件，但先确认这不会影响其他命令行程序；需要临时直连时，应在单独会话中移除变量并核对运行模式。长期使用前用一轮简单检查确认：客户端在线、端口正确、规则命中符合预期，且本地回环地址仍在绕过列表中。

如果仍无法定位，整理客户端与内核版本、操作系统、错误代码、失败时间、端口配置和脱敏后的连接记录，再逐项复现。不要发送订阅链接、完整认证日志或密钥。需要安装或重新选择客户端时，可前往下载；首次配置可查看教程。

下载Clash