Claude Code runs in your terminal, so enabling Clash’s system proxy does not always route its requests. A desktop browser may work while Claude Code reports a timeout, connection reset, or failed API request because the shell process has no proxy variables, Clash routes the relevant domain directly, or the selected node cannot reach the service. This guide shows how to check each layer in order: confirm the Clash listener, pass its address to Claude Code, verify routing rules, and test the connection without exposing credentials.
Understand the Connection Path
A Claude Code request travels from the terminal process to a local proxy listener, through the Clash rules engine, and then to the selected proxy node or a direct connection. A failure at any point can look like an application problem. Separating these layers makes troubleshooting much faster.
Clash’s system-proxy switch is usually a setting for applications that read the operating system’s proxy configuration. Command-line programs do not necessarily inherit that setting. Claude Code is launched by a shell, and the shell environment is what matters for proxy variables. In addition, a working local listener does not guarantee that the request uses a proxy: Clash may match the destination against a rule that sends it to DIRECT.
| Layer | What to verify | Typical symptom if it fails |
|---|---|---|
| Clash core | The core is running and the expected profile is active | No local connection, or the port refuses connections |
| Listener | The HTTP or mixed port and bind address are correct | Claude Code cannot connect to the configured proxy address |
| Shell environment | HTTPS_PROXY and, where needed, HTTP_PROXY point to the listener | Browser works but terminal requests time out |
| Clash routing | The destination matches a proxy rule and an available proxy group | The request connects, but the service is unreachable or blocked |
| Remote service | The selected node can reach the required service endpoints | Other proxied sites work, but Claude Code still fails |
Before changing configuration, note the active Clash profile, the client’s HTTP or mixed-port number, and the exact error text. Common defaults include ports such as 7890 or 7897, but the value shown in your own client is authoritative. Do not assume that a port from an online example matches your installation.
Prepare Clash and Check the Listener
Open Clash Verge, Clash Verge Rev, or another compatible client and confirm that the core is running and the intended profile is selected. Look for the client’s HTTP or mixed-port setting in its general, port, or network settings. A mixed port commonly accepts both HTTP proxy and SOCKS connections; for Claude Code, using the HTTP proxy form is a straightforward first test. If the client exposes only separate HTTP and SOCKS ports, use the HTTP port for the commands below.
Also check whether the listener is bound to the loopback interface. For a terminal running on the same computer, an address such as 127.0.0.1 is normally appropriate. Avoid changing the bind address to 0.0.0.0 just to make a local application work: that can expose the proxy listener to other devices on the network. If you are running Claude Code inside a container, virtual machine, or remote development environment, its 127.0.0.1 may refer to that environment rather than the host running Clash. In that case, use an explicitly reachable host address and protect the listener with suitable network controls.
Test whether the local port accepts connections before starting Claude Code. On macOS or Linux, use the following command, replacing 7890 with the port displayed by your client:
nc -vz 127.0.0.1 7890
On Windows PowerShell, the equivalent check is:
Test-NetConnection 127.0.0.1 -Port 7890
A successful result means something is listening on that address and port; it does not prove that the listener is an HTTP proxy or that the remote route works. If the connection is refused, recheck the port, confirm the core is running, and make sure another profile or application has not changed the listener setting. If the port check succeeds but an HTTP test fails, confirm that you selected the HTTP or mixed port rather than a SOCKS-only port.
Next, inspect the active mode and routing behavior in the Clash client. In Rule mode, the destination is evaluated against the profile’s rules from top to bottom, and the first matching rule determines the policy. A rule for a broad domain suffix or a final DIRECT rule may take precedence over a later rule you added. In Global mode, traffic is sent through the selected global policy, which can be useful as a temporary diagnostic but is not required for a permanent setup.
If you maintain the profile yourself, add a narrowly scoped domain rule for the service only when your existing rules do not already route it appropriately. Place the rule before any broader rule that would capture the same destination, and point it to a proxy group that actually exists in the profile. Do not replace a managed subscription profile wholesale merely to add one rule; use the client’s supported override or merge mechanism so routine profile updates do not erase your change.
Set Proxy Variables for Claude Code
Set the proxy variables in the same terminal session from which you launch Claude Code. Use the address and port of the local HTTP or mixed listener. The HTTPS variable is important because the API endpoints use encrypted HTTPS connections. Setting both uppercase and lowercase forms can help when a tool or dependency reads one spelling rather than the other.
For macOS, Linux, or a compatible shell, run:
export HTTPS_PROXY=http://127.0.0.1:7890 export HTTP_PROXY=http://127.0.0.1:7890 export https_proxy="$HTTPS_PROXY" export http_proxy="$HTTP_PROXY" claude
For Windows PowerShell, set the variables in the current PowerShell process and then start Claude Code from that same window:
$env:HTTPS_PROXY = "http://127.0.0.1:7890" $env:HTTP_PROXY = "http://127.0.0.1:7890" $env:https_proxy = $env:HTTPS_PROXY $env:http_proxy = $env:HTTP_PROXY claude
These are temporary session settings: closing the terminal removes them. That is useful while diagnosing the route. To check that the values are present without printing unrelated environment variables, inspect only the proxy entries:
printenv | grep -i proxy
In PowerShell, use Get-ChildItem Env:*proxy*. If the variables are absent in the terminal where Claude Code runs, setting the system proxy in a graphical client will not fix that shell process by itself. If they are present but the request still bypasses the proxy, check whether a wrapper script, development environment, or application-specific configuration is overriding them.
For a persistent setup, add the exports to the startup file for the shell you actually use, such as ~/.zshrc or ~/.bashrc, and open a new terminal. On Windows, user-level environment variables can be configured in the operating system settings, but a temporary PowerShell assignment is safer until the route has been verified. Avoid writing proxy variables into a shared project file or committing them to source control.
Do not put API keys, account tokens, or proxy credentials into the proxy URL or shell configuration unless your proxy specifically requires authentication and you understand how the value is protected. Environment variables can be inherited by child processes and may appear in diagnostic output. For a local Clash listener, the URL generally needs no username or password.
ANTHROPIC_BASE_URL serves a different purpose: it changes the API base URL when you intentionally use a compatible gateway or alternate endpoint. It is not the normal way to point Claude Code at a local Clash proxy. Leave it unset unless your organization or service provider has given you a specific base URL. Changing it unnecessarily can send requests to the wrong endpoint or make authentication fail even when the network route is healthy.
Verify Routing and Diagnose Failures
Test the local proxy independently of Claude Code. With curl, explicitly name the proxy and request the service’s API hostname. A response such as an HTTP error or an authentication-related response can still demonstrate that DNS, TLS, and the network path reached the server; the goal of this check is connectivity, not successful account authentication.
curl -I --proxy http://127.0.0.1:7890 https://api.anthropic.com/
Watch the Clash connection list or traffic view while the test runs. Confirm that the request appears and note the matched rule, policy group, and selected node. The exact hostname contacted can vary by feature, sign-in flow, or product version, so use the connection list and error details rather than assuming every request goes to only one domain. Authentication or account setup may involve additional service endpoints.
Once the standalone request reaches the remote host through the expected policy, launch Claude Code from the same shell where the proxy variables are set. If curl succeeds but Claude Code fails, compare the environments of the two processes, check the complete Claude Code error, and confirm that no separate terminal profile or editor task is launching it with a different environment. An integrated terminal may not inherit variables added after the editor was opened; restart the editor or start the command from a terminal with the variables already set.
| Observed result | Likely cause | Next check |
|---|---|---|
| Connection refused on the local port | Wrong port, stopped core, or listener bound elsewhere | Compare the client’s active port and bind address; verify the core is running |
curl cannot connect to the proxy | Wrong proxy type or address, or the listener is unreachable | Use the HTTP or mixed port and test the local listener again |
curl works, but Claude Code times out | Variables are missing from Claude Code’s process, or its launch environment differs | Launch both from the same shell and inspect only the proxy variables |
Clash shows the request using DIRECT | A rule matched a direct policy or the current mode bypasses the proxy group | Review rule order and the matched policy in the active profile |
| Other proxied sites work, but the API test fails | The selected node or route cannot reach the service, or a required endpoint is not covered | Try another available node and inspect the connection log for the actual destination |
| Connection succeeds but authentication fails | Network access works; credentials, account state, or endpoint configuration may be the issue | Resolve the account or authentication error separately from proxy connectivity |
Timeouts and DNS errors are not interchangeable. A timeout often points to an unavailable route, an overloaded node, or a blocked connection. A name-resolution failure suggests checking the core’s DNS settings and the route used for the destination. A TLS or certificate error deserves separate attention: check the system clock, avoid installing untrusted certificates, and do not disable certificate validation as a workaround. If the client reports a rate limit, permission issue, or invalid credential, changing proxy ports is unlikely to solve it.
For a controlled comparison, keep the proxy variables unchanged and switch only the Clash policy or node. If one node works and another fails, the difference is likely upstream connectivity rather than Claude Code’s local configuration. If the result changes when you temporarily use Global mode, the rule path is a strong suspect; return to Rule mode afterward and correct the narrow rule or policy rather than leaving all traffic globally proxied by default.
A reliable setup is usually simple: keep Clash’s local listener active, set the HTTP proxy variables only in the environment that launches Claude Code, and verify that the relevant destination is assigned to a working proxy policy. Once the standalone request and Claude Code both succeed, you can make the shell setting persistent if that fits your workflow. If you still need to configure a client or install Clash, use the relevant setup guidance for your platform, then repeat the same listener, environment, and routing checks rather than changing several variables at once.