Claude Code With Clash Verge: Setup Guide For Reliable Access

Claude Code brings AI-assisted programming to the terminal, but a successful installation does not automatically mean that its requests can reach the service reliably. A browser may work while the terminal reports a timeout, a proxy error, or an authentication failure. The reason is usually simple: Claude Code is a command-line process, and it does not always inherit the same proxy path as your browser.

This guide uses Clash Verge as the local proxy client and focuses on a stable beginner workflow. You will import and select a profile, confirm the correct local port, configure the terminal environment, test the connection in layers, and then narrow down failures from the logs. The examples apply mainly to Clash Verge and Clash Verge Rev with the mihomo core; menu names can differ slightly between releases.

1. What You Need Before Setup

There are four separate pieces in this setup: Claude Code, Clash Verge, a working Clash profile, and a shell that can pass proxy settings to command-line programs. Treat them separately. Installing Claude Code proves only that the local program is available; it says nothing about whether the service endpoint is reachable from your current network.

• Claude Code installed locally: use the installation method recommended for your operating system and confirm that the command can be found from a new terminal session.
• Clash Verge or Clash Verge Rev installed: the client provides the graphical controls, while the mihomo core handles connections, rules, DNS, and proxy protocols.
• A valid profile: the profile must contain proxy nodes and proxy groups. A profile URL is an account credential, so keep it private.
• A reachable node: a node that appears in the list is not necessarily usable. It must pass a latency or connectivity test and accept the protocols configured in the profile.
• Permission to use the service: proxy configuration cannot replace account authorization, billing, regional availability, or the service provider's terms. A network success and an API authentication success are different checks.

The recommended starting point is Rule mode. It lets the profile decide which destinations use the proxy and which use DIRECT. If the profile's rules do not cover the Claude service domains correctly, you can temporarily use Global mode as a diagnostic comparison, then return to Rule mode after identifying the cause. Direct mode is useful only when you intentionally want to confirm that the local network path fails without Clash.

2. Configure Clash Verge in the Right Order

Do not begin by changing terminal variables. First make sure Clash Verge itself can carry traffic. This prevents a common mistake: troubleshooting three unknowns at once—the client, the node, and the shell.

1. Import the profileOpen the Profiles page, paste the subscription URL supplied by your provider, and update it. Confirm that the profile displays a proxy group and a list of nodes. If the update fails, fix that problem before continuing.
2. Select the profileClick the imported profile so that it becomes the active configuration. A profile that is present but not selected does not necessarily control the running core.
3. Choose a nodeOpen Proxies, locate the group used by the rules—often named Proxy, Select, or something similar—and choose a node. Prefer a nearby node with a stable test result rather than selecting only by its advertised speed.
4. Set Rule modeOn the main screen, select Rule. This is the normal daily mode for a profile that contains appropriate domain and IP rules.
5. Enable the local proxy listenerTurn on the system proxy if you want applications that honor the operating system proxy to use Clash automatically. This switch does not configure every terminal program, so the shell variables in the next section may still be required.

Clash Verge normally exposes a mixed port, HTTP port, or SOCKS port in its settings. The exact number is configurable and may vary between installations. Never assume that a port such as 7890 is correct: read the value shown in your client. A mixed port accepts both HTTP proxy and SOCKS-style client connections, while a dedicated HTTP port should be used with an HTTP proxy URL and a dedicated SOCKS port should be used with a SOCKS URL.

Replace PORT with the actual number displayed by Clash Verge. If the terminal reports connection refused, first check whether Clash is running, whether the listener is enabled, and whether the port is already occupied by another application. If the client is listening on an IPv6-only address or a non-loopback address, use the address shown in its settings; for a normal local installation, 127.0.0.1 is the usual endpoint.

3. Pass the Clash Proxy to Claude Code

Graphical applications can read the operating system proxy setting, but terminal programs commonly rely on environment variables. The most portable starting point is to set both uppercase and lowercase forms, because different libraries inspect different spellings. Use the HTTP form when pointing to a Clash mixed or HTTP listener.

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
export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export all_proxy="$ALL_PROXY"

