Claude Code With V2Ray: Set Up a Terminal Proxy in China

Claude Code runs in a terminal, so configuring a proxy in a browser or turning on v2rayN’s system proxy may not be enough. The shell that starts Claude Code needs to inherit working proxy settings, and the local proxy listener must be reachable. This guide uses v2rayN on Windows as the example, while noting what to check on other systems. It does not guarantee that a service is available in every region; use Claude Code only where access is permitted under the service’s terms.

At a glance

Start v2rayN and confirm that one node can reach an allowed HTTPS destination. Then set HTTP_PROXY and HTTPS_PROXY in the same terminal session from which you launch Claude Code. Check the local listener port, the shell’s inherited variables, and the client’s routing mode before changing credentials or reinstalling anything. This sequence helps distinguish a local proxy problem from a sign-in or service-side issue.

How a terminal proxy works

There are several separate steps between typing a command and reaching a remote service. v2rayN manages the selected configuration and starts a proxy core. That core listens on one or more local ports. A terminal application can use one of those listeners only if it knows its address, and the core must then route the request through a usable server configuration.

Turning on the Windows system proxy mainly configures applications that read the operating system’s proxy settings. Command-line programs do not all use that setting. Claude Code is started from a shell, so the practical first test is to provide proxy environment variables to that shell. The variables are process settings: a terminal opened before they were set may not see them, and a new terminal may not inherit temporary values from an unrelated window.

v2rayN: Starts and manages the local proxy service. A selected node is a configuration choice, not proof that a remote connection succeeds.
Local listener: An address such as 127.0.0.1:10808 points back to the same computer. The port is an example; use the port shown in your own v2rayN settings.
Environment variables: HTTP_PROXY and HTTPS_PROXY tell compatible programs where to send web requests. For HTTPS, the local proxy generally needs to support the HTTP proxy CONNECT method.
Routing: v2rayN’s rules decide which outbound handles the destination. A working local listener can still fail if the selected route is direct, blocked, or otherwise unsuitable.

This distinction is useful when one application works and another does not. A browser may follow the system proxy, while a CLI tool uses environment variables or its own configuration. Neither result proves that every process is routed the same way.

Check v2rayN before launching Claude Code

First verify the proxy independently of Claude Code. Start v2rayN, select a configuration that you are authorized to use, and confirm that the core is running without a local port conflict. Then test an ordinary HTTPS destination that you are permitted to access. If that test fails, focus on v2rayN, the configuration, and network reachability before investigating Claude Code authentication.

127.0.0.1

Example loopback address for a proxy on this computer

10808

Common example port only; verify the actual local listener

2 variables

Set HTTP_PROXY and HTTPS_PROXY for the terminal test

In v2rayN, open Settings → Parameter settings and inspect the local proxy port fields. Labels and layout differ between releases, so check the actual HTTP or mixed-protocol listener rather than copying a port from another computer. If your version has separate HTTP and SOCKS listeners, the value in the examples below must point to the HTTP-capable listener when using an http:// URL.

Also check the current routing mode and the active configuration. If v2rayN is set to send the destination directly, shell variables cannot force the core to use a proxy outbound. For a controlled test, keep the same selected node and routing mode while testing both a browser and the terminal. Change one setting at a time, then retry the same destination.

Start the core

Open v2rayN and confirm that the core has started. If startup reports that a port is already in use, resolve that conflict before testing the terminal.
Choose a node

Select a known configuration and check that it is marked active. Do not treat a successful subscription refresh or a latency result alone as proof that every destination is reachable.
Check the listener

Open Settings → Parameter settings and note the local HTTP or mixed port. Confirm the address is local, usually 127.0.0.1, and use the displayed port rather than assuming it is 10808.
Verify routing

Review the active routing mode and rules. For a permitted test destination, confirm that the request is assigned to the intended outbound instead of being sent directly.

These checks do not require changing the server protocol. VMess and VLESS are different proxy protocols, and their transport and security parameters must match the server. If a node cannot connect, changing a shell variable will not repair an incorrect node configuration.

Set proxy variables in your shell

Use a fresh terminal after v2rayN is ready. The following Windows PowerShell commands set variables only for the current PowerShell process and programs it launches. Replace 10808 with the HTTP-capable local port you found in v2rayN. If your listener uses a different address, substitute that too.

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

Run the commands in the directory where you intend to work. Starting claude from that same window ensures the CLI inherits these values. Setting the variables in one PowerShell window does not automatically update an already-running editor, another terminal tab, or a separate command prompt.

To check what the current PowerShell process has received, run:

Get-ChildItem Env:HTTP_PROXY, Env:HTTPS_PROXY

If you use Command Prompt instead, set the variables in that window before starting the CLI:

set HTTP_PROXY=http://127.0.0.1:10808
set HTTPS_PROXY=http://127.0.0.1:10808
claude

On a Linux or macOS shell, use the equivalent temporary assignments in the current terminal:

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

Some software checks lowercase variable names as well as uppercase names. If a test indicates that the process is ignoring the uppercase values, set the lowercase forms to the same local URL in that shell and retry. Avoid putting credentials, subscription links, or private tokens into proxy URLs. A local listener normally does not need a username or password.

