Claude Code With V2RayN: Configure A Reliable Terminal Proxy

Claude Code is designed for developers who prefer an AI workflow in the command line. It can inspect a project, edit files, run tests, and communicate with remote model services without requiring a separate graphical workspace. That workflow depends on more than a successful installation, however. The terminal must be able to reach package registries, authentication services, and model endpoints through a consistent network path. On Windows, v2rayN can provide that local proxy layer while Xray handles the selected outbound connection.

This guide explains how to connect Claude Code with v2rayN, how to identify the correct local port, how to apply proxy variables only to the terminal session or persist them for future sessions, and how to verify whether a failure comes from v2rayN, the shell, authentication, or the remote service. The examples focus on Windows Terminal and PowerShell, while the same principles apply to Command Prompt and other terminal environments.

How the terminal proxy path works

When a browser uses v2rayN, the browser usually follows the system proxy setting or an extension-specific rule. A command-line application does not always read that setting. Claude Code, npm, Git, PowerShell commands, and other terminal tools may instead look for proxy environment variables. This is why the browser can open a website successfully while npm install or a model request still reports a timeout.

The complete path normally contains five separate parts. Claude Code creates an HTTPS request, the shell exposes the proxy address, v2rayN accepts the local connection, the selected Xray core forwards it through the active node, and the remote service returns a response. A failure at any point can look similar from the terminal, so testing each layer in order is more efficient than repeatedly changing the subscription configuration.

For HTTPS destinations, the terminal commonly uses the HTTPS_PROXY variable even though the local proxy address itself may begin with http://. This does not mean the remote connection is unencrypted. It means the terminal sends an HTTP CONNECT request to a local HTTP proxy, and the proxy then establishes the encrypted connection to the destination. If v2rayN exposes a SOCKS listener instead, use a client or environment format that supports SOCKS reliably; for the broadest compatibility with npm and command-line tools, the HTTP or mixed listener is usually easier to test.

The port values above are common defaults, not universal facts. v2rayN profiles and versions can use different ports, and an existing application may already occupy a selected port. Always read the actual value in v2rayN before copying a command. A correct proxy variable with the wrong port is indistinguishable from a stopped proxy from Claude Code's point of view.

Verify v2rayN before changing Claude Code

First start v2rayN and confirm that a configuration is selected and connected. The tray icon or main window should show that the core is running, but the most useful check is the local listener shown in the settings panel. Open the local proxy or inbound settings, note the HTTP, SOCKS, or mixed port, and confirm that the listener is bound to the loopback address rather than a nonexistent interface.

Next, test the local listener independently from Claude Code. In PowerShell, replace 10809 with the HTTP port shown in v2rayN:

curl.exe -I -x http://127.0.0.1:10809 https://registry.npmjs.org/

A response such as HTTP/1.1 200 OK, a redirect, or another normal HTTP status confirms that the request reached the destination through the proxy. A connection refusal usually means the port is wrong or the listener is not running. A timeout can indicate that the selected node, DNS path, or remote route is unavailable. Do not interpret a certificate message alone as proof that v2rayN is broken; the test should be read together with the status and core logs.

You can also check whether Windows has a process listening on the selected port:

Test-NetConnection 127.0.0.1 -Port 10809

If TcpTestSucceeded is True, a program has accepted the local TCP port. That does not prove the remote request works, but it narrows the problem to proxy protocol, routing, authentication, or the destination. If it is False, fix the v2rayN listener first. Check the port number, core status, firewall prompts, and whether another program has forced v2rayN to choose a different inbound port.

Configure proxy variables in PowerShell

For a first test, set the variables only in the current PowerShell window. This approach is safer than editing the system environment because it does not change unrelated applications and disappears when the terminal closes. Use the HTTP port from v2rayN:

$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    = "127.0.0.1,localhost,::1"

HTTPS_PROXY is the key variable for HTTPS model and authentication requests. HTTP_PROXY helps package managers and non-HTTPS endpoints. ALL_PROXY can assist tools that use a generic proxy variable, but some applications prioritize it differently. If a tool behaves unexpectedly, keep HTTP_PROXY and HTTPS_PROXY first and remove ALL_PROXY temporarily to isolate variable precedence.

