Fix Claude Code Connection Errors and API Timeouts in Clash

Why Claude Code Can Time Out While Your Browser Works Explained

When Claude Code cannot connect through Clash, it is tempting to assume the selected node is broken. That is only one possibility. The browser and the terminal may take different network paths: a browser can honor the operating system’s proxy setting while a terminal process connects directly, uses a proxy variable from an old shell session, or follows a custom API endpoint configured for work. A working claude.ai tab therefore does not prove that Claude Code can reach the API.

For typical Anthropic API access, the hostname to check first is api.anthropic.com. Sign-in or account flows can also involve Anthropic web properties, and an organization may route requests through a managed gateway or a custom base URL. The exact destinations depend on how Claude Code is installed and configured, so use the live connection log and your own environment settings rather than adding a large list of guessed domains to a rule set.

Symptoms can look similar even when the causes differ: startup hangs, authentication never completes, a prompt sits at “Connecting,” a request fails only after streaming begins, or an error reports a timeout despite successful browser browsing. A timeout is a transport symptom, not a diagnosis. It can come from a missing terminal proxy, a rule that sends the request to DIRECT, DNS behavior that hides the original hostname, a slow or unstable node, or an upstream service response that is not a network timeout at all.

Keep the test narrow: change one variable at a time. First verify that the local Clash listener accepts a request, then confirm which rule and outbound it uses, and only then adjust DNS or the subscription. Replacing a profile before collecting evidence can discard the clue you need.

Identify Whether It Is Routing, Authentication, or an API Response in Detail

Start by recording the exact error text, the time it occurred, and what Claude Code was doing: initial sign-in, refreshing credentials, sending the first prompt, or continuing a long response. Also note whether the same request works with Clash disabled, through a different node, or from another network. Do not paste API keys, OAuth tokens, full authorization headers, or subscription URLs into a public issue or an unredacted log. Error codes and hostnames are usually enough to narrow down the path.

Next, test the API hostname from the same terminal in which Claude Code fails. In macOS or Linux, use curl -v https://api.anthropic.com/. In PowerShell, use curl.exe -v https://api.anthropic.com/ so the command invokes curl rather than PowerShell’s historical alias. A response such as HTTP 401, 404, or 405 can still show that DNS, TCP, and TLS reached a server; it does not mean the API request is authorized or that the endpoint is intended for a browser GET. A connection timeout, name-resolution error, or TLS handshake failure points to a different layer.

Compare that result with an explicit request through the local Clash HTTP proxy. Replace the example port with the HTTP or mixed port shown in your client:

curl -v --proxy http://127.0.0.1:7890 https://api.anthropic.com/

If the direct test fails but the explicit proxy test reaches an HTTP response, Clash’s listener and a usable outbound are available; the likely gap is that Claude Code’s process is not using that listener. If both tests fail, inspect the rule match, DNS result, selected node, and connection log before changing the application. If curl succeeds through Clash but Claude Code still times out, focus on the environment inherited by Claude Code, its configured endpoint, and any authentication or application-specific error.

Interpret status codes carefully. A 401 or 403 generally means the server received the request but rejected its credentials or access. A 429 indicates a rate or quota response, not proof that the proxy is offline. A 5xx response may reflect an upstream service or gateway problem. A 529-style overload response, when returned, is also distinct from a TCP timeout. Preserve the status and a sanitized request timestamp when reporting an issue, but never include secret headers.

Check Clash Rules, DNS, and the Selected Node Made Clear

Open the live connections or traffic panel in your Clash client while reproducing one failure. Filter for anthropic or the exact hostname shown by the error. Check whether a connection appears, which rule matched, and which outbound or proxy group was selected. If no matching connection appears, Claude Code may be bypassing the local listener, using a different hostname, or failing before it attempts the API request. If it appears as DIRECT unexpectedly, the problem is likely rule order or the active profile rather than the quality of the proxy node.

