How to Use Claude Code With Clash Verge for Reliable Access

Understand the connection path before changing settings

Claude Code runs in a terminal, but its network path is not necessarily the same as the one used by your browser. A browser may follow Clash Verge’s system-proxy setting, an extension, or an operating-system proxy configuration. A terminal process can instead use proxy environment variables, connect directly, or inherit a tunnel route from the operating system. That distinction explains a common puzzle: Claude.ai opens in a browser while claude reports a timeout, cannot complete sign-in, or repeatedly retries a request.

A useful troubleshooting model separates the journey into four parts: name resolution, transport to the local proxy, Clash routing policy, and the remote service. The terminal first needs to resolve the hostname it is contacting. If the process is configured to use a local HTTP or SOCKS listener, it then connects to that listener on your computer. Mihomo, the core used by many Clash Verge builds, evaluates the destination against the active profile and sends the connection to a policy group, a proxy node, or DIRECT. Finally, the selected route must reach the service and keep the connection alive long enough for the response to finish.

Each layer leaves different clues. A refused connection to 127.0.0.1 usually points to a wrong port or a listener that is not running. A local connection that succeeds while Claude Code still times out may indicate a rule, DNS, node, or remote connectivity problem. A browser sign-in that completes but a terminal sign-in that does not may indicate that the browser and CLI are using different routes. Keep these cases separate instead of changing a profile, shell setting, and authentication token at the same time.

Before troubleshooting, identify which Claude Code installation and shell you are using. The command may have been installed with npm, a native installer, or another supported method, and the active executable can differ from the one you expect if several versions are present. Check the installed version and the command location using the tools available in your shell. If you update the CLI during an incident, record that change; otherwise, a new version may alter the behavior you are trying to diagnose.

Also establish whether the problem is persistent or intermittent. Note the exact time, the command that failed, the full error text, and whether a retry behaves differently. A single brief failure can be an upstream interruption; repeated failures that begin immediately after changing a Clash profile are more likely to have a local cause. Avoid pasting access tokens, authorization codes, or complete environment dumps into support chats. Such output can contain secrets even when the command itself looks harmless.

Check Clash Verge listeners and routing

Start in Clash Verge, not in Claude Code. Confirm that the application is running, the intended profile is active, and the Mihomo core has started without an error. Then locate the actual HTTP, SOCKS, or mixed-port values shown by your version of the interface. Do not assume that a port number from a tutorial applies to your installation: profiles, forks, and user settings can change listener ports, and an HTTP listener is not interchangeable with every SOCKS listener.

For a terminal client, an HTTP proxy or mixed listener is usually the simplest first test because common command-line HTTP tools can use it directly. Copy the address and port shown by Clash Verge. If the listener is bound to the local machine, its address will commonly be 127.0.0.1 or localhost. If you deliberately use a different bind address, confirm that it is reachable from the machine running the terminal and that exposing the listener does not create an unintended open proxy.

Next, examine the active routing mode and policy groups. In rule mode, the connection to an Anthropic service is matched by the profile’s rules; it is not automatically sent through the same group as every browser request. Search the current configuration and the Clash Verge connection log for the destination host associated with the failed attempt. The log can help you determine whether the request matched a specific rule, a final catch-all rule, or a policy group you did not expect. Rule names and vendor hostnames can change, so use the observed connection and the current provider documentation rather than relying on an old copied domain list.

If the connection is classified as DIRECT but your network requires the configured proxy route, adjust the relevant rule or policy group in the profile you actually use. Put a narrow, intentional rule before a broad catch-all when the profile’s rule structure requires that ordering. Do not add an indiscriminate rule for every hostname containing a familiar product name: unrelated services may share broad domains, and an overbroad match can disrupt login, documentation, or other applications.

Choose a stable, permitted outbound route for a complete Claude Code session. Authentication, model requests, and any supporting service requests may involve different hostnames. If those requests take inconsistent routes, the browser can appear signed in while the terminal cannot finish its own flow, or a request can begin successfully and fail later. When a profile uses a selector, confirm that the selected policy group is the one matched by the relevant rule. When it uses automated groups, inspect which member is currently active rather than assuming that the group name guarantees a particular route.

TUN mode is an optional alternative when an application does not honor proxy environment variables. It can capture traffic at the network layer, but it adds more variables: system permissions, virtual interfaces, DNS handling, route conflicts, and possible interaction with corporate VPN software. First verify the ordinary local listener path with a command-line test. Consider TUN only if you have a legitimate need for system-wide capture and can confirm that your Clash Verge build and operating system support it correctly.

Configure proxy variables in your terminal

Once the listener is verified, configure the shell that launches Claude Code. Environment variables are inherited by child processes, so they must be set in the same terminal session—or in the startup file used by that shell. Setting a system proxy in a desktop interface does not guarantee that every terminal program will use it. Likewise, exporting a variable in one terminal window does not automatically configure another window, an IDE task, a background service, or a scheduled job.

For a temporary test in a POSIX shell such as Bash or Zsh, use the address and port you confirmed in Clash Verge. Replace the example port rather than copying it blindly. Setting both uppercase and lowercase forms can improve compatibility with tools that recognize only one spelling.

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

