Tutorial September 26, 2026

Use Claude Code With Clash Verge: Setup and Access Guide

Claude Code runs in the terminal, so a desktop proxy setting may not be enough to route its requests. Follow this guide to check Clash Verge, configure terminal proxy variables, review routing rules, and test connectivity before troubleshooting the coding tool itself.

Docker Proxy GitHub Acceleration Advanced Config YAML

1. What this guide configures—and what it does not

This guide is for developers who already use Clash Verge and want Claude Code to reach its service reliably from a terminal. Claude Code is a command-line tool: it may make network requests from a shell, an editor’s integrated terminal, or a child process started by an IDE. That traffic does not necessarily follow the same path as a browser window. A website loading successfully while Claude Code times out is therefore not proof that the CLI can use the same proxy.

The setup has three separate parts. First, Clash Verge must be running with a usable profile and an active system proxy, mixed port, or TUN mode. Second, the process running Claude Code must either inherit a proxy setting or have its traffic captured by the selected system-level mode. Third, the active Clash rules must send the relevant connections to an appropriate policy or node. Checking these layers separately is faster than repeatedly changing DNS, reinstalling Claude Code, or switching every connection to a different mode.

This is a connectivity guide, not an account, billing, or eligibility workaround. Claude Code access depends on the applicable Anthropic plan, account, and current regional availability. A successful TCP connection cannot grant access to a feature that your account is not entitled to use. Likewise, if an employer or provider restricts sending source code through a third-party proxy, follow that policy before routing any prompts or repository content. Treat proxy nodes as infrastructure you do not control: avoid sending secrets, and rotate credentials if you think one has been exposed.

One distinction matters throughout the steps below: Clash Verge’s system proxy switch and terminal proxy variables are not the same setting. The system proxy helps applications that honor the operating system’s proxy configuration. Environment variables help command-line tools and libraries that read them. TUN mode can capture more application traffic, but it does not make every application, DNS request, or corporate policy behave identically. Use the least broad method that works for your machine.

2. Check Clash Verge before changing your shell

Open Clash Verge and confirm that the client is running, a profile is selected, and the profile has loaded successfully. Select a working node or a policy group whose current choice is known to be reachable. If the profile contains groups, inspect the group selection rather than assuming that the first node shown is the one handling traffic. A proxy process can be running normally while a group still points to an unavailable or unsuitable route.

Next, find the local port values shown in your Clash Verge settings. The mixed port commonly accepts both HTTP and SOCKS-style traffic, but its number is configurable; 7897 is only an example, not a guaranteed default. Some profiles or installations expose separate HTTP and SOCKS ports. Use the value displayed by your own client, and check whether the listener is bound to the loopback interface. A local endpoint such as 127.0.0.1:7897 means the proxy is expected on this computer, not on a remote server.

Turn on the system proxy only if you want applications that use the operating system setting to follow Clash. This can make browser testing convenient, but it does not guarantee that a shell process uses that proxy. If you use TUN mode instead, confirm that it is enabled and that the profile’s routing and DNS settings are functioning. TUN is useful when an application ignores proxy variables, but it affects a broader set of traffic and may interact with another VPN, endpoint security software, or a company-managed network.

Before involving Claude Code, test the local listener itself. On macOS or Linux, a command such as curl -I --proxy http://127.0.0.1:7897 https://example.com checks whether curl can make an HTTP request through that local proxy. On PowerShell, use curl.exe if the shell resolves curl to a PowerShell alias. Replace the sample port with the one shown in Clash Verge. A successful response means this test reached the destination through the listener; it does not yet prove that Claude Code uses the same settings or that the intended policy was selected.

If the command reports that it cannot connect to the proxy, stop here and check the port, client status, and local listener before editing Claude Code configuration. If it connects but the remote request times out, inspect the selected node, mode, DNS behavior, and routing rules. Keep one change at a time and repeat the same test; otherwise, it becomes difficult to tell which adjustment fixed or introduced the failure.

3. Pass proxy settings to the Claude Code process

For a terminal-first setup, export proxy variables in the shell that will launch Claude Code. Set both lowercase and uppercase forms because tools differ in which spelling they inspect. The following example uses an HTTP-compatible mixed port. Substitute your actual local address and port:

export HTTP_PROXY="http://127.0.0.1:7897"
export HTTPS_PROXY="http://127.0.0.1:7897"
export ALL_PROXY="socks5h://127.0.0.1:7897"
export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export all_proxy="$ALL_PROXY"

Do not copy the SOCKS line blindly if your listener does not accept SOCKS connections. If Clash Verge exposes only an HTTP proxy port, use that HTTP endpoint for the variables instead. If you use a SOCKS listener, the socks5h scheme asks the proxy to resolve the destination hostname, whereas socks5 may resolve it locally first. That difference can matter when local DNS answers are restricted or inconsistent. Match the scheme to the actual listener and your network requirements.

To apply the variables for just one run rather than changing your shell profile, prefix the command with them:

HTTP_PROXY="http://127.0.0.1:7897" \
HTTPS_PROXY="http://127.0.0.1:7897" \
claude

This is a useful diagnostic because it avoids leaving a proxy setting active in every later terminal session. Once it works, you can decide whether to add the exports to a shell startup file such as ~/.zshrc or ~/.bashrc. If you do, add them only to the account and environment that needs them. To stop using that proxy, run unset HTTP_PROXY HTTPS_PROXY ALL_PROXY http_proxy https_proxy all_proxy in the current shell, or remove the lines from the startup file and open a new terminal.

