Fix Claude Code Proxy Timeouts With Clash: CLI Setup Tips

Why Claude Code Times Out When Clash Works in Your Browser

It is possible for a browser to reach Claude successfully while Claude Code repeatedly reports a timeout, connection reset, or failed request. That difference does not necessarily mean the Clash node is down. A browser may be using the operating system’s system proxy, a browser extension, or a proxy setting managed by Clash, while a command-line program launched from a terminal may use a different route entirely.

Claude Code runs as a CLI process. Its network requests are made by the process and its runtime, not by the browser tab where you signed in. If the terminal does not inherit proxy settings, if Clash is not listening on the address configured in the shell, or if a routing rule sends the request to DIRECT, the CLI can fail even though ordinary websites load normally. The first task is therefore to identify which layer is failing instead of repeatedly switching nodes at random.

A timeout usually means that a connection did not complete within the expected period. It can result from a missing proxy variable, a wrong local port, a blocked destination, a slow or overloaded node, or a DNS problem. A fast authentication error is different: it often means the request reached a service, but credentials, account access, or another application-level check failed. Keep the exact error message and the time it occurred; those clues help separate transport problems from account problems.

Before troubleshooting, make sure the active Clash profile is loaded and the core is running. In Clash Verge or Clash Verge Rev, check the current system proxy and mixed-port settings. In other clients, locate the equivalent listener setting. The exact menu names vary, and the port is configurable; do not assume that every installation uses 7890. Mihomo can expose an HTTP, SOCKS, or mixed listener, but the shell variable must match a listener that is actually enabled. A mixed port accepts more than one supported proxy protocol; an HTTP-only listener should be addressed as an HTTP proxy.

1Check Proxy Variables in the Terminal

Start with the same terminal window from which you run Claude Code. Shell environment variables are inherited when a process starts, so changing a proxy setting in a desktop client does not always update an already-open terminal. Close and reopen the terminal after enabling the system proxy, or set the variables explicitly in the current session. Then inspect whether the variables are present and whether they point to the correct local port.

Inspect the Current Environment

On macOS or Linux, run:

On Windows PowerShell, run:

Look for both lowercase and uppercase forms. Many command-line tools recognize http_proxy, https_proxy, HTTP_PROXY, and HTTPS_PROXY, but behavior can vary between runtimes and versions. Setting both cases avoids a common mismatch. The value should include a scheme such as http://, not just an IP address and port. Use the port shown in your Clash client, and do not copy a port from an example without checking your own configuration.

If Clash exposes an HTTP or mixed listener on port 7890, a temporary macOS or Linux test can look like this:

Despite its name, https_proxy commonly contains the URL of an HTTP proxy. The HTTPS request is sent through that proxy using the HTTP CONNECT method; the traffic to the destination remains encrypted end to end. If your client exposes only a SOCKS listener, use a client and configuration that explicitly support the appropriate SOCKS URL scheme. When diagnosing, an HTTP or mixed listener is often the simplest option because it avoids uncertainty about whether the CLI runtime supports SOCKS proxy variables.

For a temporary PowerShell test, set the variables in the current session:

Replace the sample port if your Clash listener uses another value. These commands affect only the current terminal session and processes started from it; they do not permanently change Windows proxy settings. In PowerShell, launch Claude Code from that same window after setting the variables. A separately opened application, IDE, or terminal tab may have a different environment.

Test the Local Listener Before Running Claude Code

First check that something is accepting connections on the configured address and port. On macOS or Linux, you can use:

In PowerShell, use:

A response from the destination, including an HTTP status that is not a successful application response, can still show that DNS resolution, proxy negotiation, and a connection to the service completed. The test is not an authentication check and does not prove that every Claude Code endpoint or request will succeed. If the command immediately reports that it cannot connect to the proxy, verify the listener address, protocol, and port. If it hangs, inspect the Clash connection log and test a known-good node before changing Claude Code settings.

Some terminals or shells use startup files that override variables, while applications launched from a desktop icon may not read those files at all. If the temporary test works but the CLI launched another way does not, compare the environment of the two processes. Prefer setting the variables in the terminal or launcher that starts Claude Code rather than assuming that a system-wide proxy toggle is inherited by every application.

2Trace the Request Through Clash

