How Claude Code Uses Your Network
Claude Code runs in a terminal, but its network connection does not automatically follow the same path as a browser. A browser may already use Clash’s system proxy settings, while a command-line process can make direct connections unless you explicitly configure its environment or route its traffic through a system-level tunnel. This is why Claude Code can fail to sign in, hang while loading, or time out even when websites open normally in your browser.
It helps to separate the connection into three parts: the Clash client, which receives and routes traffic; the terminal environment, which tells command-line tools where to find a proxy; and the active network rules, which decide whether a connection goes through a proxy node or directly to the internet. A problem in any one of these layers can look like a Claude Code error.
This walkthrough uses a local HTTP or mixed proxy port as the starting point. Many Clash clients use port 7890 by default, but the value is configurable and may be different on your device. Check the client’s settings before copying the examples. The examples also use a proxy group named PROXY; your profile may call this group 🚀 Proxy, Proxy, or something else. Use the exact name shown in your configuration.
The Goal
Keep Clash running, make the terminal’s proxy endpoint reachable, and ensure Claude Code’s network requests follow a working rule and proxy group.
Important Distinction
A browser working through Clash does not prove that a terminal is proxied. Conversely, terminal proxy variables do not change the routing of unrelated applications. Test the exact terminal session in which you launch Claude Code.
1Prepare Clash and Confirm the Route
Start by opening your Clash client, such as Clash Verge Rev, Clash Verge, or another Mihomo-based client. Import or update a profile from a provider you trust, select a working node in the relevant proxy group, and confirm that the core is running. A profile can be imported successfully while its selected node is offline, so check the client’s connection status rather than relying on the profile name alone.
Next, find the local port settings. For a terminal application, an HTTP or mixed port is usually the simplest option. An HTTP proxy accepts HTTP proxy requests and HTTPS connections through the CONNECT method; a mixed port accepts both HTTP and SOCKS traffic. A SOCKS-only port should not be placed in an HTTP_PROXY variable unless the program specifically supports that proxy scheme. If your client exposes separate HTTP and SOCKS ports, use the HTTP port for the examples below.
Check the Local Proxy Port
In the Clash interface, inspect the port or inbound settings and note the actual value. If the client listens on 127.0.0.1:7890, applications on the same computer can reach it using that address. Some setups listen on 0.0.0.0 to accept connections from other devices; do not enable that exposure simply to make a local terminal work. Binding to all interfaces can make a proxy reachable from your local network, so keep the listener restricted unless you have a specific, secured reason to share it.
Check the client’s mode as well. In Rule mode, a request can reach Clash successfully and still be sent direct by a rule. Global mode sends traffic through the selected proxy group, making it useful as a short diagnostic test. Do not treat Global mode as the permanent fix: it changes routing for all traffic handled by Clash and can hide a missing or misplaced rule. Return to your preferred mode after testing.
Route Claude Domains in Rule Mode
If the terminal can reach the local port but Claude Code still fails in Rule mode, inspect the active profile’s rules. Add a targeted rule for Claude and Anthropic domains above a broad catch-all rule such as MATCH. In the following example, replace PROXY with the exact proxy-group name in your profile:
Many subscription profiles generate or refresh their rules, and manual edits may be overwritten on the next update. If your client supports profile overlays, merge rules, or a rules section in a local configuration, use that supported mechanism and verify the final active configuration. Keep the Claude-specific rules above rules that would otherwise send the same domains to DIRECT. A later rule cannot override an earlier match.
These domain rules are a starting point, not a guarantee that every service used by every Claude Code version is covered. Check Clash’s connection or log view while starting the CLI. If a relevant request is shown with a different hostname or policy, use the hostname and result in the log to diagnose the route rather than adding broad, unrelated domains. Avoid changing DNS, every profile rule, and the terminal environment at the same time; changing one layer at a time makes the cause much easier to identify.
2Set Proxy Variables in the Terminal
Many command-line applications recognize the conventional HTTP_PROXY and HTTPS_PROXY environment variables. These variables tell the process which local proxy endpoint to use; they do not turn Clash on, choose a proxy node, or guarantee that every dependency honors the variables. Set them in the same shell session where you will run Claude Code, using the port you confirmed in the client.
macOS and Linux
For a temporary test in a shell such as Bash or Zsh, run:
Use http:// in these values when pointing to a local HTTP or mixed proxy port. This describes the connection from the terminal to the local proxy; HTTPS destinations are then tunneled through that proxy. Do not change the scheme to https:// unless the local listener itself is configured to accept HTTPS-proxy connections. If your port is not 7890, substitute the correct port in both variables.
To apply the variables automatically to new interactive shells, add the relevant exports to your shell startup file, such as ~/.zshrc or ~/.bashrc, then open a new terminal or reload the file. Keeping the configuration in a shell-specific startup file is often preferable to setting it globally: it makes the behavior easy to inspect and limits the change to command-line sessions. If you only need proxy access for Claude Code, you can use a small launcher script instead of affecting every command you run.
To bypass the proxy for destinations that should remain local or direct, set NO_PROXY. For example, a local development service should generally not be sent through an external proxy:
Do not put a Claude hostname in NO_PROXY if your intention is to send it through Clash. Also remember that different programs may handle uppercase and lowercase variables differently. Setting both forms, as shown above, helps with compatibility, but it does not force software that ignores proxy variables to use them.
Windows PowerShell
In PowerShell, set the variables for the current session before starting the CLI:
These assignments last only for the current PowerShell process and its child processes. That is useful for testing because closing the terminal removes the temporary values. If you decide to make them persistent, configure them deliberately in your user environment and open a new terminal afterward; an already-running shell will not automatically inherit changed variables. To remove the temporary settings from the current session, run:
On Windows, Clash’s system proxy option and terminal environment variables are separate controls. The system proxy can help applications that consult Windows proxy settings, while explicit variables make the intended endpoint clear for a terminal process. If you use WSL, remember that Linux inside WSL may not be able to reach the Windows host through 127.0.0.1 in every network configuration. In that case, use the reachable host address for the WSL environment, and ensure the Clash listener accepts connections on that interface. Do not expose the listener broadly without understanding the security implications.
Pro Tip: Keep the Test Reproducible
First set the variables temporarily, launch Claude Code from that same terminal, and confirm the result. Only make them persistent after the local port, selected node, and rule behavior are verified.
3Troubleshoot Login Errors, Timeouts, and Failed Requests
When a connection fails, avoid immediately reinstalling Claude Code or replacing your whole Clash profile. Identify which part of the path is failing: the local listener, the terminal’s proxy variables, Clash’s selected route, the remote node, or the login flow. The table below maps common symptoms to the first checks worth making.
| Symptom | Likely layer | First check |
|---|---|---|
| Connection refused immediately | Local proxy endpoint | Confirm Clash is running and the configured port matches the terminal variable. |
| Browser works, terminal times out | Shell environment or CLI behavior | Print the proxy variables in the same shell and launch Claude Code from that shell. |
| Request appears as DIRECT | Clash rules | Check the matched hostname and rule order; place the intended Claude rule before a broader match. |
| Authentication page opens but sign-in does not finish | Browser handoff or session | Check whether the callback returns to the CLI and whether the browser and CLI use compatible routing. |
| Requests work intermittently | Node quality or network stability | Test another node in the same group and compare the Clash log results. |
Verify the Listener Before Changing Rules
If the terminal reports a connection-refused error, focus on the address and port first. A misspelled port, a stopped Clash core, or a proxy listening only on another interface can prevent the CLI from reaching the local service. Confirm the actual HTTP or mixed port in the client, then compare it character by character with the proxy URL in the shell. Do not substitute a SOCKS port into an HTTP URL unless you know the program supports that combination.
After the local connection is established, check the Clash connection log while starting Claude Code. Look for the requested hostname, the selected rule, and the proxy group or policy shown for the request. If you see the request but it is routed to DIRECT, correct the rule or its order. If it enters the expected group but fails, select a different node and retest. This distinction prevents you from wasting time editing YAML when the real issue is an unhealthy node.
Diagnose Login and Timeout Problems
Login can involve both the terminal and a browser. The CLI may open a browser for authentication, then wait for a callback or session result. If the browser can reach the sign-in page but the terminal remains stuck, check whether the login flow completed in the browser and whether the CLI returned to its prompt. If the browser and CLI are using different routes, a session can appear to start successfully but fail to complete. Keep the routing consistent during the login test, and avoid switching nodes midway through an authentication flow.
For a timeout, first try a short, controlled comparison: keep the same terminal variables and Clash rules, then switch only the selected node. If one node works and another does not, the problem is likely related to the node’s reachability, congestion, or service compatibility rather than the shell syntax. If every node fails but the Clash log shows no matching request, investigate whether the CLI inherited the variables or whether the application uses a different network path. Check the exact terminal in which the command runs; launching the CLI from a desktop shortcut, integrated development environment, or a different shell may give it a different environment.
If DNS seems suspect, use the Clash log and the active DNS settings to check how the relevant hostname is resolved. Avoid adding experimental DNS overrides as a first response. A DNS change can affect other applications and may make the results harder to interpret. Make one small change, restart the affected process if necessary, and repeat the same test. When sharing logs for help, remove access tokens, authentication codes, subscription URLs, and any private server details.
Choose One Routing Method Deliberately
There are two practical ways to make terminal traffic use Clash. Environment variables are targeted and easy to undo, making them a good first choice for Claude Code. A system-level TUN mode can capture traffic from applications that do not honor proxy variables, but it routes traffic at a broader level and can require administrator permission or additional network configuration. Do not enable TUN and add multiple overlapping workarounds at the same time unless you understand how the routes interact. Start with one method, confirm the connection, then add complexity only if the client’s logs show it is necessary.
Once Claude Code can connect reliably, keep the configuration as narrow as practical: use a known local port, maintain a working node, route only the required domains when using Rule mode, and document any custom rules so they can be restored after a profile update. This gives you a clearer troubleshooting path the next time a login, timeout, or network change interrupts a coding session.