Fix Claude Code Connection Timeouts With Clash Proxy Settings

Why Claude Code connection timeouts often point to Clash

If Claude Code opens normally but hangs during authentication, pauses while sending a prompt, or ends with a connection timeout after several minutes, the problem is not necessarily your API key or the model service. In many environments, the real failure sits between the terminal and the proxy: the shell does not know which port Clash is using, a rule sends Anthropic traffic through DIRECT, or the selected node cannot sustain a long HTTPS streaming session.

Searches such as Claude Code timeout, Claude Code proxy setup, and Clash Anthropic connection failed usually describe the same operational situation. A browser may load ordinary websites because it follows the system proxy, while a terminal process launched from a different shell, IDE, container, or task runner uses no proxy at all. Even when the terminal reaches Clash, an imprecise rule set can route api.anthropic.com to an unsuitable policy group.

This guide focuses on a repeatable troubleshooting loop for Clash Verge Rev, Clash Verge, and other Mihomo-based clients. You will identify the failure layer, confirm the local proxy ports, inspect live connections, test the Anthropic endpoint independently, and then make the smallest configuration change that improves reliability. The goal is not to force every application through a tunnel. It is to give Claude Code a predictable path while keeping local development services and approved internal domains on DIRECT.

Classify the symptom before changing YAML

A timeout is a description of elapsed time, not a diagnosis. Claude Code can report a similar message when DNS resolution fails, when the TCP connection never reaches Clash, when TLS negotiation is interrupted, or when a proxy node stops forwarding a long response. Start by recording exactly when the failure occurs and what still works on the same machine.

One particularly useful comparison is a browser-based Anthropic page versus the terminal. If both fail at the same time, investigate the upstream service, account status, node health, or local network first. If the browser succeeds and Claude Code fails, focus on process-level proxy settings. If Claude Code succeeds for short prompts but fails during larger responses, do not immediately add more domain rules; first compare nodes and connection behavior in Mihomo.

Also distinguish a network timeout from a model response delay. A process that receives HTTP headers and then waits for generated content has already passed several network stages. A process that cannot establish a connection at all has a different problem. Capture timestamps, the command used, the active Clash mode, and the selected policy group before restarting everything. That evidence makes the next change measurable instead of speculative.

Check the Anthropic hostnames and rule path

Claude Code may contact more than one hostname depending on its release, login flow, API mode, telemetry behavior, and supporting services. Do not build a permanent rule list from a random forum post without checking your own logs. Open the Mihomo or Clash Connections view, start a fresh Claude Code request, and filter for domains containing anthropic. The visible connection rows tell you which hostname was contacted, whether it used a proxy policy, and whether the connection was accepted or repeatedly closed.

The main API hostname commonly seen in integrations is api.anthropic.com. Authentication, console, update, or auxiliary requests may use other hostnames. A rule that covers only one endpoint can therefore create a misleading partial fix: the first request passes through the intended group, but login refreshes or follow-up calls are classified differently. The correct response is to observe the failing session, identify the required hostnames, and add narrowly scoped rules only when the evidence supports them.

Rule order matters because Clash evaluates rules from top to bottom. A broad GEOIP, MATCH, or regional rule placed before a specific domain rule can capture traffic before the intended policy is reached. In Rule mode, look for the matched rule label in the connection details. If the row shows DIRECT when you expected an AI or proxy group, the timeout may simply be a routing decision rather than a broken node.

For a controlled test, temporarily select Global mode and choose a known working proxy group. Run one small Claude Code request and then return to Rule mode. If Global mode consistently works while Rule mode fails, the test does not prove that Global mode is the best permanent setting. It proves that the local client, selected node, and upstream service can communicate when policy matching is removed from the equation. Use that result to repair the specific rule path instead of leaving all traffic globally proxied.

DNS behavior deserves separate attention. Mihomo configurations may use fake-IP, redirection, or normal hostname resolution depending on the client and profile. A stale resolver, a local DNS filter, or a split DNS policy can make one hostname resolve differently inside the terminal and inside Clash. When the Connections panel shows repeated failed hostname attempts or an unexpected destination IP, compare the client’s DNS mode and the active profile. Avoid changing several DNS features simultaneously; otherwise you will not know which adjustment solved the problem.

Configure the terminal so Claude Code can reach Clash

The most common mistake is enabling the system proxy in Clash and assuming every terminal program will inherit it. System proxy support and environment-variable support are related but not identical. Desktop applications often consult operating-system settings, whereas command-line tools may read HTTPS_PROXY, HTTP_PROXY, or their lowercase equivalents. Some tools also use their own configuration files or ignore proxies completely.

First identify the mixed or HTTP proxy port displayed by your Clash client. Do not assume it is always 7890; users frequently change it, and different clients ship with different defaults. If your profile exposes a mixed port, it can normally handle both HTTP-style proxy requests and HTTPS destinations. Confirm the address is local, usually 127.0.0.1 or localhost, and verify that the port is listening before testing Claude Code.

Set variables for the current shell session

On a Unix-like shell, export the variables in the same terminal session that launches Claude Code. Use the port shown in your client rather than copying the example blindly:

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

On Windows PowerShell, the equivalent session variables can be set with:

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

These commands affect the current process and child processes. They do not automatically configure a GUI-launched IDE, an already running shell, a service manager, or a container. If Claude Code is started by an editor task, reopen the editor after setting the variables or define the variables in the editor’s integrated-terminal environment. If it runs through Docker, systemd, a CI runner, or a remote SSH session, configure the environment at that execution boundary instead of only on your laptop.