Once the local proxy test reaches the destination, check whether Clash actually routes the CLI request through the intended policy group and node. Open the client’s connection view or Mihomo’s connection log, then start a fresh request from Claude Code. Look for the destination hostname, the matched rule, the selected policy group, and the final outbound node. The names and layout differ across clients, but the useful question is the same: did the request enter Clash, and where did the rule send it?

Claude Code may contact more than one hostname during startup and normal operation. The service API is a useful first point to check, but authentication, account features, and supporting services can involve additional requests. Do not assume that a single successful connection to one hostname proves that all required destinations are reachable. Conversely, avoid adding broad rules for unrelated domains without evidence from the connection log; unnecessary exceptions make the configuration harder to maintain.

In rule mode, a matching rule can direct a request to a proxy group, a specific node, DIRECT, or another policy. A browser may appear to work because its domains match one rule, while a CLI hostname matches a different rule or falls through to a final rule that sends traffic directly. If your current profile uses a rule provider or rule set, check its order and the final fallback policy as well as the visible custom rules.

This snippet is illustrative, not a complete configuration. AI must be the exact name of a policy group in your profile, and the group must have a usable node selected. If you do not have a group with that name, the configuration may fail validation. Add only the rules you need, keep them above broader rules that would otherwise match first, and check the client’s configuration test before applying edits. A profile managed by a subscription may be replaced on update, so use the client’s supported override, merge, or script mechanism when available instead of editing a generated file that will be overwritten.

Global mode can be a useful short diagnostic: if the CLI works in Global mode but fails in Rule mode, investigate rule matching and policy selection. It is not necessarily a good permanent fix. Global mode can send unrelated traffic through the proxy and may hide an overly broad or incorrectly ordered rule. Return to the intended mode after testing, then make a narrow rule change if the connection log confirms that a routing decision is the cause.

3Apply a Repeatable Fix and Verify It

Use a controlled test sequence so that each change answers one question. Start with Clash running and a known stable node selected. Confirm the listener address and port in the client. Open a fresh terminal, set the proxy variables for that session, and run the direct curl test. Then launch Claude Code from the same terminal and check the Clash connection view while a request is in progress. This sequence distinguishes an inactive listener from a shell inheritance problem, a routing error, or an unhealthy upstream node.

Make the Working Setup Persistent

If a temporary shell test resolves the issue, make the settings available in the normal way you launch the CLI. On macOS and Linux, you can add the required exports to the startup file for the shell you actually use, such as ~/.zshrc or ~/.bashrc. Then open a new terminal and verify the values again. Do not add a second set of conflicting values to multiple startup files; a stale export pointing at an old port can make later troubleshooting confusing.

For PowerShell, choose a user-level profile only if you want the settings available in each interactive session. If the port changes, update the profile or remove the obsolete values. For an IDE or another graphical launcher, consult its terminal or environment configuration: a child process may not inherit the same settings as a shell opened separately. Avoid placing proxy credentials in a shared script or committing them to a project repository.

Check Node and DNS Health

If the request appears in Clash and is assigned to a proxy node but continues to time out, test another node that is known to support the required destination. A node can pass a simple latency check and still fail on a particular service because of congestion, packet loss, upstream filtering, or an IP address that the service does not accept. Compare the same CLI request across a small number of reliable nodes rather than changing several settings at once. A consistent failure on one node and success on another points toward node quality or upstream behavior rather than shell configuration.

DNS problems can also produce confusing results. Check whether Clash logs show a resolved destination and whether the selected DNS mode is functioning as intended. Avoid replacing the entire DNS configuration as a first response: DNS settings can affect all applications, and a broad change may introduce new failures. If only a particular hostname fails, use the logs to confirm whether the hostname resolves, whether the connection reaches the proxy, and whether the selected rule is correct.

Finally, distinguish a transport timeout from a service response that arrives promptly. If Claude Code receives a response but reports an authentication, permission, account, or configuration error, verify the relevant application settings through the official product workflow. Do not put an API key into a proxy URL, terminal command history, or a public log as a workaround. Clash controls how traffic is routed; it does not repair expired credentials, grant account access, or change a service’s eligibility rules.

For a reliable everyday setup, keep the solution narrow: a verified local listener, proxy variables that are present in the CLI’s actual environment, a rule that sends the required request to a working policy group, and a node that remains stable. When you update Clash, Mihomo, a subscription, a shell, or the CLI itself, repeat the short verification sequence. Ports, inherited environments, rule sets, and node availability can change independently, so testing the request path is more dependable than relying on the browser’s status alone.

Download Clash