For a SOCKS listener, change the value to a SOCKS URL:

export ALL_PROXY=socks5://127.0.0.1:SOCKS_PORT
export all_proxy="$ALL_PROXY"

On Windows PowerShell, the equivalent session-only commands are:

$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"
$env:http_proxy = $env:HTTP_PROXY
$env:https_proxy = $env:HTTPS_PROXY
$env:all_proxy = $env:ALL_PROXY

These commands affect only the current terminal process and programs launched from it. That is useful for testing because you can close the window and remove the settings without changing the whole operating system. Once the connection works, you may place the commands in your shell profile, such as ~/.zshrc, ~/.bashrc, or the PowerShell profile. Before doing so, make sure the port is stable and understand that every command launched from that shell may inherit the proxy.

To remove the variables from the current Bash or Zsh session, run:

unset HTTP_PROXY HTTPS_PROXY ALL_PROXY
unset http_proxy https_proxy all_proxy

In PowerShell, use:

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

Some tools also honor NO_PROXY or no_proxy. If that variable includes the service domain or a broad wildcard, the request may bypass Clash even though HTTPS_PROXY is set. Inspect the variable if behavior seems inconsistent:

echo "$NO_PROXY"
echo "$no_proxy"

Remove an accidental entry for the destination while testing. Do not use a broad bypass list unless you understand which traffic will leave the proxy directly.

4. Verify the Connection Layer by Layer

Run tests in order, from the local listener to the actual application. Each layer answers a different question. A successful first layer does not prove the next one, but a failed lower layer makes higher-level testing premature.

1. Check that Clash is listeningConfirm in Clash Verge that the mixed, HTTP, or SOCKS port is enabled. On systems with command-line tools available, a local connection test can reveal whether the port accepts connections.
2. Test a normal HTTPS requestUse a simple command-line request through the same proxy URL. For an HTTP listener, try curl -I -x http://127.0.0.1:PORT https://example.com. A response proves that the terminal can reach Clash and that Clash can establish at least one outbound connection.
3. Inspect the Clash logOpen Logs and repeat the request. Look for the destination, the matched rule, the selected proxy group, and any timeout or TLS message.
4. Start Claude Code from the same shellDo not test in one terminal and launch Claude Code from another before checking that both sessions contain the same environment variables.
5. Separate network errors from account errorsA timeout, refused connection, or DNS failure points toward the path. An unauthorized, invalid-token, or account-related response means the request reached a service endpoint and requires an authentication or account fix instead.

A request visible in Clash logs with the expected destination but a failed outbound connection usually indicates a node, rule, DNS, or upstream issue. A Claude Code error with no corresponding log entry usually indicates that the process did not use the Clash listener, the variable was not inherited, or the application uses a transport that the current configuration does not proxy.

When Rule mode is active, inspect the matched rule rather than assuming that every request follows the selected node. A domain may match DIRECT, REJECT, a different proxy group, or the final fallback. If Global mode succeeds while Rule mode fails, the problem is probably rule coverage or group selection, not necessarily the node itself. Return to Rule mode after adding or correcting the appropriate rule through the profile's supported override mechanism.

5. Improve Reliability Without Overcomplicating the Setup

Claude Code sends repeated requests while it reads project context, prepares prompts, receives responses, and sometimes performs several tool-related operations. A node that opens one web page may still perform poorly under a longer-lived API exchange. Reliability therefore depends on more than a single latency number.

