Claude Code With Clash Verge: China Access Setup Guide

Understand the connection path before changing settings

Claude Code runs in a terminal, but its network requests still have to pass through several separate layers. The terminal starts the Claude Code process, the process resolves a hostname and opens HTTPS connections, the operating system decides how those connections leave the computer, and Clash Verge either receives them through a local proxy port or intercepts them through TUN mode. A failure at any one of these layers can look like the same symptom: login keeps spinning, an API request times out, or the command exits with a vague network error.

For users in mainland China, the important point is that installing Clash Verge does not automatically make every command-line application use it. A browser may work because it follows the operating system proxy, while Claude Code still connects directly because the process does not inherit or read that setting. Conversely, enabling TUN mode can capture traffic that ignores application-level proxy variables, but it introduces extra routing, DNS, and permission considerations. Choose the least complicated method that covers the traffic you actually need, and make sure your use of network services complies with applicable laws, service terms, and local regulations.

The practical connection paths are usually these:

• Environment-variable proxy: Claude Code receives a local HTTP or SOCKS5 proxy address through variables such as HTTPS_PROXY or ALL_PROXY. This is usually the easiest method to test and undo.
• System Proxy: Clash Verge writes its local HTTP proxy into the operating system settings. This works for applications that explicitly read system proxy configuration, but a terminal program may or may not do so.
• TUN mode: Clash Verge creates a virtual network interface and routes more traffic through the Clash core. This can help when an application ignores proxy variables, but it should not be enabled blindly alongside other VPN or packet-filtering software.

Clash Verge and Clash Verge Rev can expose slightly different labels depending on the bundled Mihomo core and the application version. Look for equivalent fields such as Mixed Port, HTTP Port, Socks Port, System Proxy, and TUN Mode. The exact button position is less important than identifying the local listening address and port shown by the client.

Configure Clash Verge for terminal traffic

Start by opening Clash Verge and confirming that an active profile is loaded. The profile must contain usable proxy nodes and a proxy group that can route the required domains. Selecting a node in the Proxies panel is not enough if the active rule set sends the destination to DIRECT. For a first test, select a known-working node or group manually rather than relying on automatic selection while you are still diagnosing the connection.

Next, check the local port settings. A common configuration exposes a mixed port such as 127.0.0.1:7890, which accepts both HTTP proxy requests and SOCKS5 connections. Some installations use another port, and another process may already occupy 7890. Do not copy a port number from an online tutorial without checking your own Clash Verge panel. The address and port in your environment variables must match the port on which the local Mihomo core is actually listening.

The following values are examples only:

HTTP proxy: 127.0.0.1:7890
SOCKS5 proxy: 127.0.0.1:7891
Mixed port: 127.0.0.1:7890

If you use the mixed port, begin with an HTTP-style proxy URL for HTTPS requests. The word “HTTPS” in HTTPS_PROXY describes the destination protocol, not necessarily the protocol spoken to the local proxy. In many setups, the client connects to a local HTTP proxy and asks it to create a tunnel for the remote HTTPS connection.

Before testing Claude Code, verify Clash itself with a small command-line request. On macOS or Linux, use:

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

On Windows PowerShell, the built-in curl command may map to a PowerShell web request alias on some systems. Calling curl.exe removes that ambiguity:

curl.exe -I -x http://127.0.0.1:7890 https://example.com

A response from the destination, even an HTTP error such as 403 or 404, can still prove that the request reached a remote server through the proxy. A connection-refused error usually means that the local port is wrong or the Clash core is not running. A timeout after connecting to the local port points more toward the selected node, rules, DNS, or the remote route.

If the command works only when you enable the System Proxy switch, compare the actual system proxy address with the port shown in Clash Verge. If it works through an explicit -x option but not through environment variables, the issue is probably variable syntax, shell inheritance, or a conflicting variable already set in the terminal.

Set and verify proxy variables in the terminal

Environment variables are generally the most transparent way to connect a command-line program to Clash Verge. They affect the current process and any child processes started from it, which makes them easy to test without changing every application on the computer. They also make it possible to compare a direct request and a proxied request in the same terminal session.

