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

Claude Code 适合在终端中辅助阅读代码、生成补丁、解释报错和执行经过确认的开发任务，但它对网络连接的要求也比普通网页访问更严格。国内用户常见的问题包括登录页面无法打开、模型请求长时间等待、npm 或其他依赖下载缓慢、终端显示网络错误，以及浏览器已经可以访问但 Claude Code 仍然连接失败。

这类问题通常不是“v2rayN 没有代理成功”这么简单。v2rayN 负责启动 Xray 内核并提供本地 HTTP、SOCKS 或系统代理入口；终端程序是否使用代理，还取决于当前 Shell 的环境变量、代理协议、分流规则和进程启动时间。只打开 v2rayN 的系统代理开关，并不会自动让每个命令行程序继承代理设置。

先确认 Claude Code 的整体连接链路

使用终端代理时，一次模型请求至少经过四个位置：Claude Code 进程、操作系统网络栈、v2rayN 本地入站端口，以及 Xray 根据路由规则选择的远端出站。任意一层配置不一致，最终都可能表现为“登录失败”或“请求超时”。因此，排查时不要直接把问题归因于节点速度，也不要一开始就修改协议参数。

v2rayN 常见的本地监听端口包括 HTTP 代理 10809 和 SOCKS5 代理 10808，但端口并不是固定标准值。不同版本、用户自定义设置或其他软件占用端口后，实际值可能不同。应以 v2rayN「设置」→「参数设置」→「核心设置」或主界面显示的本地监听信息为准。

HTTP 代理适合先做基础验证，因为 curl、npm 和许多开发工具都能直接读取 HTTP 代理地址。SOCKS5 更适合明确支持 SOCKS 的程序。如果把 SOCKS5 端口错误地填入 HTTPS_PROXY，程序可能把它当作 HTTP 代理使用，表现为连接被立即关闭或 TLS 建连失败。需要使用 SOCKS5 时，应写成 socks5://127.0.0.1:10808，而不是只填写一个端口号。

Claude Code 的请求目标、登录流程和辅助服务可能随版本变化，不能只测试一个网页就判定全部链路正常。更可靠的做法是先验证本地代理端口，再验证 HTTPS 访问，再启动 Claude Code。这样可以把问题缩小到具体层级。

导入订阅并选择可用节点

如果 v2rayN 中没有可用节点，终端变量写得再正确也无法建立远端连接。首次配置建议先让桌面端的基础代理工作正常，再把同一个本地端口交给终端。订阅地址属于敏感凭据，不要粘贴到公开工单、截图或终端录屏中；更新失败时只保留错误类型，不要暴露完整地址。

1. 更新订阅

   打开 v2rayN 主界面，在「订阅分组」中添加订阅地址，保存后执行「更新全部订阅」。确认更新结果显示成功，并检查列表中的节点数量是否发生变化。

2. 选择活动节点

   在服务器列表中选中目标节点，执行「设为活动服务器」或同义操作。单击列表行通常只是选中配置，不一定代表它已经成为当前代理出口。

3. 测试节点连通

   使用 v2rayN 的延迟测试或连通性测试观察结果。先选一条结果稳定的节点，不要只依据一次最低延迟选择线路。

4. 确认本地端口

   进入「设置」→「参数设置」→「核心设置」，记录 HTTP 代理和 SOCKS 代理端口。若启用了混合端口，也要确认它实际接受的协议类型。

5. 开启核心服务

   确认 Xray 内核已经启动，并在日志中看到入站监听成功。若出现端口占用，先关闭使用相同端口的程序或更换端口，再重新启动核心。

节点测试成功只说明 v2rayN 能够通过当前出站建立测试连接，不代表 Claude Code 一定已经使用它。下一步仍要在启动 Claude Code 的同一个终端中设置代理变量。若 v2rayN 日志完全没有新增连接记录，而终端已经发起请求，通常说明环境变量没有生效，或者变量中的地址和端口写错。

在终端设置 HTTP 与 SOCKS 代理

