Claude Code V2RayN Setup Guide for Terminal Access

Why terminal proxy settings matter

Claude Code runs from a terminal process, so its network behavior is determined by the environment inherited by that process, the application’s own network settings, and the operating system’s routing path. Enabling the system proxy in v2rayN may redirect browsers and applications that explicitly follow the operating-system proxy, but it does not guarantee that every command-line program will use the same route. A terminal session can continue attempting a direct connection even while a browser is successfully using v2rayN.

This distinction explains several common symptoms. Claude Code may remain at a login prompt, return a connection timeout, report that an API request failed, or complete authentication but fail on the next request. A browser test can appear normal because the browser reads the system proxy, while the terminal ignores it. Conversely, setting a SOCKS URL in a variable that only accepts HTTP proxy syntax can produce an immediate connection error rather than a useful API response.

The port numbers above are common examples, not fixed requirements. Open v2rayN and inspect the actual local listening ports before copying them into a command. In v2rayN, the relevant values are normally visible in the local proxy or settings area. A different profile, portable package, or another application may already occupy 10808 or 10809, causing v2rayN to select another available port.

Claude Code’s authentication and API behavior can also depend on environment variables such as an API key or an endpoint override. A proxy variable controls the route to the endpoint; it does not replace credentials, correct an invalid endpoint, or repair an expired account session. Treat network access, authentication, and endpoint configuration as separate checks.

Prepare v2rayN and a working node

Before changing terminal variables, make sure v2rayN itself can establish a connection. Importing a subscription only downloads a list of profiles; it does not prove that any node is reachable. Select one node, start the core, and check whether v2rayN reports a connected or running state. If the node fails inside v2rayN, Claude Code cannot fix the underlying address, port, UUID, password, TLS, Reality, or transport mismatch.

1. Install v2rayN

   Use the site’s download page to obtain the package for your desktop system. Extract it to a writable directory, start the main program, and allow the core process through the local firewall when the operating system asks.

2. Add subscription

   Open the subscription group area, choose the option to add or manage a subscription, paste the complete subscription URL, save it, and run an update. Keep the URL private because it may contain an account token.

3. Select a node

   Choose a node with a recent latency result and start the service. Do not judge only by the displayed delay; a node can respond to a TCP test while its transport or destination route still fails during an HTTPS request.

4. Check local ports

   Open v2rayN’s settings and record the actual HTTP and SOCKS listening ports. The examples in this guide use HTTP 10809 and SOCKS 10808, but your installation may use different values.

5. Test outside Claude

   Use a terminal request through the selected proxy before launching Claude Code. This separates a local proxy problem from a Claude Code authentication or application configuration problem.

For a first test, prefer the HTTP proxy exposed by v2rayN. Many command-line tools recognize http://127.0.0.1:10809 through the standard HTTP_PROXY and HTTPS_PROXY variables. A SOCKS listener can be useful, but support varies by runtime and tool. If you use the SOCKS port, confirm that the command supports socks5:// or socks5h://; the latter asks the proxy to resolve the hostname, which can avoid local DNS problems.

Set proxy variables by shell

A proxy variable belongs to a process environment. When you set it in a terminal, programs started from that terminal inherit the value. This makes temporary variables useful for diagnosis: they do not alter every application on the computer, and they can be removed simply by closing the terminal. Start with this method before writing values into a global profile.

Windows PowerShell

In PowerShell, set both uppercase and lowercase forms when testing third-party tools. Environment variable names are generally case-insensitive on Windows, but some libraries read a specific spelling. The following commands apply to the current PowerShell window and use the common v2rayN HTTP port:

$env:HTTP_PROXY = "http://127.0.0.1:10809"
$env:HTTPS_PROXY = "http://127.0.0.1:10809"
$env:http_proxy = "http://127.0.0.1:10809"
$env:https_proxy = "http://127.0.0.1:10809"