• Choose stability over the lowest displayed latency. A node with 180 ms latency and frequent resets is worse for terminal work than a slightly slower node that maintains connections consistently.
• Use a dedicated proxy group if your profile supports it. Keeping development traffic in a predictable group makes logs easier to read and prevents an unrelated auto-test group from changing nodes during a request.
• Update the profile when nodes change. Providers may replace endpoints, ports, certificates, or group definitions. An old profile can leave you testing a node that no longer exists.
• Keep DNS behavior consistent. DNS failures can appear as connection failures. If the profile uses fake-IP or redirection features, do not mix several DNS interception tools without understanding which component answers the query.
• Use TUN mode only when necessary. TUN can capture applications that ignore HTTP and SOCKS environment variables, but it adds system-level routing, DNS, and permission variables. First try explicit proxy variables; enable TUN when the application cannot be configured otherwise.
• Watch for network changes. Switching between Wi-Fi, mobile tethering, corporate networks, and VPN software can invalidate an otherwise working route. Test again after each major network change.
• Keep the terminal and Clash time synchronized. Incorrect system time can cause TLS certificate validation failures, especially when the error mentions certificate validity or a handshake problem.

For a repeatable daily workflow, start Clash Verge, confirm the selected profile, choose a known stable node, set the shell proxy variables, run one lightweight HTTPS test, and then launch Claude Code. If the project requires a different proxy policy, use a separate shell or a clearly documented script rather than constantly editing global settings.

6. Diagnose Common Errors in Clash Verge and Claude Code

How to Read the Relevant Log Entry

Clear the log or note the current time, perform one action, and then inspect only the new lines. A useful entry normally tells you the protocol, source, destination, matched rule, and outbound. The important questions are: did the request enter the core, did the expected rule match, and did the selected group establish a connection?

INFO [TCP] 127.0.0.1:53124 --> api.example.com:443 match DomainSuffix(example.com) using Proxy

This example shows that a local process connected to the Clash listener, the destination was identified, the domain rule matched, and the request was assigned to the Proxy group. If the next line reports a timeout while dialing the node, change the node or investigate the upstream path. If the log instead shows DIRECT, the request bypassed the proxy according to the rule set. If no line appears, return to the environment-variable and application-inheritance checks.

7. A Practical Recommended Profile

For beginners, the following arrangement is easier to maintain than a collection of global switches and manually edited generated files:

1. Use a current profile in Clash Verge and keep the subscription URL private.
2. Select a stable node manually for the first Claude Code session.
3. Use Rule mode for normal work, with a proxy group that covers the service domains required by your account and client.
4. Use the Clash mixed or HTTP port as the value for HTTP_PROXY and HTTPS_PROXY.
5. Run a small curl test before launching Claude Code after a network or profile change.
6. Use the Clash log to confirm the route instead of judging success only from the terminal's final error message.
7. Switch temporarily to Global mode only as a comparison test. If Global works and Rule does not, fix the policy rather than leaving all traffic global.

Do not edit the profile file generated by the subscription unless you know how the client handles updates. Provider-generated content may be replaced at the next update. Use Clash Verge's supported override, script, or rule-management feature where available, and keep a short record of any custom rule so it can be recreated after a profile refresh.

8. FAQ

Why does Claude Code fail when my browser works?

The browser may use the operating system proxy, a browser extension, or its own connection settings. Claude Code is a separate process and may not inherit any of those settings. Set HTTPS_PROXY explicitly in the shell used to launch it, then confirm that the request appears in Clash Verge's Logs panel.

Should I use the HTTP port or the SOCKS port?

Start with the mixed or HTTP port because many command-line clients support HTTP CONNECT through HTTPS_PROXY. Use the SOCKS port only when the application or its networking library explicitly supports SOCKS5. The port number must be copied from your Clash Verge settings; it is not universal.

Should Global mode stay enabled for Claude Code?

No. Global mode is useful for a short diagnostic comparison because it sends all connections through the selected global group. It can also proxy destinations that should remain direct and consume more node bandwidth. Use Rule mode for daily work after confirming that the required service domains match the intended proxy group.

When should TUN mode be enabled?

Enable TUN when the application ignores proxy environment variables or requires system-level traffic capture. It is not the first fix for a wrong port, failed node, missing rule, or invalid credential. Test explicit proxy variables first; if there is still no Clash log entry, then evaluate TUN together with its permissions and DNS settings.

Download ClashAll-platform clients