代理变量必须设置在 Claude Code 所处的进程环境中。Windows PowerShell、Windows 命令提示符、macOS 或 Linux 的 Bash/Zsh，语法并不相同。以下端口以 HTTP 10809、SOCKS5 10808 为例；如果你在 v2rayN 中使用了其他端口，应替换为实际值。

PowerShell 临时设置

在 PowerShell 中执行以下命令，变量只对当前窗口及其后启动的子进程有效：

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

通常不需要同时设置三种代理变量。优先使用 HTTP 代理测试最简单的路径；如果某个工具明确要求 SOCKS5，再设置 ALL_PROXY。部分程序会优先读取大写变量，部分程序只识别小写变量。遇到“curl 可以访问、Claude Code 仍然失败”的情况，可以同时补充小写变量：

$env:http_proxy=$env:HTTP_PROXY
$env:https_proxy=$env:HTTPS_PROXY
$env:all_proxy=$env:ALL_PROXY
$env:no_proxy=$env:NO_PROXY

Bash 或 Zsh 临时设置

macOS、Linux 以及其他 Unix-like 环境的当前 Shell 可以使用：

export HTTP_PROXY="http://127.0.0.1:10809"
export HTTPS_PROXY="http://127.0.0.1:10809"
export ALL_PROXY="socks5://127.0.0.1:10808"
export NO_PROXY="127.0.0.1,localhost,::1"

export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export all_proxy="$ALL_PROXY"
export no_proxy="$NO_PROXY"

如果只想让一次命令使用代理，也可以把变量写在命令前面，例如：

HTTPS_PROXY="http://127.0.0.1:10809" \
HTTP_PROXY="http://127.0.0.1:10809" \
claude

实际启动命令可能是 claude、项目中定义的脚本，或由包管理器调用的其他入口，应以本机安装方式为准。重点不是命令名称，而是确保代理变量出现在目标进程启动之前。已经运行的 Claude Code 不会自动读取后来才设置的变量，修改后应退出当前进程并重新启动。

NO_PROXY 用于排除本机服务、回环地址和开发环境中的内部域名。不要把远端模型服务域名误加入排除列表，否则请求会绕过 v2rayN。若公司网络或本地开发服务使用额外网段，可以按需追加，例如 192.168.0.0/16；但排除范围越大，越要确认不会把应代理的请求一并放行。

用 curl 确认代理真的生效

在启动 Claude Code 之前，建议先使用 curl 做三次由近及远的测试。第一步测试本地端口是否监听，第二步测试 HTTPS 请求是否经过代理，第三步再观察 Claude Code 的实际请求日志。HTTP 状态码为 401、403 或 404 并不一定表示代理失败；只要能够收到远端服务的明确响应，就说明 DNS、TCP、TLS 和 HTTP 请求至少已经走到服务端。

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

curl -v https://example.com

curl -I https://api.anthropic.com

第一条命令显式指定 v2rayN 的 HTTP 代理，适合排除 Shell 变量问题。第二条命令依赖当前环境变量，可以验证变量是否被 curl 读取。第三条命令用于观察目标服务是否能返回 HTTP 响应。不要把测试结果简单理解为“访问 example.com 成功，所以 Claude Code 必然正常”；不同域名可能命中不同分流规则，服务端也可能要求认证或特定请求头。

需要特别注意终端中的引号和变量名称。HTTPS_PROXY 的值应包含协议前缀，例如 http://127.0.0.1:10809；只写 127.0.0.1:10809 可能被不同程序以不同方式解析。若代理端口设置了用户名和密码，也必须按客户端支持的 URL 格式进行转义，不能直接把包含特殊字符的密码原样拼接进地址。

为 Claude Code 设计稳定的分流规则

终端代理不建议一开始就做过度复杂的精确分流。Claude Code 可能访问模型接口、登录服务、更新资源和项目依赖源；这些目标的域名集合会随版本和服务变化。最稳妥的初始策略是：局域网与本机地址直连，明确需要代理的开发服务走代理，其余请求根据实际情况选择直连或代理。