On PowerShell, set environment variables in the current session before starting Claude Code:

$env:HTTP_PROXY = "http://127.0.0.1:7897"
$env:HTTPS_PROXY = "http://127.0.0.1:7897"
$env:ALL_PROXY = "socks5h://127.0.0.1:7897"
claude

Environment variables are inherited when a process starts. If you launch an editor from the desktop and later open its integrated terminal, that terminal may have an older environment snapshot. Close and reopen the terminal or fully restart the editor after changing variables. The same principle applies to long-lived shells, IDE extension hosts, and background agents: a child process usually inherits its parent’s environment at launch, not whatever you set in a different terminal afterward.

For a temporary connectivity check, ask curl to use the same proxy and request a public HTTPS endpoint. Then start Claude Code from that same shell. Do not put an API key, session token, or other credential into a command-line example or shell history just to test transport. If authentication fails after the network request succeeds, diagnose account sign-in separately from proxy connectivity; changing node rules will not repair an expired or unavailable account session.

4. Verify routing rules and confirm which path is used

A proxy variable only directs a process to Clash Verge’s local listener. It does not decide which remote node handles the destination. That decision belongs to the active Clash profile and its rule order. In Clash Verge’s connection view, reproduce one request and inspect the destination hostname, matched rule, policy group, and selected node. This gives you concrete evidence instead of relying on a generic list of hostnames copied from an old forum post.

Claude Code can involve more than one network operation: account or sign-in flows, API requests, and supporting service calls may reach different hosts. Product endpoints can change, and the exact set can depend on the current version and account flow. Use the connection records from the failing session as your source of truth. If a request is routed by a broad rule such as a geographic fallback or a final catch-all, decide whether that behavior is intentional before adding a narrower rule.

When the profile uses rule-based routing, place any specific rules above broad rules that would otherwise match first. A rule that appears below a catch-all may never be evaluated. Avoid creating an unrestricted wildcard for an entire vendor domain simply because one request failed; that can send unrelated services through a different route and make future diagnosis harder. Record the observed hostname, timestamp, matched rule, and result, then make the smallest change that addresses the failing connection.

Use Clash Verge’s connection log to distinguish common outcomes. A connection marked DIRECT may mean the request bypassed the selected node because a rule matched earlier than expected. A request assigned to a proxy group but failing to establish a connection points toward the node, remote reachability, or protocol path. A successful connection followed by an application-level error suggests that the network path exists, while authentication, permissions, service availability, or account state may still be the problem.

Test in a controlled order: verify the local listener with curl, verify a public HTTPS request through the listener, start Claude Code in the same shell, then inspect the corresponding connection entry. If the shell test succeeds but Claude Code traffic does not appear in Clash’s logs, the CLI may not be reading the variables, may be using a different child environment, or may be connecting through another networking layer. Try a fresh terminal and compare with TUN mode only if needed. If you switch modes, repeat the same test rather than changing the profile and the environment at the same time.

Keep latency in mind as well as reachability. A node can complete a short HTTP request but perform poorly during a longer interactive session. Choose a stable route with acceptable response time rather than selecting a distant exit solely because it once returned a successful status code. Streaming and repeated tool requests make inconsistent latency especially noticeable. For work devices, preserve required corporate routes and follow your organization’s rules for source code and authentication traffic.

5. Troubleshooting and frequently asked questions

Why does my browser work while Claude Code fails?

The browser may use the operating system’s proxy setting while the terminal process relies on environment variables—or neither may share the same routing path. Confirm that the shell has the variables you expect with a safe check such as echo $HTTPS_PROXY on macOS or Linux, or $env:HTTPS_PROXY in PowerShell. Then test the local proxy with curl from that shell. If the browser works but curl cannot reach the listener, investigate the port or shell configuration before changing the Claude Code installation.

Which port and proxy scheme should I enter?

Use the port shown in your own Clash Verge settings. There is no universal port number across configurations. Use an HTTP URL for an HTTP or mixed listener, and a SOCKS URL only when a SOCKS listener is available. A scheme mismatch can look like a remote service outage even though the local client is healthy. If you are unsure, confirm the listener in the client and test it with curl before launching Claude Code.

How can I tell a routing error from an account error?

A connection refusal to 127.0.0.1 usually means the local listener or port is wrong. A timeout after a connection is assigned to a node points more toward the route or remote reachability. If the request reaches the service and returns an authentication or permission message, the transport may be working and the account flow needs separate attention. Check the exact error and the matching Clash connection record; do not share credentials or full debug logs that contain tokens.

Should I use TUN mode instead of environment variables?

Use TUN mode when the process does not honor proxy variables and you need system-level traffic capture, provided that your platform, profile, and organization permit it. It can simplify applications with their own networking stack, but it broadens the traffic affected and can introduce DNS, VPN, or security-software interactions. For a single CLI, explicit variables are often easier to inspect and reverse. Choose one approach, test it, and document what you changed.

Some general-purpose VPN apps make it easy to switch the whole device on or off, but that can be too coarse for a development workflow: browser traffic, package downloads, private Git hosts, and Claude Code may all need different treatment. Clash Verge offers a local proxy endpoint, selectable routing policies, and connection logs, so you can inspect the actual path and keep unrelated traffic on its intended route. If you want to try the client or compare supported platforms, download Clash.

Ready to get started?

Choose a compatible client, verify your local proxy port, and route CLI traffic with a setup you can test.