macOS and Linux shell setup

In a Bash, Zsh, or compatible shell, temporarily export the local HTTP proxy for the current session:

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=http://127.0.0.1:7890

Lowercase names are also recognized by many tools, so setting both cases can avoid differences between programs:

export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export all_proxy=http://127.0.0.1:7890

Do not assume that ALL_PROXY must contain a SOCKS5 URL. It should match what the application and local Clash listener support. If you deliberately want to use the SOCKS5 port, the syntax is commonly:

export ALL_PROXY=socks5h://127.0.0.1:7891

The socks5h form asks the proxy to resolve hostnames, which can be useful when local DNS resolution is unreliable or when you want DNS requests to follow the proxy path. Whether a particular program honors this variable depends on its networking library. If it ignores the variable, use the HTTP variables, TUN mode, or the program’s own proxy option instead.

Check what the current shell will pass to Claude Code:

env | grep -i proxy

Then test the same path with curl:

curl -I https://example.com

When finished, remove the temporary variables with:

unset HTTP_PROXY HTTPS_PROXY ALL_PROXY
unset http_proxy https_proxy all_proxy

For a permanent setup, place the exports in the shell startup file used by your terminal, such as ~/.zshrc or ~/.bashrc. A safer beginner workflow is to keep them temporary until the configuration works. Permanent variables can unintentionally proxy package managers, Git, internal company services, or local development tools.

Windows PowerShell setup

In PowerShell, assign variables for the current window with the $env: prefix:

$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:ALL_PROXY = "http://127.0.0.1:7890"

Some tools inspect lowercase names, so you can add them when needed:

$env:http_proxy = "http://127.0.0.1:7890"
$env:https_proxy = "http://127.0.0.1:7890"
$env:all_proxy = "http://127.0.0.1:7890"

Inspect the values before launching Claude Code:

Get-ChildItem Env:*proxy*

Test the proxy explicitly and then test the inherited environment:

curl.exe -I -x http://127.0.0.1:7890 https://example.com
curl.exe -I https://example.com

To remove the variables from the current PowerShell window:

Remove-Item Env:HTTP_PROXY, Env:HTTPS_PROXY, Env:ALL_PROXY -ErrorAction SilentlyContinue
Remove-Item Env:http_proxy, Env:https_proxy, Env:all_proxy -ErrorAction SilentlyContinue

Command Prompt uses a different syntax:

set HTTP_PROXY=http://127.0.0.1:7890
set HTTPS_PROXY=http://127.0.0.1:7890
set ALL_PROXY=http://127.0.0.1:7890

Launch Claude Code from the same terminal in which the variables were set. If you open a new terminal, start an IDE-integrated terminal, or launch an application from a desktop shortcut, it may not inherit the temporary values. This is a common reason for seeing different behavior between a manually tested command and Claude Code.

Choose System Proxy or TUN mode

System Proxy is a good first choice when your terminal tools already respect operating system proxy settings and you want a simple, application-level change. Enable it in Clash Verge, confirm the displayed address and port, and open a new terminal. Then run a plain curl request without the -x option. If the request succeeds, launch Claude Code from that same terminal and test login or a small API operation.

System Proxy is not a universal switch. Some command-line programs ignore it, some libraries honor only environment variables, and some applications have their own proxy configuration. A green System Proxy indicator therefore does not prove that Claude Code is using the proxy. Explicit variables are easier to verify because the process receives a concrete value.

TUN mode operates at a lower network layer. It is useful when the application does not honor system settings or proxy variables, and it can cover traffic generated by programs that use their own networking implementation. In Clash Verge, enabling TUN may require administrator privileges, permission approval, or installation of a virtual network component. After enabling it, check that the TUN interface is active and that the Clash logs show traffic from the terminal process.

TUN mode also changes more of the computer’s network behavior. DNS mode, automatic route configuration, IPv6 handling, and exclusions can all affect the result. A misconfigured TUN setup may cause local websites, printers, corporate resources, or virtual-machine networks to stop working. If Claude Code starts working after TUN is enabled, that identifies a proxy-compatibility problem, but it does not prove that every TUN setting is correct.

