入门指南 预计阅读 9 分钟

Claude Code 国内连接不稳定？用 Clash Verge 配好终端代理

使用 Claude Code 编程时遇到终端连接超时或登录失败？了解如何通过 Clash Verge 配置终端代理、检查代理变量并选择合适的规则与线路，让网络排查更清晰，减少反复试错。

先分清终端、代理与登录环节

Claude Code 在终端里连接超时或登录失败，不一定是客户端配置出了问题。请求可能没有进入 Clash Verge、本机代理端口填错、规则把目标域名送到直连出口，也可能是所选节点无法连接目标服务。浏览器能打开网页，也不能证明终端程序使用了同一条代理路径：浏览器可能读取系统代理，而终端进程通常需要通过环境变量获知代理地址。

建议先记录三项信息：操作系统与终端类型、Clash Verge 实际监听的代理端口、失败时 Claude Code 输出的错误。然后从本机端口、代理连通性、规则出口、登录流程依次检查。不要一开始就同时切换 TUN、修改 DNS 和更换规则，否则即使恢复，也很难确认真正原因。

  • 本机代理端口：以 Clash Verge 的设置或当前配置为准。常见示例是 7897，但端口可能已被手动修改，也可能因配置不同而变化。
  • 代理模式：Clash Verge 运行中不代表每个终端程序都自动使用代理。终端未设置代理环境变量时，命令行请求可能仍然直连。
  • 规则出口：规则模式下，请求会按匹配结果选择策略组或直连。确认 Claude Code 相关请求实际命中了预期策略，而不是只看策略组名称。
  • 认证环节：终端登录与浏览器授权可能是两个步骤。浏览器打开授权页面，不代表终端回调或后续 API 请求也已成功。

确认 Clash Verge 正在监听代理端口

打开 Clash Verge，确认内核已经启动，并查看设置或当前配置中的 HTTP、SOCKS 或混合代理端口。混合端口通常同时接受 HTTP 代理与 SOCKS5 代理请求；若终端变量使用 http:// 地址，应选择 Clash 能接受 HTTP 代理请求的监听端口。不要仅凭网上常见的端口号填写。

本文以 7897 作为示例端口。若界面显示的是其他值，例如 7890，后续命令和环境变量都要替换成实际端口。配置中的端口与命令中的端口不一致时，常见结果是连接被拒绝或等待超时。

可以先在终端发出一次明确指定代理的测试请求。Windows PowerShell 使用 curl.exe，以免旧版 PowerShell 将 curl 识别为其他命令：

curl.exe -v --connect-timeout 10 --max-time 20 --proxy http://127.0.0.1:7897 https://example.com/

macOS、Linux 或支持 curl 的其他终端可运行：

curl -v --connect-timeout 10 --max-time 20 --proxy http://127.0.0.1:7897 https://example.com/

example.com 在这里仅作示例，不用于判断 Claude Code 服务是否可用。若命令提示连接 127.0.0.1:7897 被拒绝，优先核对 Clash Verge 是否运行、监听端口是否正确，以及本机安全软件是否拦截连接。若已连上本地端口，但之后请求超时，则检查 Clash 日志中的实际目标、命中规则和出口状态。

测试成功只说明 curl 能通过这条代理请求示例网址，不等于 Claude Code 的认证与服务请求都已成功。它的价值在于先证明“终端能连到本地代理”，避免在端口未通时反复改登录设置。

为当前终端设置代理变量

Claude Code 等命令行程序通常通过进程环境变量读取 HTTP 代理。优先在启动 Claude Code 的同一个终端会话中设置 HTTP_PROXY 和 HTTPS_PROXY。这些变量只影响当前终端启动的程序，不会自动替其他已经打开的终端补上设置。

Windows PowerShell

在 PowerShell 中执行以下命令，再从同一个窗口启动 Claude Code：

$env:HTTP_PROXY = "http://127.0.0.1:7897"
$env:HTTPS_PROXY = "http://127.0.0.1:7897"
claude

这里的 http:// 描述终端到本机代理的代理协议，不表示访问的网站必须是 HTTP；通过 HTTP 代理访问 HTTPS 网站时，客户端会使用代理隧道建立连接。若 Clash Verge 的实际端口不是 7897，请替换两处端口。

关闭这个 PowerShell 窗口后，临时设置通常随会话结束。若需要持久配置，先确认当前终端、启动方式和组织策略，再决定是否写入用户环境变量；持久设置会影响之后从该用户环境启动的其他程序。排障阶段建议先使用临时变量，便于撤销，也能清晰比较设置前后的结果。

macOS 与 Linux 终端

在常见的 zsh 或 bash 会话中，可以运行：

export HTTP_PROXY="http://127.0.0.1:7897"
export HTTPS_PROXY="http://127.0.0.1:7897"
claude

确认这两条变量确实存在时，可只检查变量名和代理地址，不要把包含密钥的完整环境输出发到公开渠道。若 Claude Code 是从 IDE、桌面启动器、任务计划或远程会话启动，它可能不会继承你在另一个终端窗口设置的变量。应在实际启动它的环境中配置，并重新启动对应的终端或 IDE。

若某些内网地址不应经过代理，可按需设置 NO_PROXY，例如只排除本机回环地址：

export NO_PROXY="localhost,127.0.0.1,::1"