After setting the variables, run the network test and then start Claude Code from the same window. If you open a new terminal tab, the temporary values may not be present. To inspect them, use $env:HTTPS_PROXY. To remove them from the current PowerShell process, run:

Remove-Item Env:HTTP_PROXY
Remove-Item Env:HTTPS_PROXY
Remove-Item Env:http_proxy
Remove-Item Env:https_proxy

Windows Command Prompt

Command Prompt uses a different assignment form. The values remain active for the current window:

set HTTP_PROXY=http://127.0.0.1:10809
set HTTPS_PROXY=http://127.0.0.1:10809
set http_proxy=http://127.0.0.1:10809
set https_proxy=http://127.0.0.1:10809

Do not add spaces around the equals sign. If the port is wrong, the terminal program will usually report that the connection was refused or that it could not connect to the proxy. If v2rayN is not running, the result is similar, so verify the v2rayN status before interpreting the application error.

Bash and Zsh

On a Unix-like desktop, use export to place the variables in the current shell environment:

export HTTP_PROXY=http://127.0.0.1:10809
export HTTPS_PROXY=http://127.0.0.1:10809
export http_proxy=http://127.0.0.1:10809
export https_proxy=http://127.0.0.1:10809

For a temporary SOCKS test, replace the value with socks5h://127.0.0.1:10808, but do not assume that every dependency used by Claude Code will honor SOCKS variables. If HTTP works and SOCKS does not, keep the HTTP configuration for the first stable setup. You can later test SOCKS with a tool whose proxy behavior is documented and visible.

Verify the proxy before login

Testing the proxy independently is the fastest way to avoid confusing a routing failure with a credential failure. Use a harmless HTTPS request to a service you are authorized to access, or test the specific API hostname required by your configured Claude Code environment. The important observation is whether the request reaches an HTTPS response through the local listener, not whether a particular public test page loads.

With curl, an explicit proxy test can look like this on any shell that provides the command:

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

The verbose output should show a connection to 127.0.0.1:10809, followed by an HTTP proxy connection and TLS negotiation for the remote host. A local “connection refused” message points to v2rayN, the port, or a firewall. A timeout after the local connection succeeds points more often to the selected node, remote routing, DNS, or the destination itself. A certificate or hostname error should not be bypassed casually; it may indicate an incorrect endpoint, interception, or a mismatched TLS configuration.

Next, test the environment variables rather than the explicit -x option:

curl -I -v https://example.com

If the explicit proxy command succeeds but the environment-variable command goes direct, the shell variables were not set in the current process, were overwritten by a profile, or are not recognized by that version of the tool. If both tests fail in the same way, return to v2rayN and test another node.

Launch Claude Code through v2rayN

Once the independent request works, start Claude Code from the same shell where the proxy variables are visible. The exact installation and authentication commands can change with the tool’s release and your organization’s account policy, so follow the current Claude Code instructions for installation and login. The proxy portion remains the same: v2rayN provides the local listener, while the terminal process receives the proxy address through its environment.

On PowerShell, a typical sequence is:

$env:HTTP_PROXY = "http://127.0.0.1:10809"
$env:HTTPS_PROXY = "http://127.0.0.1:10809"
claude

On Bash or Zsh, use:

export HTTP_PROXY=http://127.0.0.1:10809
export HTTPS_PROXY=http://127.0.0.1:10809
claude

If Claude Code uses a different executable name in your installation, launch that executable instead. The key requirement is that the process starts after the variables are set. If the program has already been launched from another terminal, changing variables in a new window does not modify the existing process.

Do not add ALL_PROXY immediately unless you know that a dependency requires it. ALL_PROXY can affect DNS, package managers, telemetry, local services, and commands that should remain direct. A narrow configuration with HTTPS_PROXY and, when necessary, HTTP_PROXY is easier to audit. Some tools also honor NO_PROXY; use it for local addresses so requests to development services do not enter the proxy:

NO_PROXY=localhost,127.0.0.1
no_proxy=localhost,127.0.0.1

On PowerShell, the equivalent is:

$env:NO_PROXY = "localhost,127.0.0.1"
$env:no_proxy = "localhost,127.0.0.1"

Keep endpoint variables separate from proxy variables. If your environment requires a custom API endpoint, configure that endpoint only according to the service documentation and confirm that its hostname is reachable through the selected route. A proxy can transport the request, but it cannot make an invalid base URL valid.

Configure smart routing without breaking local tools

Smart routing is useful when only external API traffic should use the proxy while local development traffic, private network services, and package mirrors should remain direct. The exact menu names vary across v2rayN releases, but the principle is stable: choose a routing mode, inspect the active rules, and confirm which outbound is selected in the core log. Do not assume that “global” is automatically more reliable.

• Rule or smart mode: Use this for normal development. External destinations can use the proxy while private address ranges and local services remain direct.
• Global mode: Use it as a short diagnostic test when rule matching is suspected. It can expose whether the issue is a missing domain rule, but it may interfere with local package registries and intranet tools.
• Direct mode: Use it to confirm that the underlying terminal, DNS, and account setup work without proxying. A direct failure does not prove that the proxy configuration is wrong.

Claude Code may contact more than one hostname during authentication, API access, update checks, or auxiliary operations. If a rule list contains only one remembered domain, a later request can take a different route and fail unexpectedly. Watch the v2rayN core log while reproducing the issue. Look for the requested domain, selected outbound, DNS result, transport error, and whether the connection was rejected locally or remotely.

DNS handling deserves particular attention. If the terminal resolves a hostname directly to an unusable address before v2rayN receives the request, a domain rule may not behave as expected. A SOCKS configuration using socks5h can move hostname resolution to the proxy path for tools that support it. With an HTTP proxy, confirm that the tool sends an HTTPS CONNECT request to the proxy rather than resolving and connecting to the destination directly.

Troubleshoot common terminal errors

Read the first meaningful error rather than the final stack trace alone. A dependency may retry the same failed request several times, making one local timeout appear as many different messages. Close duplicate Claude Code processes, keep one v2rayN node active, and reproduce the error once while watching the core log.

Port conflicts are another frequent cause. A local development server, container tool, or second proxy client may already use 10808 or 10809. On Windows, inspect active listeners with netstat -ano and match the process identifier in Task Manager. On a Unix-like system, use the platform’s socket inspection command to identify the listener. Changing v2rayN’s port is valid, but every terminal variable must then be updated to the new value.

If requests succeed only in global mode, inspect the smart-routing rules and DNS path rather than keeping global mode permanently. If requests fail in every mode, compare two nodes and test the local listener independently. If curl succeeds but Claude Code still fails, inspect the process environment, endpoint variables, authentication state, and the runtime’s proxy support. This sequence narrows the fault without replacing a working subscription.

A safe daily workflow

For regular terminal work, start v2rayN before opening the development shell, select a node that has recently passed a connection test, and set the proxy variables only in the shell that needs them. Keep NO_PROXY for local addresses, use rule mode for ordinary traffic, and switch to global mode only for a controlled comparison. When changing networks, especially between home broadband and mobile tethering, retest the node instead of assuming that the previous route remains valid.

When the subscription is updated, do not change the terminal variables unless the local ports changed. A subscription update changes remote profiles; the shell still points to v2rayN’s local listener. If every node becomes unavailable after an update, check the subscription response and core logs. If only one node fails, remove or skip that profile and test another. Keep credentials and subscription URLs out of screenshots and shared terminal history.

Before concluding that Claude Code is unavailable, collect four facts: the v2rayN core type and version, the selected node and transport, the local proxy port, and the exact terminal error. Add the result of one explicit curl proxy test and one environment-variable test. These details distinguish a local port problem, a node transport problem, a routing or DNS problem, and an application authentication problem.