Claude Code 配合v2rayN：国内终端访问配置指南

Claude Code 适合通过终端辅助编程、阅读项目文件和执行开发命令，但终端程序与浏览器并不总是共享同一套代理设置。即使 v2rayN 已经显示节点连接成功，Claude Code 仍可能出现登录页面无法打开、授权回调失败、API 请求超时，或首次响应很慢等问题。常见原因并不一定是节点失效，而是终端进程没有继承代理变量、v2rayN 的系统代理模式没有生效，或者分流规则把相关域名送进了直连出口。

本文以 Windows 11、v2rayN 7.x 和 Xray 内核为主要示例，说明如何导入订阅、选择节点、配置系统代理与终端环境变量，并通过命令行测试确认请求确实经过 v2rayN。文中使用的端口是常见起始值，实际端口应以 v2rayN「设置」→「参数设置」中显示的本地监听端口为准。

先理解终端代理与 v2rayN 的关系

v2rayN 是本地代理客户端，Xray 或其他核心负责实际的节点连接。启动后，客户端通常会在本机回环地址 127.0.0.1 上监听 HTTP 和 SOCKS 端口。浏览器可以通过系统代理自动使用 HTTP 端口，但终端里的 Claude Code、包管理器和脚本程序是否使用代理，取决于它们是否读取操作系统代理设置，或者是否看到了当前终端会话中的代理环境变量。

这条链路中有两个容易混淆的入口。第一个是 v2rayN 的本地监听端口，终端程序需要连接它；第二个是远端节点的服务器端口，例如 443 或其他端口，终端程序不应该直接填写这个端口。Claude Code 的代理设置通常不需要修改节点协议、UUID、传输方式或服务器端口，只需要让它的 HTTPS 请求进入本机代理。

• 系统代理：由 v2rayN 修改 Windows 的代理设置，适合浏览器和能够读取系统设置的应用。
• HTTP_PROXY：告诉许多命令行工具通过 HTTP 代理发送请求，常用于终端和脚本。
• HTTPS_PROXY：虽然名称带有 HTTPS，但它通常表示 HTTPS 请求使用的代理地址，值仍可以是本地 HTTP 代理。
• ALL_PROXY：部分程序使用这个变量作为通用代理入口，使用 SOCKS5 时要确认程序是否支持该协议。
• NO_PROXY：指定不使用代理的地址，例如 localhost、127.0.0.1 和局域网域名。

导入订阅并确认 v2rayN 基础状态

在配置 Claude Code 之前，应先把 v2rayN 本身调通。订阅导入失败、节点过期或系统时间错误，都会表现为终端登录失败或请求超时。此时直接修改 PowerShell 命令没有意义，因为终端即使成功连接到 127.0.0.1，也可能无法通过节点访问目标服务。

1. 导入订阅

   打开 v2rayN，在主界面找到「订阅分组」或订阅管理入口，新增订阅地址并保存。订阅地址应完整复制，不要混入空格、引号或换行。

2. 更新节点

   在订阅分组上执行「更新当前订阅」或「更新全部订阅」。如果更新超时，可以先暂时使用现有可用节点，避免把订阅下载问题误认为节点连接问题。

3. 选择核心

   进入「设置」→「参数设置」→「Core 类型」，优先选择与节点协议匹配的 Xray 内核。使用 VLESS、Reality 等配置时，应确认当前核心版本支持对应传输参数。

4. 测试节点

   在节点列表中选择一个延迟正常、近期可用的节点，执行测速或连接测试。延迟测试只能说明测试目标可达，仍需通过浏览器或命令行完成实际 HTTPS 验证。

5. 确认本地端口

   进入「设置」→「参数设置」查看本地 HTTP 和 SOCKS 端口。若界面显示的端口不是 10809、10808，后续环境变量必须使用界面中的真实数值。