Windows PowerShell

HTTP variable: $env:HTTP_PROXY
HTTPS variable: $env:HTTPS_PROXY
Typical URL form: http://127.0.0.1:PORT

Values set this way apply to the current PowerShell session and child processes.

POSIX shell

HTTP variable: HTTP_PROXY
HTTPS variable: HTTPS_PROXY
Typical URL form: http://127.0.0.1:PORT

Use export in the terminal that will launch the CLI.

For repeated use, you can put the assignments in your shell profile, but doing so makes them apply to future terminal sessions and can cause confusion when v2rayN is closed. A safer initial setup is to keep them temporary. Once the test works, decide whether a profile entry is useful; document the port and remove or update the entry if the listener changes.

When the CLI starts but requests time out, first confirm that the variables are present in the process that launched it. A GUI terminal can inherit a different environment from a terminal opened after changing system settings. Close and reopen the terminal after making persistent environment changes, then print the variables again before launching Claude Code.

Next, test the local listener and the route separately. In v2rayN, inspect the core log around the exact time of one request. Look for whether the request reaches the core and which outbound or rule is selected. A log entry for a local inbound does not by itself prove that the remote server completed the connection. Likewise, a successful browser request may use a different proxy path from the CLI.

Connection refused at 127.0.0.1: The local port may be wrong, the core may not be running, or another process may have taken the port. Recheck the listener in v2rayN and restart the core if needed.
Timeout after the local connection: The request may have reached the core, but the outbound connection or route may be failing. Check the selected node, routing rule, remote reachability, and relevant core log lines.
Browser works, CLI does not: The browser may be reading the system proxy while the CLI is not. Set the environment variables in the launching shell and confirm their values there.
Sign-in page opens but completion fails: The browser-based sign-in flow and the terminal process may not share the same proxy path. Ensure the browser can complete its own allowed connection, then return to the original terminal and inspect the exact CLI message.

Authentication errors are not all proxy errors. An expired session, an incorrect account, an unavailable service, or an account restriction will not be fixed by changing the local port. Do not paste access tokens into terminal transcripts or share unredacted logs. If the network request succeeds but authentication is rejected, follow the service’s official account and sign-in guidance rather than repeatedly changing proxy settings.

When testing, avoid changing the node, routing mode, environment variables, and account session all at once. Make one change, run one request, note the result, and then decide what to test next. This preserves evidence about which layer changed and prevents a temporary improvement from being attributed to the wrong setting.

Common errors and focused fixes

The message text and behavior can vary by Claude Code, shell, and v2rayN release. Treat the examples below as diagnostic patterns, not as a guarantee that every installation will display the same wording. The most useful clue is usually the stage where the failure occurs: before connecting to the local listener, during the outbound connection, or during account authorization.

It says the connection was refused. What should I check?

Compare the proxy URL’s port with the HTTP or mixed listener shown in v2rayN. Confirm the core is running, then test again from a newly opened terminal. A refused connection to 127.0.0.1 usually points to the local listener, not to the remote account.

The variables are set, but the request still times out. Why?

Check that Claude Code was launched from the same shell and that v2rayN routes the destination through the intended outbound. Then inspect the core log for that request. A correct variable value does not prove that the remote route is healthy.

Do I need to turn on the system proxy too?

Not necessarily for a CLI process that honors proxy environment variables. System proxy and shell variables are separate mechanisms. First test the shell variables alone; enable the system proxy only if other applications need it.

Can a proxy fix a rejected sign-in?

Only if the failure is actually caused by network reachability. If the request reaches the service and the response is an account or authorization error, verify the account and session through the service’s official guidance. A proxy cannot make an unsupported or restricted account eligible.

For a clean retest, close the current CLI session, confirm that v2rayN and the selected node are running, open a fresh terminal, set both variables using the verified local port, and launch the command again. If it still fails, record the exact error, timestamp, shell type, local port, and whether a permitted HTTPS test succeeds. Redact account identifiers, tokens, subscription URLs, and other secrets before sharing diagnostic information.

Use a reliable and safe terminal setup

Keep the configuration minimal. A local proxy URL should point to the listener on your own machine, not to a public address copied from an unrelated guide. Do not expose the local listener to a network unless you have a specific, secured reason to do so. The loopback address 127.0.0.1 limits the connection to the local computer in the usual setup.

Temporary shell variables are useful for diagnosis because they make the scope clear. If you later add them to a profile, note how to unset them and verify that the chosen port remains correct after a v2rayN update or settings change. If the proxy is stopped, applications may fail immediately or appear to hang while retrying, so close the CLI session when you no longer need the proxy.

Finally, keep the roles separate when troubleshooting: the shell supplies proxy instructions, v2rayN provides the local entry point and routing, the selected configuration defines the remote connection, and the service controls account access. Checking each layer in that order is more effective than repeatedly reinstalling the CLI or rotating credentials when the actual problem is a stale port or a shell that never received the proxy variables.