在国内使用 Claude Code 时，常见问题并不只出现在命令本身。终端可能提示登录失败、OAuth 页面无法打开、请求长时间停留在连接中，或者浏览器可以访问网页但 Claude Code 仍然返回网络错误。原因通常涉及三个环节：Clash Verge 是否正常运行，终端程序是否真正使用了 Clash 的代理端口，以及当前配置是否允许 Claude Code 所需的域名通过稳定节点访问。
Clash Verge 负责在本机提供代理入口，Claude Code 则是通过终端发起 HTTPS 请求。两者之间没有“自动识别”关系：即使 Clash Verge 已经连接节点，终端也不一定会主动使用代理。本文以 Windows、macOS 和 Linux 上常见的终端环境为例，从安装、订阅导入、系统代理，到环境变量和连通性检查，逐步完成一套便于排错的配置。使用相关服务时，还应遵守所在地区法律法规、服务条款和账号使用政策，不要共享账号或绕过服务方的安全限制。
一、Claude Code 为什么需要单独配置终端代理
Clash Verge 常见的工作方式是在本机监听一个或多个端口。HTTP 代理端口用于接收 HTTP 或 HTTPS 请求，SOCKS5 端口则适合支持 SOCKS 协议的程序，mixed-port 通常允许客户端同时处理 HTTP 与 SOCKS 请求。具体端口不能直接套用网上的固定数字，应以 Clash Verge 当前配置页面显示的值为准。
浏览器通常会读取系统代理设置，因此打开“系统代理”后，浏览器访问网站可能已经经过 Clash。但 PowerShell、Windows Terminal、macOS Terminal、VS Code 集成终端以及其他命令行程序，是否使用代理取决于程序自身的实现。很多 CLI 工具会读取 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 和对应的小写变量；也有程序使用自己的配置文件，或者只支持其中部分变量。
Claude Code 的登录和接口请求都可能需要访问 HTTPS 服务。代理配置成功的判断标准不是“Clash Verge 显示已启动”，而是终端发出的实际请求能够出现在 Clash Verge 的连接日志中，并且请求可以完成 TLS 建连和响应。若日志中完全没有终端请求，通常说明终端没有使用代理，或者使用了错误的端口。
| 检查对象 | 主要作用 | 常见误区 |
|---|---|---|
| Clash Verge | 启动内核、加载订阅、监听本地代理端口 | 客户端启动不等于节点可用 |
| 系统代理 | 让遵循系统设置的桌面应用使用本地代理 | 终端不一定自动读取系统代理 |
| 终端环境变量 | 明确告诉命令行程序代理地址和协议 | 端口、协议或变量作用域写错 |
| 分流规则 | 决定目标域名走代理、直连或拒绝 | 规则命中后仍可能受到 DNS 和节点质量影响 |
还要区分“代理连通”和“业务可用”。一个测试网站能够打开，只能说明当前节点和本地代理基本工作，不能保证 Claude Code 的登录流程、API 请求、流式响应和长连接都没有问题。完成基础测试后，应在 Clash Verge 日志中观察 Claude Code 实际访问的域名和连接结果。
二、安装 Clash Verge 并导入订阅配置
先从可信来源获取与操作系统匹配的 Clash Verge 安装包。Windows 用户应注意安装包架构和系统安全提示，macOS 用户需要确认应用权限及芯片架构，Linux 用户则应结合发行版选择可用格式。安装完成后打开客户端，先不要急着启动 TUN 或修改复杂规则，优先确认图形界面能够正常运行。
导入订阅的基本步骤
- 打开 Clash Verge 的配置或订阅管理页面，找到添加订阅、导入 URL 或类似入口。
- 粘贴服务提供方生成的订阅链接，并为配置设置容易识别的名称。
- 执行拉取或更新操作，确认返回内容不是登录页面、错误文本或 HTML 文档。
- 选中刚刚导入的配置，将其设为当前运行配置。
- 查看代理组和节点列表，选择一个稳定节点进行延迟测试或连接测试。
订阅链接通常包含账号识别信息，不应发布到论坛、截图或公共代码仓库。若链接已经泄露，应尽快在服务提供方后台重置或生成新的订阅地址。订阅导入成功也不代表所有节点都能使用：节点协议、传输参数、证书验证和服务端状态都可能影响最终连接。
Clash Verge 的核心名称可能在不同版本或界面中显示为 Clash Meta、mihomo 或其他兼容实现。若订阅包含较新的协议、Reality、Hysteria2、TUIC 或特定扩展字段，应确认当前客户端使用的内核能够解析这些内容。配置载入失败时，先查看内核日志中的字段错误、协议不支持或证书错误，不要直接修改 Claude Code 的参数。
先用浏览器完成基础验证
打开 Clash Verge 的系统代理开关后，用浏览器访问一个普通 HTTPS 网站，再观察连接日志是否出现请求。随后在客户端中切换一个节点，重复测试。如果浏览器始终无法访问，说明问题还停留在 Clash 配置、节点、规则或系统代理层，应先完成这些基础排查。
三、在终端中设置 Claude Code 代理
完成 Clash Verge 基础验证后，再配置终端代理。下面示例使用本机回环地址和占位端口，实际操作时请将 7890 替换为 Clash Verge 设置页显示的 HTTP、mixed-port 或其他兼容端口。若使用 SOCKS5 端口，则协议前缀应写成 socks5://；HTTP 代理端口则使用 http://。
Windows PowerShell 临时设置
在准备运行 Claude Code 的同一个 PowerShell 窗口中执行：
$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:ALL_PROXY="http://127.0.0.1:7890"这种写法只对当前终端窗口及其启动的子进程生效，关闭窗口后通常不会保留。它适合排查问题，因为不会影响系统中的其他程序。若程序不接受大写变量，可以同时补充小写形式：
$env:http_proxy=$env:HTTP_PROXY
$env:https_proxy=$env:HTTPS_PROXY
$env:all_proxy=$env:ALL_PROXYmacOS、Linux 与 Git Bash
在 Bash、Zsh 或兼容 shell 中，可以使用以下命令：
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export ALL_PROXY="http://127.0.0.1:7890"
export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export all_proxy="$ALL_PROXY"如果确认配置长期稳定，可以将相应内容加入 ~/.zshrc、~/.bashrc 或其他实际使用的 shell 配置文件，然后重新打开终端。不要在共享电脑或公共脚本中写入包含用户名、密码或订阅信息的代理 URL。使用无认证的本机代理时，地址通常只需要回环地址和端口。
验证变量是否进入当前进程
PowerShell 可以执行：
Get-ChildItem Env:HTTP_PROXY,Env:HTTPS_PROXY,Env:ALL_PROXYmacOS 或 Linux 可以执行：
env | grep -i proxy然后使用系统中已有的 HTTPS 测试工具访问一个你有权限访问的普通站点，并同时观察 Clash Verge 日志。例如：
curl -I https://example.com如果 curl 请求能够完成，且日志中出现对应连接，说明当前终端至少能够通过本地代理发送 HTTPS 请求。若命令提示无法连接 127.0.0.1，应检查 Clash Verge 是否运行、端口是否正确以及本地防火墙是否拦截。若日志没有请求而命令却成功，可能是系统或工具使用了其他代理设置，不能据此判断 Claude Code 已经走同一条路径。
四、登录失败与请求超时时如何分流排查
Claude Code 的登录流程可能需要打开浏览器、完成授权，再将结果返回终端。此时应分别检查终端到服务端的请求，以及浏览器打开授权页面时使用的网络路径。浏览器能打开授权页面，不一定说明启动 Claude Code 的终端已经配置代理；反过来，终端能够访问某个接口，也不代表浏览器回调一定顺利。
登录页面打不开
- 先确认 Clash Verge 已开启系统代理，并检查浏览器请求是否出现在连接日志中。
- 确认系统默认浏览器没有单独启用另一个代理扩展或代理客户端。
- 检查系统日期、时间和时区。TLS 证书校验依赖准确时间，时间偏差可能导致安全连接失败。
- 不要把浏览器中的登录地址复制到公开场所，也不要将授权回调内容发送给他人。
- 如果浏览器能打开而终端仍然失败，回到终端环境变量和当前 shell 进程检查。
请求超时或连接被重置
超时不一定代表节点完全不可用。Claude Code 可能需要较稳定的 HTTPS 连接，流式输出期间还需要连接持续一段时间。可以在 Clash Verge 中更换一个延迟较低、丢包较少的节点，并观察日志中是 DNS 超时、TCP 连接失败、TLS 握手失败，还是远端主动关闭连接。
如果只有某个域名失败，可以检查规则是否将其错误地匹配为 DIRECT、REJECT 或不可用的策略组。规则匹配顺序通常是从上到下，前面的规则命中后，后面的规则不会继续处理。修改规则前应备份当前配置，并优先使用客户端提供的配置覆写能力，避免每次订阅更新都丢失手工修改。
终端提示代理协议错误
常见原因是把 SOCKS 端口写成 HTTP，或把带认证信息的远程代理地址误填为本机端口。可以分别尝试 Clash Verge 的 HTTP 或 mixed-port，并保持变量格式一致。若某个程序只支持 HTTP 代理，就不要直接填入只监听 SOCKS5 的端口；若程序明确要求 SOCKS5，再使用对应协议前缀。
| 现象 | 优先检查 | 处理方向 |
|---|---|---|
| 浏览器和终端都无法访问 | 节点、订阅、内核、系统代理 | 先恢复 Clash 基础连通性 |
| 浏览器正常，终端无日志 | 环境变量、终端窗口、端口 | 在启动 Claude Code 的同一窗口设置变量 |
| 终端有日志但请求超时 | 节点质量、规则、DNS、TLS | 查看具体失败阶段并更换稳定节点 |
| 登录页面成功但回到终端失败 | 浏览器回调、账号状态、进程环境 | 重新在同一终端启动登录流程 |
五、让日常使用更稳定的配置建议
完成一次登录后，不建议立即把所有流量都切换到 TUN 模式或复杂的全局代理。Claude Code 主要是终端网络请求，先用环境变量和明确的代理端口验证最容易定位问题。只有当其他不遵循系统代理的开发工具也需要代理时，再考虑启用 TUN，并重新检查 DNS、局域网访问和本地开发服务是否受到影响。
为开发环境保留清晰的代理边界
- 终端工具：通过环境变量明确指定代理，避免依赖不确定的系统代理继承行为。
- 浏览器：使用系统代理或单独代理设置，但排查时尽量不要叠加多个代理扩展。
- 本地服务：将
localhost、127.0.0.1和内网地址加入适当的直连范围，避免本地开发接口被送入远程节点。 - 代码仓库和包管理器：分别确认 Git、npm、pip 或其他工具是否读取环境变量，有些工具还保存了独立代理配置。
- 日志与隐私：分享错误信息前，删除订阅 URL、账号标识、访问令牌、完整请求头和可能包含个人信息的域名。
如果不希望每次打开终端都启用代理，可以保留一个专用脚本或 shell 函数，在需要使用 Claude Code 时手动加载。这样做比永久修改全局系统代理更容易控制，也能减少其他软件意外经过代理的情况。退出代理时，应确认取消变量或关闭专用终端，避免后续命令继续使用已经失效的本地端口。
# 临时取消当前 shell 中的代理变量
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY
unset http_proxy https_proxy all_proxyWindows PowerShell 中可以使用：
Remove-Item Env:HTTP_PROXY,Env:HTTPS_PROXY,Env:ALL_PROXY -ErrorAction SilentlyContinue
Remove-Item Env:http_proxy,Env:https_proxy,Env:all_proxy -ErrorAction SilentlyContinue最后，建议保留一份“可工作的最小配置”：一个已确认稳定的节点、一个明确的本地代理端口、一组终端环境变量，以及一次成功的 HTTPS 测试结果。以后遇到 Claude Code 无法连接时，先恢复这套最小配置，再逐项加入自动测速、复杂规则、TUN 或其他代理链路，排查效率会明显高于直接重装所有软件。
选择客户端并继续配置
先获取适合当前系统的 Clash 客户端，再回到快速上手页完成订阅导入、系统代理和终端环境设置。