Environment variable names can be case-sensitive in some software even though Windows itself treats them less strictly. For compatibility, you may define both uppercase and lowercase forms in a session:

$proxy = "http://127.0.0.1:10809"
$env:HTTP_PROXY  = $proxy
$env:HTTPS_PROXY = $proxy
$env:http_proxy  = $proxy
$env:https_proxy = $proxy
$env:NO_PROXY    = "127.0.0.1,localhost,::1"

Confirm what the current shell will pass to child processes:

Get-ChildItem Env:HTTP_PROXY,Env:HTTPS_PROXY,Env:NO_PROXY

Then test npm before launching Claude Code. This separates package access from the Claude Code executable itself:

npm config get proxy
npm config get https-proxy
npm view @anthropic-ai/claude-code version

Some npm installations have persistent proxy values saved in the user configuration file. If the output shows an old address, inspect the current configuration with npm config list. A stale npm proxy can override or conflict with the shell variables. Keep one source of truth during testing; either use environment variables or set the npm values to the same local listener, not two different ports.

Configure Command Prompt separately

Command Prompt uses a different assignment syntax. Open a new window and run:

set HTTP_PROXY=http://127.0.0.1:10809
set HTTPS_PROXY=http://127.0.0.1:10809
set NO_PROXY=127.0.0.1,localhost,::1
npm view @anthropic-ai/claude-code version

These values apply only to that Command Prompt window and programs started from it. If you set variables in PowerShell, an already-open Command Prompt will not automatically receive them. Launching Claude Code from the same shell where the variables were defined avoids confusion about inheritance.

1. Start v2rayN

   Open v2rayN, select a working node, start the Xray core, and record the HTTP or mixed port under the local proxy settings.

2. Test the port

   Run Test-NetConnection 127.0.0.1 -Port 10809, then use curl.exe -I -x to test an HTTPS destination.

3. Set variables

   In the same PowerShell window, assign HTTP_PROXY, HTTPS_PROXY, and NO_PROXY with the verified local port.

4. Test npm

   Run npm view @anthropic-ai/claude-code version and confirm that package metadata can be retrieved without a timeout.

5. Launch Claude

   Install or start Claude Code from that shell, then complete sign-in and test a small request before changing any advanced settings.

Install and launch Claude Code

Once npm can reach its registry through v2rayN, install Claude Code using the package method supported by your current Node.js and npm environment. A commonly used command is:

npm install -g @anthropic-ai/claude-code

After installation, verify that the command is available:

claude --version
where.exe claude

If the shell cannot find claude immediately after a successful installation, the npm global binary directory may not be included in PATH. Close and reopen the terminal first. If the problem continues, inspect the global prefix with npm prefix -g and add its binary directory through the Windows environment settings. Do not reinstall repeatedly before checking the command path; repeated installation attempts rarely fix a PATH problem.

Start Claude Code from the same terminal session that contains the verified proxy variables:

claude

Follow the displayed authentication flow and complete sign-in in the supported browser window. The proxy variables control network access from the terminal process, but they do not replace an account, subscription, permission, or valid authentication session. A successful connection to the package registry therefore does not guarantee that model requests will be authorized.

After sign-in, make a small request in a test project rather than immediately opening a large repository. Confirm that Claude Code can read the working directory, return a response, and perform a harmless operation such as explaining a file. This gives you a clean baseline. If the first request succeeds, keep the same node and shell variables while testing a second request; changing several conditions at once makes later failures harder to diagnose.

Make the configuration reliable for daily work

A temporary PowerShell configuration is ideal for diagnosis, but daily development may benefit from a repeatable launcher. Instead of changing the entire system proxy, create a small PowerShell function in your profile. First open the profile file:

if (!(Test-Path $PROFILE)) {
  New-Item -ItemType File -Path $PROFILE -Force
}
notepad $PROFILE

Add a function with the port you verified in v2rayN:

function Start-ClaudeProxy {
  $proxy = "http://127.0.0.1:10809"
  $env:HTTP_PROXY = $proxy
  $env:HTTPS_PROXY = $proxy
  $env:NO_PROXY = "127.0.0.1,localhost,::1"
  claude
}

After saving, reopen PowerShell and run Start-ClaudeProxy. This keeps the proxy scope limited to Claude Code and commands launched from that function. If your execution policy blocks profile loading, use a one-time session command instead of weakening the policy broadly. The goal is predictable process inheritance, not a permanent system-wide override.

Some developers prefer setting persistent user variables through Windows environment settings. That can work, but it also affects npm, Git, package managers, IDE terminals, and scripts that inherit the user environment. Persistent settings are appropriate only when those tools should use the same proxy all the time. Otherwise, a launcher function is easier to audit and less likely to break local services.

Keep NO_PROXY for loopback and local development services. Tools such as local web servers, container endpoints, or a development API on localhost should not be sent through a remote node. If your organization uses internal domains, add them to the list according to its network policy. Avoid putting broad wildcards into NO_PROXY until you understand which destinations they exclude, because an overly broad bypass can make a remote request appear to ignore v2rayN.

Diagnose timeouts and failed requests

When Claude Code reports a network failure, reproduce the problem with progressively higher-level tests. First verify the local TCP listener. Second run curl.exe through the same port. Third test npm metadata. Only then retry Claude Code. This order distinguishes a dead listener from a package issue and an authenticated model-service issue.

• Connection refused: v2rayN is not listening on the specified port, the port number is wrong, or the core stopped.
• Proxy connection timeout: The local listener accepted the request but the selected node or route did not complete the connection.
• Certificate or handshake error: Check the system clock, TLS inspection software, node security parameters, and the Xray core log.
• HTTP 401 or 403: The request reached the service, but authentication, account permissions, or organization access is the issue.
• HTTP 429: The service responded but rate limits or quota rules were reached; switching local ports will not solve it.
• Command not found: The package may be installed, but the npm global binary directory is missing from PATH.

Use v2rayN's core log while reproducing one request. A log entry showing an inbound connection confirms that Claude Code reached the local listener. An outbound dial failure points toward the node, DNS, routing, or remote server. No inbound entry usually means the shell variables were not inherited, the application ignored them, or a different proxy setting is being used. This single observation can save considerable time.

Do not add a second proxy layer unless the first one has been proven insufficient. Running a system proxy, a terminal wrapper, and an application-specific proxy simultaneously can create loops, conflicting bypass rules, or misleading logs. Keep one local listener, one selected node, and one clearly defined environment-variable strategy while testing.

Security and maintenance checklist

Proxy variables are ordinary process environment values, so treat them as configuration rather than secret storage. A local proxy URL without credentials does not contain the remote node's user ID, but shell history, profile files, screenshots, and diagnostic logs may still expose internal addresses or account-related information. Do not paste authentication tokens or private configuration data into public issue reports. If a provider gives a proxy URL with credentials, prefer a temporary session and remove it after testing.

Keep v2rayN and its selected core compatible with the imported node. Updating the client can change available core choices, local port defaults, or support for transport fields. Before a planned update, record the active core type, local HTTP and SOCKS ports, routing mode, and the name of a known-working node. After updating, test the local listener and npm before starting a long Claude Code session.

• Record the working local port, but verify it again after profile or client changes.
• Use an Xray core when the imported configuration requires current Xray-specific security or flow parameters.
• Keep local addresses in NO_PROXY so development services remain local.
• Test package access and model access separately; they can fail for different reasons.
• Use the smallest reproducible request when reading logs or comparing nodes.
• Clear temporary variables with Remove-Item Env:HTTP_PROXY,Env:HTTPS_PROXY,Env:ALL_PROXY when the test is complete.

The most reliable setup is therefore simple: v2rayN runs one verified local HTTP or mixed listener, the terminal points to that listener through HTTPS_PROXY, local development addresses bypass it, and Claude Code is launched from the same shell. If installation works but sign-in fails, investigate the account response. If sign-in works but requests time out, inspect the active node and core log. Separating those layers makes terminal-based development much easier to maintain.