Claude Code With Clash Verge: Setup Tips for Stable Access

Understand which part of the connection is failing

Claude Code can fail before it reaches the service, while it is contacting an API endpoint, or during browser-based sign-in. Those are different stages. A browser that can open a website does not prove that a terminal process is using the same proxy, and a successful proxy latency test does not prove that the account or requested service is available from your current region.

Clash Verge is a desktop client for managing a proxy core, commonly mihomo. It can provide a local HTTP or SOCKS listener, set the operating system’s system proxy, or route traffic through TUN mode, depending on the client version and configuration. Command-line applications do not necessarily follow the system proxy setting. For a first test, configure Claude Code’s terminal process to use the local listener explicitly; this makes the connection path easier to inspect.

Start by recording the exact error, the time it occurred, your operating system, the Clash Verge version, and the active core version. Do not include account credentials, authentication codes, API keys, full subscription URLs, or unredacted request headers when sharing logs. An error mentioning a timeout, DNS lookup, connection refusal, HTTP status, or authentication points to different checks.

Availability can vary by region, account eligibility, and network conditions. A proxy setup cannot guarantee access, change account eligibility, or make a service available where it is not offered. If the service returns an account or availability message, check the relevant official account information rather than repeatedly changing proxy settings.

Check the Clash Verge profile, core, and proxy listener

Before adjusting terminal variables, make sure Clash Verge has loaded the configuration you intend to use. A profile can import successfully yet still contain a group that needs a manual selection, a rule that sends the target domain to a different route, or a DNS setting that behaves differently from your browser’s network path. Confirm that the profile is selected and that the core is running; a visible profile name alone does not confirm that traffic is passing through it.

1. Open Clash Verge and select the intended profile in its Profiles or configuration view. Check that the profile is active and that its proxy groups and nodes are present.
2. Open the Proxies view and select a working node or group deliberately. If a group is set to automatic selection, note that its test destination and results may not match Claude Code’s connection requirements.
3. Check the connection or traffic view while making a new request. If no relevant connection appears, the terminal may not be using the Clash listener, or a system-level route may be handling it elsewhere.
4. In Settings, note the actual HTTP or mixed-port value. Do not assume that it is 7890; clients and configurations can use different ports. Also note whether the listener is bound to the loopback interface.

For a local terminal on the same computer, a loopback address such as 127.0.0.1 is normally the appropriate proxy host. The example below uses port 7890 only as a placeholder. Replace it with the HTTP or mixed port shown in your running Clash Verge configuration. A SOCKS-only listener needs a SOCKS URL instead of the HTTP URL in the example.

curl --proxy http://127.0.0.1:7890 \
  --connect-timeout 10 --max-time 20 \
  -I https://example.com/

This command tests whether curl can connect through the selected local HTTP proxy to a separate HTTPS destination. A returned HTTP response shows that this particular request completed; it does not verify Claude Code authentication, account status, or the route to every service endpoint. If the command says connection refused, recheck the port, listener type, and whether Clash Verge is running before changing DNS or editing rules.

Set proxy variables for the terminal process

A terminal process can use standard proxy environment variables even when the desktop system proxy is enabled. Set them only in the shell where you plan to run Claude Code, using the correct local port and protocol. This scoped approach is easier to undo and avoids unexpectedly routing unrelated tools, package managers, or background services through the proxy.

Configure a temporary proxy for one shell session

For macOS or Linux using a POSIX-compatible shell, export the HTTP and HTTPS proxy variables in the terminal. Many command-line tools use HTTPS_PROXY for HTTPS destinations while connecting to an HTTP proxy through the standard CONNECT method. Setting both upper- and lower-case forms helps with tools that recognize only one spelling.

export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"

claude

In Windows PowerShell, set process-scoped variables before launching Claude Code. These values apply to processes started from that PowerShell window and do not permanently change Windows settings.

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

claude

If your configuration provides a SOCKS listener rather than an HTTP or mixed listener, use the protocol it actually supports, for example socks5h://127.0.0.1:7891 where the client and application support that scheme. The h form requests proxy-side hostname resolution in compatible clients; support differs across tools. Do not point an HTTP proxy variable at a SOCKS-only port or assume that changing the scheme changes what the listener accepts.

Verify which variables Claude Code inherits

Environment variables are inherited when a process starts. If you set them after launching a terminal, an already-running Claude Code process will not receive the updated values; close it and launch a new process. To inspect whether the variables are set without printing their values, use a simple presence check. Proxy URLs normally should not contain account tokens, but avoid posting terminal output that might include credentials or private network details.