The scheme in these examples describes the connection from the terminal to the local HTTP proxy. It does not mean that the remote service is being contacted over unencrypted HTTP: HTTPS requests normally establish their secure connection through the proxy tunnel. If you are using a SOCKS-only listener, do not label it as an HTTP proxy. Use a client and proxy URL scheme that explicitly support SOCKS, or enable and use an appropriate HTTP or mixed listener instead.

For PowerShell, set the values in the current session using its environment-variable syntax. For example, assign the same local HTTP proxy URL to $env:HTTPS_PROXY and $env:HTTP_PROXY. These session-level values disappear when that PowerShell process closes. To make a setting persistent, add it to the appropriate shell profile only after the temporary test succeeds; then open a fresh terminal and verify that the new session inherited the expected values.

If you need to exclude local services from proxying, review the existing NO_PROXY or no_proxy value before changing it. Loopback destinations such as localhost and 127.0.0.1 are commonly excluded so local callbacks and development servers remain local. However, an overly broad exclusion can cause remote requests to bypass the proxy, while an overly narrow one can interfere with local sign-in callbacks. Make the smallest change that matches the observed failure.

Check what the current shell will pass to a new process without publishing the output. A proxy URL can include credentials in some environments, so treat the complete value as sensitive. If it contains an old port, an obsolete host, or an unintended trailing character, correct it before launching Claude Code. When testing with an IDE-integrated terminal, verify the variables there too: an IDE started before you changed system settings may retain an older environment for its child processes.

When the temporary setup works, decide how long it should remain active. A shell profile is convenient for a personal workstation, but it may not be appropriate on a shared machine or a device governed by enterprise policy. For one-off use, set the variables in a dedicated terminal and clear them when finished. Do not put tokens or passwords into a profile, a shell history entry, or a command copied into a public issue.

Verify connectivity and fix common failures

Test the local listener before changing Claude Code authentication. A command-line HTTP client such as curl can make a simple request through the proxy. Use a neutral, permitted HTTPS destination first, then test an Anthropic endpoint only if the service and your account allow that request. A successful generic request proves that the local listener accepted traffic and that at least one route worked; it does not prove that Claude Code’s complete login and model workflow is healthy.

curl -I --proxy "http://127.0.0.1:YOUR_HTTP_PORT" https://example.com

Then launch Claude Code from the same terminal session and observe Clash Verge’s connection log while reproducing the problem once. Match the timestamp and destination with the CLI output. If no corresponding connection appears, the process may not be using the variables, may be failing before network access, or may be using a transport path that your current test did not exercise. Recheck the executable, shell environment, and CLI version before changing routing rules.

If the log shows the expected destination but the selected route is wrong, correct the rule or group and repeat the test. If the route is correct but the connection stalls, compare a different authorized node or permitted route, then check whether the issue affects only long-lived or streaming requests. A quick header request can pass while a sustained response fails because the two tests exercise different connection durations. Avoid interpreting one successful ping or short request as proof that every API call will remain stable.

If the error is a connection refusal to the local proxy, verify the listener address, port, core status, and protocol. If the proxy accepts the request but name resolution fails, review the profile’s DNS mode and current DNS logs; do not immediately replace DNS settings with public resolvers, particularly on managed networks. If the request reaches a route but the remote service returns an authentication or permission error, treat that as an account or policy issue rather than repeatedly rotating nodes or credentials.

Sign-in deserves a separate check. Claude Code may open a browser for an authorization flow, but the terminal still has its own requests and callback handling. Confirm that the browser and CLI can both reach the required services through permitted routes, and do not assume a browser session automatically authenticates a separate CLI installation. If authorization appears to succeed but the terminal remains unauthenticated, record the CLI’s final message, inspect the relevant connection entries, and use the official sign-in or recovery instructions for the installed version. Never share an authorization code or access token while asking for help.

TUN mode is worth testing only after the listener-and-environment-variable path is understood. If you enable it, change one setting at a time, approve only the permissions requested by the legitimate application, and check for conflicts with another VPN or network filter. If TUN fixes the issue, that is evidence that the application’s traffic was not following the shell proxy path; it is not a reason to leave competing tunnels enabled or to ignore a policy restriction.

Finally, keep a short record of the working combination: Clash Verge version, core status, profile name, listener type and port, shell, proxy-variable names, route group, and test result. Redact credentials and subscription URLs. This makes later updates easier to diagnose because you can compare what changed instead of rebuilding the entire setup from memory. Profiles and upstream services evolve, so recheck the actual listener and connection log after an application or configuration update.

Other desktop proxy clients can be perfectly suitable for browser traffic, but their system-proxy toggles alone may leave a terminal process unconfigured, and generic shell exports can be confusing when the listener type or port is guessed. Clash Verge gives you a useful combination of visible local listeners, profile-based routing, and connection logs, so you can verify each hop rather than troubleshooting Claude Code by trial and error. If you want to compare a maintained Clash client and set up a clearer terminal workflow, visit the Clash V.CORE download page.