• 本机与局域网优先直连：把 geoip:private 或本地回环地址放在规则前部，避免终端访问本地 API、数据库、容器服务时绕到远端节点。
• 模型服务按域名代理：对当前版本实际访问的 Anthropic 相关域名进行观察后再添加规则，不要凭记忆写一组长期不变的域名清单。
• 开发依赖单独验证：npm、Python 包管理器和容器镜像可能使用不同域名。Claude Code 请求正常，不代表依赖源也能正常下载。
• 默认规则放在末尾：如果使用“其余流量代理”，它必须位于局域网例外和明确直连规则之后，否则本地服务可能出现访问延迟或连接失败。
• 观察日志再收窄：先用较宽的代理策略确认功能可用，再依据 Xray 日志中的目标域名逐步增加例外。

当 v2rayN 使用系统代理模式时，浏览器和支持系统代理的应用可能自动走代理；终端程序仍然可能直连。若希望更多应用统一接管，可以考虑 TUN 模式，但 TUN 会改变系统级流量路径，对 DNS、局域网访问、虚拟网卡权限和路由冲突提出更高要求。为了只解决 Claude Code 的终端访问问题，优先使用环境变量通常更容易回滚，也更容易判断是哪一个命令产生了连接。

依赖下载与登录异常的进一步处理

Claude Code 的运行环境往往还会调用 Node.js、npm、Git、Python 或项目自身的安装脚本。每个工具都有自己的代理支持方式。环境变量是最通用的入口，但并非所有工具都会完全遵循它。比如 npm 可能同时读取配置文件和环境变量，Git 也可能保存独立的代理设置；如果两套配置指向不同端口，就会出现同一终端中部分命令成功、部分命令失败的情况。

建议先查看当前配置，再决定是否写入持久设置。npm 可以检查 npm config list，Git 可以检查 git config --global --get http.proxy 和 git config --global --get https.proxy。如果只是临时使用，不必把代理写入全局配置；长期写入前应确认设备是否会在没有运行 v2rayN 时执行自动化任务，否则后台任务可能因为访问一个已经不存在的本地端口而失败。

登录流程还可能涉及浏览器跳转、一次性授权页面和终端回调。此时需要确认浏览器与终端使用的是同一条可用链路，并留意是否有本机回调地址被加入了代理列表。localhost、127.0.0.1 和 ::1 通常应放在 NO_PROXY 中，以免授权回调被送到远端代理。如果终端提示认证失败而 v2rayN 日志没有远端请求记录，优先处理代理继承；如果日志显示请求已经到达服务端，则再检查账户、授权状态和客户端版本。

建立可重复的日常检查流程

配置完成后，不建议每次出错都重新编辑全部设置。可以保留一套固定检查顺序：先确认 v2rayN 核心运行，再确认活动节点，接着检查本地端口，然后在当前终端查看代理变量，最后使用 curl 和 Claude Code 做实际测试。每次只改变一个变量，例如只换节点或只切换 HTTP 端口，便于判断结果。

1. 检查核心：确认 v2rayN 没有显示内核退出、端口占用或配置解析错误。
2. 检查节点：查看活动服务器是否仍属于最新订阅分组，并进行一次延迟或连通性测试。
3. 检查变量：确认当前终端中的 HTTPS_PROXY 指向正在监听的 HTTP 代理端口。
4. 检查目标：用 curl -v 访问目标服务，观察是否出现代理连接、TLS 建立和 HTTP 响应。
5. 检查应用：重新启动 Claude Code，查看 v2rayN 日志是否出现对应的出站连接。

如果请求偶尔中断，记录发生时间、当前节点、请求类型和 v2rayN 日志中的第一条错误。连接超时、远端重置、TLS 握手失败和 HTTP 认证错误对应的处理方向不同。不要仅凭“今天能用、明天不能用”判断客户端配置失效；节点拥塞、网络切换、系统休眠恢复和订阅内容变化，都可能造成间歇性故障。

完成上述步骤后，Claude Code 的终端代理应当具备清晰的边界：v2rayN 提供稳定的本地入口，Shell 明确指定代理协议和端口，Xray 负责出站与分流，curl 用于验证链路，应用日志用于确认真实流量是否经过代理。后续更换节点时只需检查本地入口是否保持不变；后续调整分流时则应先保留一条可回退的默认规则。