如果 v2rayN 设置了“自动配置系统代理”，可以先用浏览器访问一个普通 HTTPS 页面，确认系统代理能够生效。之后再检查 v2rayN 日志，观察是否出现新的连接记录。不要在同一台电脑上同时开启多个代理客户端、多个 TUN 虚拟网卡或多个端口转发服务，否则终端请求可能被不同程序接管。

在终端中配置 Claude Code 代理

终端代理配置的核心是设置当前会话的环境变量，然后从同一个终端窗口启动 Claude Code。若先打开程序，再在另一个窗口执行 set 或 $env:，已经运行的进程不会自动获得新变量。最稳妥的顺序是关闭原有终端，确认 v2rayN 正在运行，在新终端中设置变量，再启动相关命令。

PowerShell 配置方法

打开新的 PowerShell 窗口，执行以下命令。示例使用 v2rayN 常见的 HTTP 端口 10809；如果你的端口不同，请替换所有出现的端口号。

$env:HTTP_PROXY = "http://127.0.0.1:10809"
$env:HTTPS_PROXY = "http://127.0.0.1:10809"
$env:ALL_PROXY = "http://127.0.0.1:10809"
$env:NO_PROXY = "localhost,127.0.0.1"
$env:HTTP_PROXY
$env:HTTPS_PROXY

最后两行用于确认变量已经写入当前会话。PowerShell 中变量名不区分大小写，但为了兼容不同运行时，建议同时设置大写形式。某些 Node.js 工具、网络库或安装器只读取其中一部分变量，因此同时设置 HTTP_PROXY 和 HTTPS_PROXY 更稳妥。

命令提示符配置方法

如果使用命令提示符，可以执行下面的命令：

set HTTP_PROXY=http://127.0.0.1:10809
set HTTPS_PROXY=http://127.0.0.1:10809
set ALL_PROXY=http://127.0.0.1:10809
set NO_PROXY=localhost,127.0.0.1
set HTTP_PROXY
set HTTPS_PROXY

set 只对当前命令提示符窗口及其子进程有效，关闭窗口后会失效。这种临时设置适合初次排查，可以避免把错误端口写入系统环境变量。确认代理链路稳定后，再决定是否通过 Windows 的“环境变量”界面设置为用户级变量。

类 Unix 终端配置方法

在 macOS 或 Linux 的 shell 中，写法通常是：

export HTTP_PROXY=http://127.0.0.1:10809
export HTTPS_PROXY=http://127.0.0.1:10809
export ALL_PROXY=http://127.0.0.1:10809
export NO_PROXY=localhost,127.0.0.1
env | grep -i proxy

如果使用 SOCKS5 端口，只有在程序支持 SOCKS5 环境变量时才将地址改为 socks5://127.0.0.1:10808。遇到 TLS 连接失败、代理协议错误或“Unsupported proxy scheme”等提示，应先恢复为 HTTP 端口测试。很多 HTTPS 客户端的正确关系是“通过 HTTP 代理建立 HTTPS 隧道”，并不是把 HTTPS_PROXY 的值写成 https://。

设置代理模式与分流规则

Claude Code 的请求是否稳定，不仅取决于本地端口，还取决于 v2rayN 的路由模式。如果选择“直连”或规则中把相关域名归入直连，终端变量虽然填写正确，请求仍可能从当前网络直接发出。第一次配置时，建议先使用较容易判断的全局代理模式完成连通性验证，再切换到规则分流。

在 v2rayN 主界面或托盘菜单中选择代理模式后，检查系统代理开关是否同步打开。不同版本的菜单名称可能略有差异，通常可以在「设置」→「参数设置」→「系统代理」或主界面的模式选择区域找到。终端程序不一定读取系统代理，但打开系统代理有助于先验证 v2rayN 的 HTTP 入站是否正常。

• 首次排查时使用全局代理，避免规则集误判。
• 确认终端请求成功后，再改为规则分流。
• 检查规则中是否把相关服务域名、认证域名或 API 域名设置为直连。
• 不要只根据浏览器地址栏判断分流，终端请求可能访问不同的域名。
• 局域网地址和 localhost 通常保留在 NO_PROXY，避免本地开发服务绕路。

