Claude Code With Clash Verge: Setup Guide For China

Why Claude Code Needs a Reliable Proxy Path in China

Claude Code brings an AI coding workflow to the terminal. Instead of switching between a browser and an editor, you can open a project directory, ask for an explanation of unfamiliar code, review a proposed change, generate tests, or investigate an error from the command line. That workflow is especially useful for beginners because the terminal keeps the project context, commands, and files in one place.

The difficult part for users in mainland China is often not the command itself. The CLI needs to reach the service endpoint, resolve its domain name, complete a TLS connection, and keep that connection alive while a response is streamed back. If any of those stages is interrupted, the symptom may look like an application problem: a timeout, a failed login, an empty response, a reset connection, or a request that remains stuck for several minutes.

Clash Verge can provide the missing network layer, but it does not automatically proxy every terminal program just because a browser works. A browser may follow the Windows or macOS system proxy, while a shell process may read HTTP_PROXY and HTTPS_PROXY, use its own network library, or ignore both. This is why the setup has two separate parts: first make Clash Verge route the traffic, then make Claude Code use that route.

The goal is not to force every connection through one mode without checking the result. A practical configuration should give Claude Code a stable proxy, preserve normal access to local development services, avoid exposing subscription credentials, and make it easy to turn the proxy off when it is no longer needed.

Check Clash Verge Before Configuring Claude Code

Before changing shell variables, confirm that Clash Verge itself is ready. The names of menus can differ slightly between Clash Verge releases and builds based on the mihomo kernel, but the important concepts remain the same: an active profile, a selected proxy group, a running local listener, and a mode that can receive the terminal's traffic.

• Import a valid profile. Open the profile page and import the subscription URL supplied by your service provider. After the profile is downloaded, select it as the active configuration and wait for the proxy groups to appear. A profile that is visible but not selected may not control any traffic.
• Select a usable proxy group. On the proxy page, choose a node or a proxy group with a stable route. Automatic groups such as URL-test may select a low-latency node, but a manual selection is easier to troubleshoot during the first setup.
• Confirm the local port. Look for the mixed, HTTP, or SOCKS listener in Clash Verge's settings. Common local addresses use 127.0.0.1, but the port is configurable and must be copied exactly. Do not assume that every installation uses the same port.
• Choose the right mode. System Proxy mode is usually enough for applications that honor operating-system proxy settings. TUN mode captures more system traffic, including programs that do not read system proxy settings, but it requires additional permissions and can affect local services, virtual machines, containers, and other VPN software.
• Enable logging temporarily. Set the log level to an informative level while testing. A request from Claude Code should create an entry that helps you distinguish DNS failure, connection refusal, timeout, and routing failure. Return to a quieter log level after the setup works.

For the first attempt, use the HTTP or mixed listener and explicit environment variables. This makes the connection path visible and reversible. If that works, you can later test TUN mode separately instead of changing several variables at once.

Hands-On Setup: Connect Claude Code to Clash Verge

This section uses a local proxy address represented by 127.0.0.1:PORT. Replace PORT with the HTTP or mixed-port value shown in Clash Verge. The placeholder is intentional: copying a port from an unrelated tutorial is one of the most common causes of a failed setup.

1. Start Clash Verge and choose a profile.

   Open the client, activate the profile, choose a proxy group, and confirm that the client is running. If the interface shows a connection or traffic indicator, generate a small test request from a browser or another known application first.

2. Open a new terminal.

   Use a new PowerShell, Command Prompt, macOS Terminal, or Linux shell window. A new shell avoids confusion caused by old variables or a terminal session that was opened before Clash Verge started.

3. Set temporary proxy variables.

   On PowerShell, run:

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

   On macOS or Linux, run:

   export HTTP_PROXY="http://127.0.0.1:PORT"
   export HTTPS_PROXY="http://127.0.0.1:PORT"
   export ALL_PROXY="http://127.0.0.1:PORT"

   Lowercase variants are useful because different command-line libraries check different spellings:

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

4. Check the variable without exposing credentials.

   Print only the local proxy value, not your subscription URL. On PowerShell, use $env:HTTPS_PROXY; on macOS or Linux, use printf '%s\n' "$HTTPS_PROXY". The result should show the expected local address and port.

5. Test the route with a harmless request.

   Use a service endpoint or test address that your organization permits. For a generic HTTPS check, run curl -I https://example.invalid only if your environment provides an equivalent test target; otherwise use the project's documented connectivity check. Watch Clash Verge's log at the same time. The important result is not only whether the command returns data, but whether the request appears in the Clash log.

6. Launch Claude Code from the same shell.

   Start the CLI without opening a second terminal. This ensures it inherits the variables you just set. If the command succeeds, ask it to inspect a small local project or explain a file that does not contain secrets. Keep the first request simple so that network errors are easy to identify.

7. Clear the temporary variables after testing.

   On PowerShell, use Remove-Item Env:HTTP_PROXY, Env:HTTPS_PROXY, Env:ALL_PROXY. On macOS or Linux, close the shell or run unset HTTP_PROXY HTTPS_PROXY ALL_PROXY http_proxy https_proxy all_proxy. Clearing them prevents unrelated tools from unexpectedly using Clash Verge later.

If you use Command Prompt instead of PowerShell, the temporary syntax is different:

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

These values apply only to the current Command Prompt window. For a permanent setup, prefer a shell profile or a small enable/disable script rather than writing proxy values into the global operating-system environment. A reversible script is easier to audit and less likely to affect package managers, local APIs, or corporate tools by accident.