Now validate the variables before launching the application. Check that the value uses the correct port and that there is no accidental whitespace, quotation mark, or old proxy URL. If you maintain a NO_PROXY list, keep it conservative. Localhost, private development services, and internal domains may belong there, but adding broad public suffixes can silently bypass the proxy for the very API traffic you are trying to diagnose.

Run a simple HTTPS request through the proxy and compare it with the same request without proxy variables. The exact endpoint and authentication method depend on your account and client version, so do not paste a live API key into shell history or public logs. The purpose of this test is to establish whether the process can create a TLS connection through the local Clash port. A successful generic HTTPS test does not guarantee Claude Code is configured correctly, but a failure here means it is premature to debug application-level settings.

After changing proxy variables, close and relaunch Claude Code. Long-lived processes preserve old environment values, connection pools, and DNS results. Restarting only the terminal tab may not be enough when an IDE, daemon, or wrapper process launched the client earlier.

Separate routing success from node stability

A correct rule can still lead to a poor experience if the selected node is overloaded, geographically unsuitable, or unreliable for long-lived HTTPS streams. Claude Code often produces requests that remain open longer than a normal web page load. A node may appear fast in a download test yet reset an HTTP/2 stream, impose an aggressive idle timeout, or become unstable when several tools share the same subscription connection.

Use the Clash dashboard to compare at least two or three permitted, reputable nodes from the same policy group. Keep the test fair: use the same prompt, the same shell variables, and the same Rule-mode configuration while changing only the node. Observe connection establishment time, time to first response, whether output continues smoothly, and whether the connection closes after an apparently random interval. One successful request is not enough evidence; repeat short and moderately long prompts so intermittent failures become visible.

• High latency before any output: inspect the node’s reachability, DNS path, and current load.
• Fast start followed by repeated resets: suspect stream handling, congestion, or a node-side timeout.
• Only one policy group fails: compare its members and fallback behavior instead of rewriting all rules.
• Failures during network changes: check whether Wi-Fi roaming, sleep mode, or a changing interface interrupts the local tunnel.
• Different results on IPv4 and IPv6: test whether the active profile prefers an address family that the node handles poorly.

Do not compensate for an unstable node by adding endless retries. Retries can multiply API requests, create confusing duplicate operations, and make rate limits harder to interpret. Prefer a policy group with sensible health checks and failover, but verify that the fallback nodes are genuinely usable for the Anthropic traffic. A health check that only downloads a tiny page may not reflect the behavior of a long Claude Code exchange.

TUN mode can help applications that ignore environment variables, but it is not automatically a better answer for a terminal client. It changes the scope of interception, may interact with antivirus or corporate endpoint controls, and can route local development traffic unexpectedly. Enable it when you have confirmed that Claude Code bypasses the ordinary proxy and when you understand the client’s bypass rules. For a process that already honors HTTPS_PROXY, explicit environment configuration is often easier to audit.

A repeatable recovery checklist

When the timeout returns, follow the same order rather than toggling every Clash feature. This sequence keeps the fault domain small and leaves an audit trail:

1. Record the symptom: note the command, timestamp, prompt size, active mode, selected node, and the exact error text.
2. Check the local listener: confirm Clash is running and that the configured mixed or HTTP port matches the terminal variables.
3. Inspect live connections: find the Anthropic hostname in Mihomo Logs or Connections and confirm whether it is using the intended policy.
4. Run a narrow HTTPS test: test connectivity from the same shell or process boundary that launches Claude Code.
5. Compare modes carefully: use Global mode only as a diagnostic control, then return to Rule mode and repair the matching rule.
6. Compare nodes: test a second permitted node when short requests work but longer streams reset.
7. Restart the right process: relaunch Claude Code, the IDE task runner, or the container that retained old environment values.
8. Change one setting at a time: avoid changing DNS, TUN, rules, ports, and node groups in one restart cycle.

Keep credentials out of screenshots and logs. When sharing diagnostics with a team, redact API keys, subscription URLs, authorization headers, usernames, and unique request identifiers where appropriate. A useful report can include the hostname, rule result, policy group, timing, and sanitized error without exposing secrets.

Once the connection is stable, document the working arrangement: Clash client and version, profile name, mixed port, relevant domain rules, shell environment, and selected policy group. This small record prevents a future update from turning a solved timeout into another guessing exercise. Review the profile after subscription updates because providers can reorder rules, rename groups, or change DNS defaults even when your local client has not changed.

Why deliberate Clash routing is useful for Claude Code

For Claude Code, the practical advantage of Clash is visibility. A simple all-or-nothing VPN can hide whether the terminal bypassed the tunnel, whether an endpoint matched the wrong route, or whether one node is resetting streams. Clash exposes the policy decision, connection destination, and selected group, so you can distinguish a shell configuration mistake from an upstream transport problem. Its rule-based approach also lets local package registries, internal Git servers, and development containers remain on approved direct paths while Anthropic traffic follows the policy you have tested.

Other proxy tools may be easier for a first click, but they can become restrictive when a developer needs per-domain rules, multiple node groups, live connection inspection, or a predictable Mihomo-compatible profile across Windows, macOS, and Linux. For example, a fixed system-wide VPN may route a private staging hostname through an unnecessary relay, while a minimal environment export may not help an IDE task launched outside that shell. Clash does not remove the need for correct credentials, a reliable upstream service, or responsible network policy, but it makes the Claude Code path observable and adjustable; if you are looking for a cross-platform client that can turn these timeout checks into a repeatable workflow, Download Clash for free and browse freely →