Rules are evaluated in order. A broad rule such as GEOIP,CN,DIRECT or a catch-all final rule can take effect before a narrower API rule if the narrower entry is placed too low. For a controlled test, add a narrowly scoped hostname rule near the top of the effective rules, before broad geographic or fallback rules. The target must be a proxy group that actually exists in the loaded configuration; PROXY is only an example name and may not be present in your profile.

rules:
  - DOMAIN,api.anthropic.com,Your-Proxy-Group
  - DOMAIN-SUFFIX,anthropic.com,Your-Proxy-Group
  - GEOIP,CN,DIRECT
  - MATCH,Your-Default-Group

Do not blindly copy the whole example. Some profiles are generated by a provider and overwritten on update; others use rule providers, a script, or a client-side override mechanism. Make the test in a persistent rules or mixin layer supported by your client, or use a temporary override that you can remove. If the log shows a custom company gateway rather than api.anthropic.com, write and test a rule for the hostname that is actually in use.

DNS can complicate this check. In fake-IP mode, the core may return a synthetic address and rely on its own DNS mapping to recover the domain for rule matching. If the application uses an external resolver, a secure DNS feature, or a custom hostname, the connection may not match the rule you expected. Compare the hostname in the application configuration with the connection log; do not add a raw IP rule unless you have verified that the destination is stable and understand how the profile resolves it. When testing DNS changes, adjust one setting at a time and restore the original value if the result gets worse.

Finally, test a second node from a different network route or region. Prefer a node that can sustain a long TLS connection, not merely one with the lowest ping to a generic speed-test endpoint. Claude Code streams responses, so a node that handles a short request but drops idle or sustained connections can still fail halfway through a response. Avoid switching an automatic group repeatedly during a single test; record the chosen node so each comparison is meaningful.

Set the Proxy for the Terminal Process Under the Hood

System proxy mode often covers applications that read the operating system’s proxy settings, but many command-line tools do not automatically inherit them. Confirm the local HTTP or mixed port in Clash’s settings. Then configure the shell environment before starting Claude Code. The following examples use a common local port; replace it with the value shown by your client.

  1. Confirm the listener. In Clash, verify that the HTTP or mixed port is enabled and that the client is running. Use the explicit curl test from the previous section to check that the port accepts requests.
  2. Set proxy variables in macOS or Linux. In the same shell session, run export HTTPS_PROXY=http://127.0.0.1:7890 and export HTTP_PROXY=http://127.0.0.1:7890. Some tools also recognize lowercase names, so if the application still bypasses the proxy, set https_proxy and http_proxy to the same local address.
  3. Set proxy variables in PowerShell. Run $env:HTTPS_PROXY="http://127.0.0.1:7890" and $env:HTTP_PROXY="http://127.0.0.1:7890" in the window from which you will launch Claude Code.
  4. Start a fresh Claude Code process. Environment variables are inherited when a process starts. Close the old process and launch it from the configured shell; changing a variable in a separate terminal will not alter a process that is already running.
  5. Repeat the same test and inspect the log. Confirm that the API connection appears in Clash and uses the intended rule and group. If it still does not appear, check whether a launcher, IDE, service, or custom runtime is starting Claude Code with a separate environment.

For a temporary test, set variables only in the current terminal rather than adding them immediately to a global profile. This keeps the change easy to undo and helps distinguish a shell-proxy issue from a persistent configuration problem. To remove the variables from a macOS or Linux shell, run unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy. In PowerShell, run Remove-Item Env:HTTP_PROXY,Env:HTTPS_PROXY; remove lowercase variables too if you set them.

Do not point an HTTPS proxy variable at an HTTPS URL by assumption. Clash’s local HTTP proxy usually accepts an address beginning with http://, even when the destination website uses HTTPS. The proxy establishes a tunnel for the destination connection. Use the protocol and port documented by your client, and do not expose a local proxy listener to an untrusted network.