System Proxy or TUN Mode: Which One Should You Use?

Clash Verge offers more than one way to capture traffic. System Proxy changes the HTTP and HTTPS proxy settings exposed by the operating system. Programs that honor those settings can send requests to Clash without individual configuration. This is the least invasive option and is a good starting point for Claude Code when explicit terminal variables are available.

TUN mode creates a virtual network interface and redirects a wider range of traffic into the mihomo kernel. It can help when a CLI ignores HTTP_PROXY, uses a networking library with no proxy support, or opens connections that are not ordinary HTTP requests. TUN mode may also intercept DNS and route traffic from applications that do not understand system proxy settings.

Broader capture does not automatically mean better results. TUN mode may require administrator approval, a privileged helper, or permission to add routes. It can conflict with another VPN, security software, a virtual machine network, Docker or similar container networking, or a local development service bound to a specific interface. Start with System Proxy plus explicit variables, then move to TUN only when the narrower method cannot cover the CLI.

When TUN is enabled, check that loopback addresses, private network ranges, your editor's local server, and package registries used by the project still behave as expected. A rule such as IP-CIDR,127.0.0.0/8,DIRECT,no-resolve may be appropriate in a compatible configuration, but do not paste rules blindly: the profile format and existing rule order matter.

Proxy Variables, Authentication, and Project Safety

Environment variables are convenient because they scope the proxy to a process tree. However, they are still configuration data. Shell history, process inspection tools, terminal recordings, CI logs, and diagnostic output may reveal their values. A local proxy address is usually not sensitive, but a proxy URL containing a username, password, or token is sensitive and should not be pasted into a public issue or saved in a project file.

Temporary Versus Persistent Settings

Temporary variables are best for the first test. They disappear when the shell closes or when you unset them. Persistent variables can be useful if you use Claude Code every day, but they also make troubleshooting harder because the proxy remains active when Clash Verge is stopped. If you choose persistence, create two small commands or scripts: one to enable the local listener and one to remove it. Name them clearly and keep them outside the repository.

Do not put HTTP_PROXY, HTTPS_PROXY, or subscription URLs into .env files that may be committed. Add sensitive files to the project's ignore list, and use a credential manager or the CLI's documented authentication flow where available. Claude Code may read project files while performing a task, so do not place access tokens, private keys, provider credentials, or personal subscription links in its working directory unless the tool's access behavior has been reviewed.

Keep Local Development Traffic Direct

Proxying a local API can create confusing errors. A development server at 127.0.0.1, a LAN database, or an internal service may not be reachable through an external proxy. If a project uses local endpoints, test them independently with the proxy variables cleared. You can also use a no-proxy list where supported:

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

On PowerShell, the equivalent is:

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

Some tools use NO_PROXY, some use lowercase no_proxy, and some implement their own bypass logic. Treat this list as a compatibility aid rather than a guarantee. If a local request still fails, inspect the tool's own documentation and verify whether Clash Verge's TUN rules are intercepting it.

Troubleshoot Failures in a Fixed Order

Changing several settings at once often produces a temporary improvement without revealing the cause. Use the layers below, from the local client outward. Stop at the first layer that fails.

1. Clash Verge process. Confirm that the client is running and that the active profile has not expired. If no proxy group is available, terminal variables cannot solve the problem.
2. Listener. Confirm the address and port. A refused connection usually means the listener is disabled, the port is wrong, or another program has taken the port. Check the Clash log and local status rather than guessing.
3. Shell inheritance. Print the variables from the same terminal used to launch Claude Code. A variable set in PowerShell is not automatically present in Command Prompt, a different terminal tab, an IDE task runner, or a remote shell.
4. Proxy protocol. Use an HTTP or mixed listener with an http:// proxy URL for the first test. If the CLI requires SOCKS5, follow its supported format and test that listener separately.
5. DNS resolution. If Clash shows no request, the process may be resolving outside the expected path or failing before a connection reaches the proxy. Review DNS settings, TUN DNS hijacking, and fake-IP behavior only after the basic listener test is confirmed.
6. Rule selection. If the request appears in Clash but is sent DIRECT, inspect the matching rule and proxy group. A broad MATCH,DIRECT rule placed before the intended proxy rule can make the node appear broken when the traffic never used it.
7. Authentication and service response. A successful TCP connection does not guarantee a successful login. Check the CLI's own error text, account status, clock accuracy, and any organization policy that may restrict access.

Do not repeatedly rotate nodes before confirming the local path. If the request never appears in Clash, changing nodes cannot help. Conversely, if the request reaches Clash and the selected node returns repeated timeouts, then comparing a second node is meaningful.

A Practical Daily Workflow

Once the connection works, keep the routine simple. Start Clash Verge before opening the terminal, activate the intended profile, and select a known-good group. Launch Claude Code from a shell where the proxy variables are either explicitly enabled or intentionally absent. When switching between work networks, recheck the selected node instead of assuming that yesterday's route is still available.

Keep project operations separate from network diagnosis. First verify that the CLI can connect with a small request. Then ask it to read a limited part of the project. Avoid granting access to unrelated directories, credentials, or production configuration while you are still testing. A stable proxy cannot compensate for unsafe file permissions or an accidentally exposed secret.

For a broader introduction to client installation and first-run permissions, see the quick start guide. When you need to install or compare a suitable client build, use the download center. The exact menu labels may change between Clash Verge releases, but the diagnostic principles remain the same: identify the listener, verify inheritance, observe the Clash log, and change one layer at a time.