# macOS or Linux
[ -n "$HTTPS_PROXY" ] && echo "HTTPS_PROXY is set" || echo "HTTPS_PROXY is not set"

# PowerShell
if ($env:HTTPS_PROXY) { "HTTPS_PROXY is set" } else { "HTTPS_PROXY is not set" }

Some environments also define ALL_PROXY or NO_PROXY. If a stale NO_PROXY entry matches a required destination, the request can bypass the proxy. Conversely, removing every bypass rule may send local callbacks through the proxy and interfere with browser sign-in. Inspect existing values before changing them, and keep localhost destinations such as 127.0.0.1 and localhost reachable directly when the authentication flow relies on a local callback.

To remove temporary values, close that terminal session. In a POSIX shell you can also run unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy ALL_PROXY all_proxy. In PowerShell, clear only the process variables you set with Remove-Item Env:HTTP_PROXY, Env:HTTPS_PROXY, Env:http_proxy, Env:https_proxy. Avoid placing secrets in shell history, scripts committed to a project, or shared machine-wide configuration.

Test routing, DNS, and sign-in one variable at a time

With the terminal variables set, run one small request and observe both the terminal result and Clash Verge’s connection view. Use a destination appropriate for your own diagnostics; a successful check to a general website is not a test of Claude Code’s service endpoints. If the request appears in the connection list, inspect its matched rule and proxy group. The connection may be routed by a domain rule, a final rule, or a policy group, and a browser’s successful route does not guarantee that a command-line request matches the same rule.

1. Confirm the profile and core are active, then select a known working node or policy group. Change only the selection and repeat the same test.
2. Check the connection log for the requested hostname, matched rule, and selected outbound. If a rule sends the request to a direct route or an unavailable group, correct the relevant profile or group rather than changing every rule at once.
3. Compare one request with the current DNS configuration and one after checking the client’s DNS settings. A DNS failure can occur before a proxy connection is established, but DNS behavior depends on the profile and core configuration; do not assume that every lookup is performed by the remote node.
4. If the local proxy test works but Claude Code still times out, check whether the application uses the environment variables, whether the relevant endpoint is routed as expected, and whether the failure occurs during login or a later API request.
5. Change one condition at a time and record the result. Reverting a single change is more informative than simultaneously switching profiles, enabling TUN, replacing DNS servers, and editing shell startup files.

System Proxy and TUN mode solve different routing problems. System Proxy changes proxy settings for applications that honor the operating system’s proxy configuration; it does not force every terminal program to use that route. TUN mode can capture more system traffic, but it depends on permissions, route installation, DNS handling, and the active rules. It is not a substitute for checking the local listener and shell variables. Avoid running System Proxy, custom terminal variables, and TUN experiments together until you know which path is being tested.

Browser-based authentication can involve a browser redirect and a local callback. Keep the callback on the same machine, avoid routing localhost through a remote proxy, and do not share or manually edit callback URLs that contain temporary codes. If the browser completes sign-in but the terminal reports an authorization error, check the account selected in the browser and the CLI’s displayed authentication status. If the browser itself reports that the service is unavailable for the account or region, proxy troubleshooting will not resolve that eligibility issue.

Diagnose repeated timeouts and return to a known state

When a request hangs, distinguish a local listener timeout from a remote connection timeout. A refusal usually happens before the request reaches a proxy. A delayed response may involve DNS, the selected outbound, the destination, a rule, or a temporary network condition. Read the timestamp and destination from the client’s connection log, then compare it with the terminal error. Avoid interpreting a single latency test as proof that a node is suitable for every endpoint.

For a controlled retry, keep the same terminal, local port, profile, node, and test command. If you need to test TUN mode, first save or note the current settings, close the terminal application, enable TUN according to the client’s permissions prompts, and start a fresh terminal. Record whether the connection appears in Clash Verge and whether it follows the intended rule. If results become less clear, turn TUN off and return to the explicit local-proxy test rather than layering additional changes on top.

Once the test is complete, remove temporary proxy variables if you do not want future commands to inherit them. Restore any edited rule or DNS value that did not improve the result. Keep a short, redacted record of the client version, core version, operating system, observed error, and the successful or failing test. That information is more useful for troubleshooting than a full subscription file or an unfiltered debug log.

If you need the client installer or general setup instructions, use the downloads page and setup guide. Menu labels and available routing features vary by Clash Verge release and operating system, so verify each setting in the version you have installed.