• Use environment variables first when you want a reversible, process-level test.
• Use System Proxy when the terminal and related applications clearly follow the operating system setting.
• Use TUN mode when the application bypasses application-level proxy configuration and broader traffic interception is appropriate.
• Do not combine modes randomly: keep one known configuration, test it, record the result, and then change one item at a time.

For any mode, inspect the Clash Logs or Connections panel while running a request. A visible connection for the expected destination confirms that traffic reached the Clash core. No connection at all suggests that Claude Code is bypassing the client or failing before it opens a network socket. A connection followed by timeout or rule errors moves the investigation to the node, routing rule, DNS, or TLS path.

Troubleshoot login, API, and terminal failures

Once Clash Verge and the terminal proxy are configured, separate browser authentication from API traffic. A login flow may open a browser window, redirect through an authentication service, and then return a token to the local CLI. The browser can succeed while the terminal’s later API request fails, or the browser can fail while direct API connectivity is fine. Test each phase rather than treating “login” as one indivisible operation.

The login window does not open or the callback fails

First check whether Claude Code printed a URL that can be copied into a browser manually. If the browser opens but the final callback does not return to the terminal, inspect whether another application is already using the local callback port or whether a security tool blocked the loopback address. Local callback traffic such as 127.0.0.1 or localhost normally should not be sent through a remote proxy.

Review the NO_PROXY and no_proxy variables if you have set broad proxy rules. A practical baseline is to exclude local addresses:

export NO_PROXY=localhost,127.0.0.1,::1
export no_proxy=localhost,127.0.0.1,::1

On PowerShell:

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

Do not add remote service domains to NO_PROXY unless you intentionally want them to bypass Clash. An overly broad value can force API traffic onto a direct route and recreate the original failure.

Login succeeds but API requests time out

Check the Clash Connections panel while making a request. If there is no matching connection, confirm that the Claude Code process inherited the variables and that no wrapper script clears them. If a connection appears but is routed to DIRECT, inspect the active rules and proxy group. If the connection reaches a proxy group but fails with repeated timeouts, test another node and compare the logs.

Use a verbose curl request only for basic network diagnosis, not as a substitute for Claude Code’s authentication flow:

curl -v https://example.com

Look for these broad categories:

• Could not resolve host: investigate DNS, TUN DNS settings, or whether the selected proxy mode is trying to resolve the domain locally.
• Connection refused to 127.0.0.1: the local port is closed, incorrect, or already assigned to a different service.
• Connection timed out after entering Clash: check the selected node, proxy group, rules, and remote route.
• TLS or certificate errors: check the system clock, HTTPS interception software, security products, and whether a corporate certificate is required. Do not disable certificate verification as a casual fix.
• HTTP 401 or 403: the request reached a server, but authentication, account permissions, region policy, or service-side access rules may be involved. This is not normally fixed by changing the local port.

The terminal works but the browser or other apps fail

This usually means the explicit terminal variables are correct but the System Proxy or TUN configuration is incomplete. Check whether Clash Verge’s System Proxy address uses the same port as your environment variables. If TUN is enabled, review DNS and route exclusions, then temporarily disable other VPN software. Testing one browser request and one local address can reveal whether the problem affects only remote routing or the entire network stack.

Remove stale and conflicting proxy settings

Old variables are a frequent source of confusing results. A terminal may contain an outdated HTTPS_PROXY, while ALL_PROXY points to another port and a shell startup file restores both every time. Inspect all proxy-related variables, remove duplicates, and set only the values you intend to test. Also check package-manager configuration, Git proxy settings, IDE terminal profiles, and company-managed environment policies. A successful request in one shell does not guarantee that a child process launched by another tool receives the same configuration.

Finally, change one variable at a time. Record the original Clash port, the selected group, the proxy mode, and the exact command result. Start with an explicit curl request through the local port, continue with inherited environment variables, and only then retry Claude Code. This order keeps the test reproducible and makes it clear whether the failure belongs to Clash Verge, the terminal environment, authentication, or the remote service.