Claude Code With V2Ray: Configure a Reliable Terminal Proxy

1. Why the browser and terminal can differ

v2rayN manages subscriptions, nodes, routing, and the local proxy listeners used by other programs. Claude Code is a separate command-line application. Turning on the Windows system proxy may help applications that read Windows proxy settings, but it does not guarantee that every terminal process or development tool will use that proxy. The terminal needs a proxy setting that the process recognizes, or a network route configured for that environment.

For a straightforward setup, use v2rayN’s local HTTP proxy listener and set HTTP_PROXY and HTTPS_PROXY in the shell before starting Claude Code. HTTPS traffic usually travels through an HTTP proxy using the HTTP CONNECT method; the proxy does not need to decrypt TLS traffic. Do not confuse the local listener with the remote node: the terminal connects to a local address and port, while v2rayN and its active core handle the onward connection.

Keep the client, core, node, and application settings separate while diagnosing a problem. A node that works in a browser can still be irrelevant to a terminal that is bypassing the proxy. Likewise, proxy variables cannot repair a stopped core, an unusable node, a blocked local port, or an authentication problem on the service side.

• Client: v2rayN provides the desktop interface and manages local proxy settings.
• Core: The selected core makes the connection described by the imported node configuration.
• Listener: An HTTP or HTTP-capable local listener accepts requests from applications on the computer.
• Shell: Proxy environment variables tell supported command-line programs where to send requests.

2. Prepare v2rayN and select a working node

Start by confirming that v2rayN itself can reach the internet through a node. Import your subscription using the provider’s instructions, update it, and select a node. Menu names can differ between v2rayN versions, so use the equivalent subscription and server commands shown in your build rather than relying on a label from a different release. Do not edit the node’s address, port, UUID, transport, TLS, or REALITY fields to make the settings resemble an example.

Run a real connection test for a small number of candidate nodes, then open a destination in a browser that you know should use the proxy. A TCP latency result alone only indicates that a TCP connection to a remote address and port succeeded; it does not prove that the full protocol, routing, or application request works. Confirm that the core is running and that v2rayN logs do not show a configuration parse error or a local listener failure.

Many v2rayN installations expose a local HTTP proxy on a port such as 10809, while other configurations use a different port or a mixed HTTP/SOCKS listener. Treat that number only as an example. Read the configured listener in your own v2rayN build. A SOCKS-only listener is not interchangeable with an HTTP listener when you set an HTTP proxy URL; select the correct protocol and port together.

3. Set proxy variables in the shell that launches Claude Code

Set the variables in the terminal session where you will run Claude Code. The URL scheme describes the local proxy listener, not the destination website: when v2rayN exposes an HTTP proxy, use an http:// proxy URL for both HTTP and HTTPS destinations. The HTTPS request is still protected by TLS between the client and the destination; the HTTP proxy carries the CONNECT request that establishes the tunnel.

PowerShell session

In PowerShell, replace 10809 with the HTTP listener port shown in v2rayN, then run the following commands before launching Claude Code:

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

These assignments apply to the current PowerShell process and programs started from it. They do not automatically change Windows proxy settings or persist across new terminal windows. This limited scope is useful for testing: close that shell to discard the temporary values. If the command is not found, troubleshoot the Claude Code installation or PATH separately; a missing executable is not evidence of a proxy failure.

Bash or Zsh session

In a Bash or Zsh terminal, use export so child processes inherit the settings:

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

Some software also checks lowercase variable names. If a program does not appear to recognize the uppercase values, you can set the corresponding lowercase variables in the same shell:

export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"

Use the shell appropriate to the environment in which Claude Code runs. A Windows terminal, PowerShell, Git Bash, and a Linux shell inside WSL have different process environments and may not share proxy variables. In particular, 127.0.0.1 inside a Linux virtualized environment refers to that environment’s own loopback interface; it is not automatically a promise that the Windows listener is reachable there. First establish which environment launches the CLI, then test the local address from that same environment.

ALL_PROXY is sometimes used by command-line tools, but support and accepted schemes vary by application. Do not rely on it as a substitute for the HTTP and HTTPS variables unless the tool’s documentation confirms that behavior. Avoid embedding subscription credentials or node secrets in proxy variables. A local unauthenticated listener should remain bound to loopback unless there is a deliberate, secured reason to expose it to other devices.

4. Verify the route before signing in

Test the listener from the same shell that will launch Claude Code. With the PowerShell variables set, run:

curl.exe -v --proxy $env:HTTPS_PROXY https://api.anthropic.com/

For Bash or Zsh, run:

curl -v --proxy "$HTTPS_PROXY" https://api.anthropic.com/

Watch for a successful connection to the local proxy and a CONNECT response before the TLS exchange. An HTTP status from the destination—even an error such as 401 or 404—can still show that the request reached the service. This check is a network-route test, not an authentication test, and a response code by itself does not prove that Claude Code can sign in.

If the request fails, compare the output with v2rayN’s core and connection logs at the same time. A connection refused at 127.0.0.1 usually points first to a wrong port, stopped listener, or mismatched proxy protocol. A timeout after the local connection succeeds may instead point to the active node, routing rules, DNS, or access to the destination. A TLS certificate error is different from a proxy connection refusal; note the complete error and avoid disabling certificate validation as a workaround.

• Local connection refused: Recheck the listener address, port, protocol, and whether the core is running.
• Proxy CONNECT fails: Confirm that the selected listener supports HTTP proxy requests and that v2rayN is not routing the destination unexpectedly.
• DNS or remote timeout: Check the active node and core logs; then test another known-working node without changing subscription parameters.
• Browser works, curl fails: The browser may use system proxy settings while curl uses the shell’s environment. Pass the proxy explicitly with --proxy as shown above.

5. Sign in and troubleshoot Claude Code

Once the explicit curl test reaches the destination through the local listener, start Claude Code from that same terminal. Follow its current sign-in flow. If authentication opens a browser, remember that the browser and CLI are separate clients: the browser may complete its part through Windows proxy settings even when the terminal’s own request path is wrong. Keep the terminal open and check whether the CLI reports a callback, token exchange, or network error after the browser step.

Do not diagnose every login failure as a V2Ray problem. A proxy route can be working while an account, organization policy, expired session, or service-side authorization prevents sign-in. Conversely, a browser login page loading successfully does not prove that the CLI completed its own requests. Use the exact error, the curl result, and the v2rayN logs to distinguish these cases. Do not paste tokens, authorization codes, subscription URLs, or full environment dumps into a public support request.

For a reliable routine, start v2rayN, confirm the active node and local HTTP listener, open the intended shell, set or verify its proxy variables, and then launch Claude Code. If the route stops working, test the local listener and core before re-importing a subscription or changing protocol fields. This order keeps the diagnosis focused and avoids turning a simple shell configuration issue into a larger, harder-to-reverse change.