PowerShell 的写法是 $env:NO_PROXY = "localhost,127.0.0.1,::1"。不要把范围很大的域名或通配规则随意加入排除列表；目标服务若被 NO_PROXY 命中，请求就可能绕过 Clash，造成“浏览器正常、终端仍超时”的差异。

规则模式下确认请求实际走向

Clash Verge 的规则模式适合让不同目标按规则选择出口，但终端代理变量只负责把请求交给本地代理，并不决定最后使用哪个节点。检查连接日志时，观察目标域名、命中的规则与最终策略；如果日志没有 Claude Code 发起请求的记录，先检查环境变量是否被进程继承，以及本地监听端口是否正确。

排查可按以下顺序进行：

  1. 保持 Claude Code 的终端窗口打开，在 Clash Verge 的日志页面清除不相关筛选。
  2. 重新执行一次失败的操作，记下准确时间，并查找同一时段出现的目标连接。
  3. 确认目标请求命中的策略组及当前选择的出口。策略组名字看起来像“代理”，不代表它当前选中的项目一定是可用节点。
  4. 如果日志显示规则命中直连，核对目标域名对应的规则和规则顺序；如果命中代理但连接失败，再针对当前出口做一次对照测试。
  5. 一次只切换一个条件，例如只换节点或只调整一条规则，然后重复同一操作并比较日志。

规则数据、订阅内容和客户端版本可能变化，Claude Code 使用的服务域名也可能调整。不要把某一份静态域名清单当作永久完整的答案。以实际日志中的目标为依据，确认需要的连接是否被错误地直连或送入不可用的策略组，再在自己的配置中做最小范围调整。若通过订阅覆写规则，应使用客户端提供的持久覆写方式；直接修改订阅生成文件可能在下次更新时丢失。

初次排错不必为了设置终端代理而开启 TUN。环境变量可以明确把支持代理的程序指向本机端口；TUN 则涉及系统路由、权限和更多应用流量。两者同时启用时，流量路径可能更难判断。只有在确认程序不读取代理变量、并且确实需要接管相关流量时，再了解 TUN 的适用条件和权限要求。

按错误现象继续定位

“登录失败”可能发生在请求授权页面、等待浏览器确认、终端接收本地回调，或随后与服务端建立连接的阶段。先看 Claude Code 显示的错误文本与 Clash 日志时间是否对应，不要仅凭浏览器是否弹出就判断整条链路正常。

  • 本地端口拒绝连接：错误地址若是 127.0.0.1 加本地代理端口，检查 Clash Verge 状态和端口。不要先改服务端认证信息。
  • 域名解析失败：记录失败的是目标服务域名还是代理节点域名。两者出错的阶段不同，换节点未必能修复本机 DNS 问题。
  • 连接或读取超时：对照日志确认是否进入内核、命中什么规则、使用哪个出口。然后只更换一个出口或测试条件。
  • 认证被拒绝：检查登录账户、令牌有效状态及终端当前使用的认证方式。代理能够连通，不代表账户具有对应服务权限。
  • 浏览器授权后终端仍等待：确认启动 Claude Code 的终端仍在运行，并留意本地回调是否被其他程序、安全策略或网络设置影响。不要把本地回调地址加入代理排除规则之外的复杂配置，除非日志明确表明需要调整。

若怀疑设置的变量没有被程序读取，可先在同一个终端运行 curl 测试，再重新启动 Claude Code；不要用另一个终端窗口测试后，假定原进程会自动获得新变量。若有代理认证要求，也不要将用户名、密码直接写进可分享的命令或脚本。普通本机 Clash Verge 监听通常不需要额外在变量中嵌入账户凭据。

完成测试后，恢复临时设置很简单：关闭设置过变量的终端会话即可。若把变量写入持久环境，则按对应操作系统的环境变量管理界面删除或修改，并重启受影响的终端、IDE 或桌面程序。排查日志也应恢复到日常需要的级别，避免长期开启过多调试输出。

常见问题

开启系统代理后，Claude Code 为什么仍然直连？

系统代理主要影响会读取系统设置的应用，命令行程序不一定自动继承。先在启动 Claude Code 的同一个终端设置 HTTP_PROXY 与 HTTPS_PROXY，并确认端口与 Clash Verge 实际监听值一致。还要检查 NO_PROXY 是否把目标排除。

环境变量能不能写成 SOCKS5 地址？

应优先使用客户端和程序明确支持的代理协议。本文示例使用 http://127.0.0.1:端口，便于让终端通过 Clash 的 HTTP 或混合代理入口发送请求。不要把 SOCKS5 端口误填进 HTTP 代理变量；如果确需 SOCKS，先确认 Claude Code 当前版本及其运行环境支持相应写法，再按实际监听类型配置。

开了 TUN 还需要设置代理变量吗？

不一定。TUN 通过系统网络路径接管符合条件的流量，环境变量则告诉应用显式连接哪个代理。两种方式可能叠加，也可能产生重复代理或路由混淆。先选一种路径验证，确认日志、权限和应用行为后再决定是否同时使用。

浏览器可以登录，为什么终端仍然失败？

浏览器与终端可能使用不同代理设置、不同 DNS 路径和不同认证会话。浏览器授权完成后，终端还需要继续访问服务或接收回调。检查终端代理变量、Clash 日志中的实际规则出口及 Claude Code 的具体错误阶段，再判断是网络路径还是账户认证问题。

下载客户端