Use Logs to Fix the Actual Cause Explained

After each test, read the Clash connection entry and the sanitized Claude Code error together. A log entry with the expected domain, a matching proxy rule, and a selected outbound confirms that terminal traffic reached Clash. If the outbound fails during connection establishment, test another node and check whether the client reports a timeout, reset, or TLS error. If the request reaches the server but Claude Code reports an authentication error, changing DNS or enabling TUN is unlikely to help; recheck the account, API key, organization policy, or configured gateway instead.

  • No entry in Clash: Verify proxy variables in the launching shell, the listener address and port, and whether an IDE or wrapper starts its own child process. A browser proxy setting alone may not apply to the terminal.
  • Entry is marked DIRECT: Check rule order, the active profile, and whether an earlier rule or provider rule wins. Move a narrow domain rule above broad fallbacks using the configuration method your client supports.
  • Entry uses the intended proxy but times out: Test a second stable node, check for packet loss or frequent group switching, and compare a short curl request with a longer response. A successful handshake does not guarantee a stream will remain alive.
  • DNS or certificate error: Check the resolved hostname, Clash DNS mode, system clock, and any TLS inspection software. Do not disable certificate verification as a workaround; it weakens security and can conceal the real fault.
  • HTTP 401, 403, or 429: Treat it as an application, access, or quota response unless the logs show a separate transport failure. Confirm that credentials are valid and that your account or organization permits the requested service.

TUN mode is a fallback when the application does not honor proxy variables and you need Clash to capture traffic at the network-interface level. Before enabling it, confirm that your client supports TUN, grant the required system permissions, and check for conflicts with VPNs, security software, or another proxy client. TUN can capture more traffic, but it does not repair a bad rule, invalid credentials, or an unhealthy node. Start with the explicit proxy-variable test because it is easier to inspect and reverse.

If you use an enterprise gateway or a custom API base URL, confirm that the hostname and TLS certificate match the organization’s instructions. A rule for api.anthropic.com will not route a request sent to a private gateway. Likewise, an old environment variable or shell startup script can silently direct traffic to a retired endpoint. Review only the relevant variable names and endpoint settings, redact their values before sharing logs, and avoid printing secrets to a terminal recording.

Frequently Asked Questions in Detail

Why does Claude work in my browser but Claude Code time out? Explained

The browser may use the operating system proxy while the terminal process connects directly. Set the local Clash proxy variables in the shell that launches Claude Code, then confirm that the live connection log shows the API hostname and expected outbound. Also check whether the browser and CLI are using the same account and endpoint.

Do I need TUN mode for Claude Code? in Brief

Not necessarily. If Claude Code honors HTTP_PROXY and HTTPS_PROXY, a local HTTP or mixed proxy listener is often sufficient. Consider TUN only when the process bypasses proxy variables or you need broader system-level capture, and first check permissions and conflicts with other network tools.

Which domain should I add to Clash rules? in Detail

Start with the hostname shown in the live connection log or configured API endpoint. api.anthropic.com is a useful first check for direct API traffic, but authentication flows, managed gateways, and future service changes can involve other hostnames. Prefer a narrow, verified rule over a large copied domain list.

Should I replace my subscription when one Claude Code request fails? Notes

No. First compare an explicit curl request through the local listener, inspect the matched rule and outbound, and try one different node. Replace or refresh a subscription only when its configuration is actually missing, invalid, or incompatible—not as the first response to a terminal-specific timeout.

Some competing proxy setups make terminal troubleshooting unnecessarily opaque: a browser extension may route only browser tabs, while an older client or manually edited profile can leave command-line traffic outside the proxy without an obvious warning. Clash gives you inspectable rules, selectable outbounds, and connection logs, so you can distinguish a capture problem from a node or authentication failure before changing your whole setup. If you want a client and setup path that make those checks easier to follow, you can choose a Clash client and apply the targeted tests above.