动手验证终端是否真正走代理

不要直接把“登录失败”当作唯一测试结果。登录过程可能包含浏览器跳转、授权回调和多个网络请求，任何一个环节异常都会产生相同的表面提示。建议依次测试本地端口、通用 HTTPS 请求和实际运行命令，并在每一步记录结果。

1. 确认端口监听

   在 PowerShell 执行 Test-NetConnection 127.0.0.1 -Port 10809。如果 TcpTestSucceeded 为 False，先回到 v2rayN 检查核心是否启动或端口是否填错。

2. 检查变量值

   执行 Get-ChildItem Env: | Where-Object Name -match "PROXY"，确认当前终端确实有代理变量，并检查地址没有多余引号、空格或错误端口。

3. 测试 HTTPS

   使用支持代理参数的命令行工具访问一个稳定的 HTTPS 目标。观察命令是否能完成 TLS 建立；若本地端口可连但请求超时，应查看 v2rayN 日志中的出站错误。

4. 重新启动程序

   关闭原有 Claude Code 进程，在设置变量的同一窗口重新启动。不要从旧的桌面快捷方式或另一个没有变量的终端窗口启动。

5. 记录对照结果

   分别记录全局代理、规则分流和关闭代理时的结果。三组结果能够帮助判断是节点、规则还是终端继承问题。

Test-NetConnection 127.0.0.1 -Port 10809
Get-ChildItem Env: | Where-Object Name -match "PROXY"

如果使用 curl，可以显式指定代理进行对照测试：

curl.exe -I --proxy http://127.0.0.1:10809 https://example.com

这个命令只用于确认 HTTP 代理入口能够建立 HTTPS 请求，不代表目标服务的登录流程已经完成。若显式指定代理可以访问，而仅依赖环境变量失败，说明终端程序可能没有读取当前变量，或者变量名称与它使用的运行时不一致。若显式指定代理也失败，则继续检查 v2rayN 日志、节点状态和路由模式。

登录失败与超时的排查顺序

完成基础配置后，仍可能遇到授权页面打不开、程序提示网络错误、请求在几十秒后超时等现象。应先根据错误发生的位置分类，而不是反复更新订阅。下面的排查顺序适用于大多数基于 HTTPS 的终端工具。

稳定使用与安全收尾

确认 Claude Code 可以正常访问后，可以把配置整理成更适合日常开发的状态。建议保留一个“最小可用方案”：v2rayN 使用一个已经验证的 Xray 节点，终端使用 HTTP 代理端口，路由先保持规则分流，NO_PROXY 仅包含本地地址。这样出现问题时，变量数量少，恢复速度更快。

• 不要把订阅地址、访问令牌、授权信息或完整环境变量截图公开。
• 不要把代理变量写入项目的提交文件、构建日志或公开的 shell 配置片段。
• 开发本地服务时，将 localhost、127.0.0.1 和必要的局域网地址加入 NO_PROXY。
• 升级 v2rayN、Xray 核心或终端运行时后，重新检查本地端口与代理变量。
• 遇到异常时先记录客户端版本、核心类型、节点协议、代理模式和错误时间，再查看日志。
• 不需要终端代理时，关闭当前窗口或清除临时变量，避免其他命令误走代理。

Remove-Item Env:HTTP_PROXY -ErrorAction SilentlyContinue
Remove-Item Env:HTTPS_PROXY -ErrorAction SilentlyContinue
Remove-Item Env:ALL_PROXY -ErrorAction SilentlyContinue

最终验证应至少包含三项：v2rayN 本地端口处于监听状态，终端能够通过代理完成普通 HTTPS 请求，Claude Code 从已经设置变量的同一终端启动后能够完成对应操作。若只有第一项成立，问题在本地代理入口；若前两项成立而程序仍失败，应检查程序是否支持这些环境变量、是否需要单独配置，以及规则是否覆盖了它实际访问的域名。