Claude Code 为什么需要单独配置终端代理？
如果你正在搜索「Claude Code 国内怎么用」「Claude Code 登录失败」或「Clash Verge 终端代理」，通常遇到的并不是客户端完全无法启动，而是浏览器能打开相关页面，终端里的安装、登录或首次请求却不断超时。Claude Code 运行在命令行环境中，实际发起网络请求的是 Node.js 进程或 Claude Code 自身的运行时，它不会自动继承浏览器扩展里的代理规则，也不一定会按照系统 PAC 文件工作。
因此，仅仅在 Clash Verge 中打开「系统代理」，并不能保证 Claude Code 的全部请求都能正常通过代理。常见症状包括：npm 安装包下载到一半卡住，登录页面已经在浏览器中打开却无法完成回调，终端显示认证成功但第一次发送提示词时仍然报网络错误，或者连接列表里完全看不到 Claude Code 的请求。它们背后的共同原因往往是终端进程没有使用正确的 HTTP 代理端口，或者相关域名被错误地分到了直连策略。
本文使用 Clash Verge 作为示例，从客户端下载、订阅导入、代理模式选择，到终端环境变量验证，完整整理一套适合新手的配置顺序。文中不会提供任何账号、密钥或第三方服务推荐；你需要准备的是一份来源可靠的 Clash 订阅，以及已经安装好的 Node.js。配置完成后，可以根据连接日志判断请求是否真的经过了 Clash，而不是凭「网页能打开」来猜测终端是否通了。
先记住一个边界：Clash Verge 只负责在本机提供代理入口和转发流量，Claude Code 的账号权限、地区可用性、API 配额以及服务端返回的 401、403，并不能单靠代理解决。若日志显示 TLS 已建立、请求也确实走了代理，但服务端仍返回权限错误，应转向账号和配置侧排查。
安装 Clash Verge 并完成基础准备
安装客户端时，优先从项目公开发布页或可信的软件分发渠道获取安装包。不要把搜索结果中的「高速版」「免配置版」或来历不明的整合包当成官方版本，尤其不要在其中直接粘贴订阅链接和 API 密钥。订阅 URL 本质上等同于一组临时访问凭证，泄露后别人可能获取你的节点信息，甚至消耗流量。下载前应核对操作系统、CPU 架构和安装包名称；Windows 通常选择 x64，Apple 芯片 Mac 选择 arm64，Intel Mac 则选择 x64 构建。
首次打开 Clash Verge 后，先不要急着启动 TUN。新手最稳妥的顺序是先让系统代理加终端环境变量跑通，再决定是否需要全流量接管。打开应用后，检查主界面能否看到 Mihomo 内核状态、配置文件入口、代理端口和日志页面。如果客户端提示需要授予服务模式或网络扩展权限，应按照系统弹窗完成授权；但授权成功不等于已经在代理，仍然需要导入有效配置并选择可用节点。
在「配置」或「Profiles」页面添加你的订阅链接，等待客户端下载并解析 YAML。若订阅一直显示加载失败，可以先检查三件事：链接是否被复制时多了空格或引号；当前网络是否能连接订阅地址；客户端日志中是否出现证书、DNS 或超时错误。不要在订阅下载失败时反复点击更新，因为短时间内大量请求可能触发服务商限流。必要时先用浏览器确认订阅地址返回的是文本配置，而不是登录页面、验证码页面或过期提示。
- 导入订阅：打开 Clash Verge 的配置页面，粘贴订阅 URL，点击下载或导入，等待配置文件出现在列表中。
- 启用配置：选中刚刚下载的配置并设为当前配置，确认 Mihomo 内核没有显示 YAML 解析错误。
- 选择节点：进入代理页面，在策略组中选择一条延迟较低且状态正常的节点，不要一开始就依赖自动选择。
- 打开系统代理：回到主界面启用系统代理，确认开关状态与系统网络设置一致。
- 观察日志：打开连接或日志页面，随后再从终端执行测试命令，确认请求目标和策略组都能被记录。
小技巧：第一次测试时建议固定一个节点，而不是使用会自动切换的 url-test 或负载均衡组。登录过程包含浏览器跳转、回调和多个接口请求，如果策略组在中途切换节点，问题会更难复现，也不利于判断究竟是代理链路还是账号状态异常。
确认混合端口，再选择系统代理或 TUN
Claude Code 终端配置最关键的概念是混合端口。Clash 通常会提供一个同时兼容 HTTP 和 SOCKS5 的端口，常见形式是本机地址加端口号，例如 127.0.0.1:7890；但不同配置、客户端版本或用户自定义设置可能使用其他端口，不能直接照抄示例。请在 Clash Verge 的设置页面查看实际的 HTTP、SOCKS 或 Mixed Port，并以界面显示值为准。
| 使用方式 | 适合场景 | 优点 | 注意事项 |
|---|---|---|---|
| 系统代理 | 浏览器、部分桌面应用、遵循系统设置的终端工具 | 配置简单，关闭后容易恢复 | 不是所有 CLI、Git、容器或子进程都会自动继承 |
| 终端变量 | Claude Code、npm、Git、Node.js 项目 | 作用范围明确，便于单独测试 | 每个 Shell 或启动脚本都可能需要单独设置 |
| TUN 模式 | 不支持代理变量的程序、容器、桌面工具和全局流量 | 接管范围更广，减少逐个设置的工作 | 涉及权限、路由、DNS，出现冲突时排查更复杂 |
建议新手先使用系统代理和终端变量完成 Claude Code 的安装与登录。如果终端程序确认不读取代理变量，或者你同时需要让 Docker、WSL、IDE 内置终端等多个环境共享代理，再考虑开启 TUN。TUN 模式不是「更快」的开关，而是改变流量接管层级的网络功能。启用后若出现本地服务无法访问、局域网地址打不开、DNS 解析异常或系统断网，应先关闭 TUN 恢复到可控状态，再逐项检查自动路由、DNS 劫持和绕过局域网设置。
在 Clash Verge 中，系统代理打开后，可以先测试浏览器和普通命令行请求；若配置文件使用规则模式，相关域名应进入代理策略组。不要在排障初期直接使用全局模式作为永久方案。全局模式虽然能快速验证节点是否可用，但会让所有域名都经过代理，可能增加延迟、影响国内服务，并掩盖规则配置中的真实问题。确认链路后，切回规则模式，再根据连接日志补充必要规则更合理。
为 Claude Code 设置终端代理变量
终端代理变量的作用，是明确告诉当前 Shell 中启动的程序：访问 HTTP 或 HTTPS 地址时，应把请求交给本机 Clash 端口。推荐使用混合端口，因为它通常同时接受 HTTP 代理和 SOCKS5 代理请求，兼容性比只填写某一种端口更好。下面的示例端口仅用于说明写法，请替换为 Clash Verge 设置页面里的实际端口。
# macOS / Linux / WSL
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:7891
# Windows PowerShell
$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:7891"如果你使用的是混合端口，HTTP_PROXY 和 HTTPS_PROXY 可以都指向同一个混合端口；如果只填写了 SOCKS 端口，则应确认 Node.js、npm 或具体工具支持 SOCKS 代理。许多命令行程序对 HTTP_PROXY、HTTPS_PROXY 的支持比对 ALL_PROXY 更稳定，因此不要只设置 ALL_PROXY 就认为所有请求都会自动转发。
设置变量后，必须在同一个终端窗口里测试。新开窗口、IDE 内置终端、远程 SSH 会话和 WSL 都可能拥有不同的环境变量。可以先查看变量是否生效，再执行一个简单的 HTTPS 请求：
# 查看当前代理变量
env | grep -i proxy
# PowerShell 查看
Get-ChildItem Env:*proxy*
# 使用 curl 测试 HTTPS 请求
curl -I https://example.com测试时不要只看命令是否返回 HTTP 状态码，还要同时打开 Clash Verge 的连接日志。如果日志中没有出现对应域名，说明请求可能没有经过 Clash，应该检查变量拼写、端口、Shell 类型以及程序是否主动忽略代理环境变量。若日志显示请求已进入代理但连接失败，则进一步查看命中的策略组、节点和错误类型。超时、连接重置、TLS 错误和服务端 401 的处理方向并不相同，不能全部归结为「换节点」。
安装、登录与首次请求的排查顺序
Claude Code 的安装方式和版本会随官方发布调整，建议始终以官方文档显示的命令为准。若通过 npm 安装，先单独确认 npm 能访问注册表，再继续登录 Claude Code；不要把「包下载失败」和「OAuth 登录失败」混在一起排查。npm 可能访问注册表、包元数据服务和 tarball CDN，这些请求未必使用相同的域名。Clash 日志中如果只看到注册表请求，却没有看到后续下载目标，说明规则或代理链路仍不完整。
完成安装后，执行 Claude Code 的启动或登录命令。登录通常会拉起浏览器，浏览器负责展示授权页面，终端负责等待回调或交换认证信息。浏览器能打开授权页面，只能说明浏览器这一段链路可用，不能证明终端进程也使用同一个代理。若页面授权成功但终端迟迟没有完成，可以检查终端是否仍在运行、回调地址是否被本地安全软件拦截，以及 Clash 是否错误代理了 localhost、127.0.0.1 等本机地址。
- 安装超时：先检查 npm 的代理变量、注册表地址和 Clash 连接日志，再判断是否需要清理缓存或重试。
- 浏览器能登录，终端不结束：确认登录命令所在的终端继承了代理变量，并检查本地回调没有被 TUN 或安全软件干扰。
- 启动后首次请求失败：固定节点，查看连接日志中的真实域名和命中规则，不要只凭模型名称猜测规则。
- 返回 401 或 403：优先检查账号、订阅状态、环境变量名称和认证文件，不要把明确的权限错误当成网络超时。
- 请求反复断开：暂时关闭自动测速切换，固定稳定节点，并检查终端所在网络是否存在代理二次转发。
不要公开认证信息：排障时可以分享错误类型、时间和脱敏后的域名，但不要上传订阅链接、访问令牌、API Key、认证缓存文件或完整的环境变量截图。很多看似普通的终端日志，也可能包含用户名、项目路径和请求头信息。
让配置长期稳定：规则、日志与环境隔离
一次登录成功并不代表配置已经适合长期使用。建议把日常开发环境拆成三层：Clash Verge 负责节点、配置和分流；Shell 配置文件负责终端代理变量；Claude Code 或项目脚本负责自身的账号和模型设置。这样做的好处是出现问题时可以快速定位：浏览器和终端都失败，优先看 Clash；只有某个 Shell 失败，优先看环境变量；只有 Claude Code 返回权限错误，优先看认证和账户状态。
在规则维护方面，不建议把所有海外域名简单写成一个无限扩大的列表。更实际的方法是先观察真实连接日志，确认 Claude Code 当前版本访问了哪些域名，再将稳定、必要的目标加入适当策略组。域名可能随登录流程、区域、版本和服务端架构变化，因此静态教程只能提供排查方向，不能替代本机日志。对于开发机，最好保留一个专门的「开发工具」策略组，与浏览器或视频服务使用的策略组分开，避免自动测速导致长请求中途切换出口。
如果你在 VS Code、JetBrains、Windows Terminal、macOS Terminal、WSL 或远程服务器中使用 Claude Code，还要分别确认它们的网络环境。IDE 内置终端可能读取用户 Shell 配置，也可能使用独立启动方式；WSL 中的 127.0.0.1 是否能访问 Windows 主机端口，则取决于网络模式和系统版本；远程服务器无法直接使用你本机的 Clash 端口，除非额外建立安全的代理通道。不要把本机配置原样复制到服务器上，更不要为了让远程环境「能通」而把代理端口暴露到公网。
完成调整后，可以用下面的顺序做最终验收：先确认 Clash Verge 当前配置和节点状态正常，再确认终端变量指向实际端口，接着用 curl 或 npm 做基础 HTTPS 测试，最后启动 Claude Code 并观察完整连接日志。每次只修改一个变量，并记录修改前后的表现。如果问题在切换节点后消失，也不要立刻认定节点是唯一原因，还应确认原节点是否存在 DNS、TLS、出口地区或长连接稳定性问题。
相比之下，一些同类代理工具虽然能快速打开网页，却常把订阅、终端变量、TUN 权限和连接日志分散在不同位置，遇到 Claude Code 这类命令行应用时，用户往往只能反复切换全局模式，缺少清晰的验证路径。Clash 官网 更适合把这类问题拆成可执行步骤：从 Clash Verge 的安装与订阅导入，到混合端口确认、Shell 变量设置和日志排查，都能按本文思路逐层验证，而不是依赖猜测；如果你正准备为 Claude Code 配置一套可控的终端代理环境，不妨前往下载，再结合实际系统完成配置。