Why Claude Code can time out while Clash says it is connected
If Claude Code hangs, reports a connection timeout, or stops while sending a request, a connected Clash client does not prove that the CLI is using the proxy. Clash may be running normally while your terminal process connects directly, a rule sends the relevant hostname to DIRECT, or the selected proxy node cannot sustain the request. The useful question is not simply “Is Clash on?” It is “Which process made this connection, what route did Clash choose, and did the connection stay healthy long enough to finish?”
This distinction matters because Claude Code runs in a terminal environment. A browser may use the operating system’s proxy setting, while a shell command-line program may rely on environment variables, its own network library, or traffic capture through TUN. Your browser can therefore open a website while Claude Code stalls. Conversely, a working terminal proxy does not prove that every background process, editor integration, or child process has inherited the same settings.
Start by reproducing one failure and observing it in Clash’s Connections or Logs view. Look for the destination hostname, the process or source address when available, the selected rule, and the proxy group or node. Interface names vary across clients, including Clash Verge, Clash Verge Rev, and other Mihomo-based applications, but the diagnostic goal is the same: establish whether the request appeared and how it was routed before changing several settings at once.
Also separate a network timeout from an account or application error. A delayed connection, a stalled TLS handshake, or a request that never reaches a response points toward the path between Claude Code and the service. An immediate response that identifies authentication, permissions, or usage limits is a different problem. Read the complete error and note when it occurs; a generic “request failed” message alone does not identify the cause.
Check the proxy variables in the terminal that launches Claude Code
When a command-line client supports conventional HTTP proxy variables, the variables must be present in the environment of the process that launches it. Setting them in a different terminal tab, a shell configuration file that was not reloaded, or a graphical operating-system proxy panel may not affect the existing process. If you start Claude Code from an IDE, a task runner, a remote shell, or a service, that launcher may have a different environment from your interactive terminal.
First inspect what the current shell has actually exported. On macOS or Linux, you can check the common variable names with:
env | grep -i proxyOn Windows PowerShell, inspect the process environment with:
Get-ChildItem Env:*proxy*For a local Clash HTTP or mixed port, a typical shell setup could look like this, but the port must match the value shown in your own client:
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"In PowerShell, the equivalent process-level settings are commonly written as:
$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_PROXYThese are examples, not universal port values. Check Clash’s active port configuration before copying them. An HTTP proxy listener can usually be addressed with an http:// proxy URL even when the destination request uses HTTPS: the client asks the proxy to establish a tunnel to the destination. Do not change the URL scheme to https:// unless your configured listener actually supports TLS on the proxy connection.
After setting variables, launch Claude Code from that same shell and test again. If the CLI still fails, confirm the variables are inherited by the launch path you are using. An IDE opened from the desktop may not inherit settings added later to a shell startup file. For a reliable comparison, close the existing process, open a new terminal after updating the environment, inspect the variables there, and start a fresh Claude Code session.
Check NO_PROXY as well. If it contains a broad entry that matches the destination or a parent domain, the client may bypass the proxy even when HTTPS_PROXY is set. Do not remove necessary local exclusions blindly: local services and development endpoints may need direct access. Instead, temporarily test with a minimal, appropriate NO_PROXY value and compare the resulting connection in Clash. Keep credentials and subscription URLs out of terminal output you plan to share.
Verify the actual rule and destination in Clash
Once Claude Code is running with the expected proxy environment, observe a fresh request in Clash. If no corresponding connection appears, the CLI may not be using that listener, may have failed before creating a network connection, or may be using a different transport path. If a connection does appear, inspect its destination and the rule result. A connected client can still select DIRECT for a destination, and a broad rule earlier in the configuration can take precedence over a more specific rule placed later.
Do not begin by adding a long list of guessed hostnames from old forum posts. Service infrastructure can change, and a failed Claude Code operation may involve more than one request. Use the live connection record to identify the hostname that stalled. Then check whether your configuration has an applicable rule for that hostname and whether the rule points to a usable proxy group. If you use a provider profile, some rule sections may be managed remotely; understand whether you are editing a local override, a rule provider, or the generated configuration before making changes.
- If the connection is DIRECT: determine why the matching rule selected direct access. Check rule order, rule mode, and any rule that matches a domain suffix, process, or IP range before adding a narrower exception.
- If the connection uses the intended proxy group: check which node the group selected and whether that node remains available. A correct rule can still lead to an unhealthy or overloaded server.
- If the hostname is unexpected: record the observed name and compare it with the requested operation. A sign-in flow, API request, or other feature may use different destinations; diagnose the connection actually shown rather than assuming one hostname covers every step.
- If Clash shows no matching activity: test the listener separately and check whether Claude Code was launched from the shell where the proxy variables were set.
A brief comparison with Global mode can be useful as a diagnostic, provided it is permitted on your network and you understand that it changes routing for more traffic. If Claude Code works only in Global mode but fails in Rule mode, that is evidence to investigate policy matching or rule order. It is not a reason to leave Global mode enabled indefinitely. Restore your intended mode after the test, then make the narrowest appropriate rule change and verify it against a new connection.
When editing rules, change one thing at a time. Reload the configuration if your client requires it, start a new request, and confirm that the connection’s rule and route changed as expected. This method makes it much easier to undo a bad override than changing the rule set, DNS settings, and proxy group simultaneously.
Test node health, latency, and long-lived connections
Some failures look like rule problems but are actually node problems. A server may pass a quick latency check and still drop sustained connections, struggle under load, or perform poorly on the route to a particular service. Claude Code requests can involve more than a short page load, so judge a node by whether the relevant operation completes—not only by a fast indicator in the proxy group.
In Clash, select a known working proxy group or node for a controlled test and watch the same request again. Compare outcomes with the current selection, keeping the configuration and environment unchanged. If one node consistently works and another consistently stalls, record that result and avoid treating the issue as a Claude Code setting until the node or provider route has been investigated. If every node fails in the same way, return to the environment, rule, and listener checks rather than repeatedly switching servers.
Use simple, safe connectivity tests to separate basic reachability from an application-level failure. A request to a service’s public website can show that DNS and an HTTPS path work in general, but it does not prove that Claude Code’s exact request, authentication flow, or streaming behavior will work. Avoid sending credentials or API keys in improvised diagnostic commands, and do not paste sensitive request headers into logs or support tickets.
Watch for timing patterns. An immediate failure may suggest a refused local connection, a bad listener port, or an immediate policy rejection. A request that waits for a long time before failing may indicate a stalled route, an overloaded node, packet loss, or a connection that is not being proxied as expected. A request that starts successfully and then stops during a longer operation can point toward an unstable connection or a timeout in an intermediate component. These clues are not proof by themselves, but they help choose the next test.
If a node recently changed or a provider has rotated its endpoints, refresh the profile only through a source you trust and review the result. Do not expose a subscription URL to obtain help. A client update can also change listener defaults or routing behavior, so after an update verify the active port, mode, and selected profile rather than assuming old values still apply.
When TUN mode can help—and what it does not fix
TUN mode can help when a command-line program does not honor the proxy variables or when traffic from a particular launch environment never reaches the local HTTP proxy listener. It captures eligible system traffic at a lower networking layer and routes it through Mihomo according to the configured policy. This can make traffic from applications that lack proxy support visible to Clash, but it does not automatically correct a wrong rule, a bad node, or an application-level authentication error.
Before enabling TUN, confirm that terminal proxy variables and the listener port are correct. Then check your client’s TUN status, required system permissions, and any operating-system approval prompts. Exact setup differs between Windows, macOS, and Linux and between client releases; use the controls and instructions for your installed build rather than copying settings intended for another platform. If another VPN, network filter, or virtual adapter is active, it may conflict with traffic capture or alter the route. Test with only the network components you need, where practical.
After enabling TUN, generate a new Claude Code request and inspect Clash’s connection view. Confirm that the request is now visible and that the selected rule and proxy group are the ones you intend. If TUN makes the connection appear but the request still times out, the remaining issue is likely elsewhere in the path: rule outcome, node health, DNS behavior, or the remote service response. If enabling TUN changes unrelated applications’ connectivity, revert it and investigate the interaction before leaving it enabled.
Do not use TUN as a blanket substitute for understanding your routing. It can affect traffic beyond Claude Code and may change how local networks, development services, or other VPN software behave. Keep a note of the original settings, make one change at a time, and return to the previous state if the test creates new failures. For a machine that must follow organization policies, follow those policies rather than attempting to bypass network controls.
Frequently asked questions
Claude works in my browser. Why does Claude Code still time out?
The browser and the CLI may use different proxy settings. A browser can follow the operating system’s proxy configuration while Claude Code relies on the environment inherited from its launching shell, or on traffic captured by TUN. Check the variables in the exact terminal or IDE that starts the CLI, then look for the CLI’s connection in Clash. A working browser is useful evidence that some network path is available, but it does not confirm that the terminal request took that path.
Claude Code works in Global mode but fails in Rule mode. What should I change?
That difference points toward rule matching, rule order, or the proxy group selected by a matching rule. Use Clash’s live connection record to identify the destination and the rule that handled it. Then make a narrow, reversible adjustment and test again in Rule mode. Global mode can help isolate the cause, but it routes more traffic and should not be treated as the default fix without considering your network requirements.
Do I need TUN mode for every Claude Code installation?
No. If Claude Code honors the proxy variables and the request appears in Clash with the correct route, a local proxy listener may be sufficient. TUN is worth testing when the CLI ignores those settings or traffic from its launch environment is not captured by the listener. It can affect other applications, so verify the impact and the resulting route before relying on it.
Should the HTTPS proxy variable start with https://?
Not necessarily. The variable name describes the kind of destination traffic the client is proxying; the URL scheme describes the connection to the proxy itself. A common Clash HTTP listener is configured with an http:// URL even when used for HTTPS destinations. Match the scheme and port to the listener shown in your Clash client, and do not assume that an HTTPS proxy listener exists unless you configured one.
Choose a controlled fix instead of changing everything
Some one-click VPN clients make it difficult to see whether a particular terminal process is using a proxy, which rule decided its route, or which server handled the connection. Clash provides a more observable workflow: set the CLI’s proxy environment deliberately, inspect rule matches in live connections, test a specific node, and use TUN only when the application is not following the ordinary proxy path. If you want a client for that kind of step-by-step troubleshooting, start by checking the supported options for your platform and the setup that fits your network.