Claude Code runs in a terminal, so getting it to use a Clash proxy is not quite the same as selecting a proxy in a browser. The terminal process must inherit the right proxy environment variables, Clash must be listening on a compatible local port, and the active profile must route the service’s connections through a usable node. This guide walks through those pieces in order: import and check a profile, configure the shell environment, verify routing, and narrow down common connection timeouts. Service access can vary by region, account eligibility, and network conditions; a working proxy alone does not guarantee that a particular account or service is available.

Understand the Connection Path

When Claude Code starts, it makes network requests from the process running in your terminal. A typical connection path looks like this:

  1. Your shell starts Claude Code and passes it environment variables.
  2. Claude Code reads the proxy settings supported by its runtime and sends requests to the local proxy address.
  3. Clash accepts the connection on a local port, evaluates the active profile’s rules, and selects a proxy group or direct route.
  4. The selected node attempts to reach the destination. DNS handling, remote availability, and the service’s own access policies can all affect the result.

Each step can fail independently. A browser may work because it has its own proxy setting while Claude Code receives no proxy variables. Conversely, a shell may point at a Clash port that is not listening, or the profile may send the relevant domain to DIRECT. A useful troubleshooting approach is therefore to test the chain one layer at a time rather than repeatedly changing nodes at random.

For a straightforward terminal setup, use a Clash HTTP or mixed port. The mixed port accepts HTTP proxy connections as well as SOCKS connections, while a dedicated HTTP port is suitable for applications that use HTTP proxy environment variables. Check the actual port displayed in your client or in the active configuration; do not assume that every installation uses the same default.

Keep the first test simple: Confirm that Clash is running, identify its local HTTP or mixed port, and try a request through that port before launching Claude Code. This separates a proxy-listener problem from an application or account problem.

Also distinguish the local proxy from the remote node. The address in a shell variable is normally a loopback address such as 127.0.0.1, which points to Clash on the same computer. It is not the address of a remote server in your subscription. If Clash runs on another device, use that device’s reachable LAN address only when the listener is deliberately configured to accept connections from the network, and protect that listener appropriately.

Import and Check a Clash Profile

Open your Clash client, add the profile or subscription through the client’s normal import workflow, and select that profile. A profile can contain nodes, proxy groups, DNS settings, and routing rules; importing it does not necessarily mean it is active. Check the client’s profile status and make sure a usable proxy group is selected. If your profile requires an update, refresh it and wait for the update to complete before testing.

Next, find the local port settings. Depending on the client, the option may be called mixed port, HTTP port, or ports. A simplified configuration might resemble the following:

Example Local Listener Settings
mixed-port: 7890
allow-lan: false
bind-address: 127.0.0.1
mode: rule
log-level: info

This is an illustration, not a replacement profile. Keep your client’s existing DNS, rules, proxy groups, and provider settings unless you understand why they need to change. In particular, avoid replacing a subscription configuration with a short example that omits its nodes or routing policy. If you edit a configuration manually, make sure the selected client supports the fields you use; Clash-compatible clients and Mihomo-based clients can differ in supported options and interface labels.

With rule-based routing enabled, the selected proxy group matters. Some profiles expose groups such as Proxy, Auto, or a service-specific group. Choose a working option in the client’s proxy or dashboard view, then inspect the connection list while making a test request. If a request appears as DIRECT, the shell may be connected to Clash correctly but the profile’s rules have chosen a direct route. If it appears under a proxy group, note which node handled it and whether the connection completed.

Do not expose the controller unnecessarily: A Clash external controller is a management API, not the proxy port. Keep it bound to the local machine unless remote administration is specifically required, and never use the controller address as HTTP_PROXY.

Before moving on, record the local port and confirm that the client shows a running core. If the client has a built-in connection test, use it as a preliminary check, but do not treat a successful latency test as proof that Claude Code can connect. A latency probe can test a different destination, rule, protocol, or node from the one used by the application.

Set Proxy Variables for the Terminal

Most command-line programs recognize some combination of HTTP_PROXY, HTTPS_PROXY, and their lowercase equivalents. For a local Clash HTTP or mixed port at 7890, set the variables in the same terminal session from which you will start Claude Code:

macOS, Linux, and Bash-Compatible Shells
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"

claude

Replace 7890 with the HTTP or mixed port configured in your client. The scheme in these variables describes the connection from the application to the local HTTP proxy. For an HTTP proxy, the value commonly begins with http:// even when the destination is an HTTPS website; the client uses the proxy’s CONNECT method to establish the secure destination connection. Do not change it to https:// unless your local proxy listener itself is configured to accept TLS.

In PowerShell, use the equivalent process-level variables before launching the application:

Windows PowerShell
$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_PROXY

claude

Process-level settings apply to programs started from that shell; they do not automatically alter every application on the computer. This is useful when you want only terminal tools to use the proxy. If you need the variables in every new shell, add them to the appropriate shell startup file, such as ~/.zshrc or ~/.bashrc, then open a new terminal or reload that file. On Windows, persistent user environment variables can be set through system settings, but a temporary PowerShell test is easier to undo and helps avoid changing unrelated applications.

Some tools also read ALL_PROXY, often for SOCKS proxies. Do not point it at an HTTP-only port with a SOCKS scheme. If you choose to test a SOCKS listener, use the actual SOCKS port and the scheme expected by the tool, commonly socks5://. Support varies by application and runtime, so start with the HTTP or mixed port unless you have a specific reason to use SOCKS.

Use NO_PROXY (or lowercase no_proxy) only for destinations that should bypass Clash, such as local development services. An overly broad entry can unintentionally bypass the proxy for a domain you are trying to test. Keep exclusions precise, and remember that applications may interpret domain suffixes, ports, and comma-separated entries differently.

Verify the Proxy and Routing

First inspect the variables in the same terminal session. On macOS or Linux, run env | grep -i proxy; in PowerShell, inspect them with Get-ChildItem Env:*proxy*. Confirm that the values contain the intended loopback address and port, and look for stale variables pointing to a different client or a proxy that is no longer running.

Next, test a basic HTTPS request through the local listener. If curl is installed, you can specify the proxy explicitly so the test does not depend on how that particular build handles environment variables:

Explicit Proxy Test
curl -I --proxy http://127.0.0.1:7890 https://example.com

A successful response shows that curl reached the destination through a proxy connection, but it does not prove that the service Claude Code needs is accessible. If the test fails immediately with a connection-refused message, check the local port, whether Clash is running, and whether the listener is bound to the address you used. If it hangs or reports a timeout, inspect the Clash log and connection list to see whether the request reached the core and which route was selected.

Then start Claude Code from the same terminal and watch the Clash client’s live connections. Compare the observed domain and route with your expectations. A connection that never appears may indicate that the application did not inherit or honor the variables, that a different process launched it, or that the request failed before reaching the proxy. A connection marked DIRECT points toward rule selection rather than a missing local listener. A connection assigned to a proxy group but failing there points toward node reachability, DNS, or remote service behavior.

ObservationLikely LayerNext Check
Connection refused immediatelyLocal listenerConfirm Clash is running and the port matches the client setting.
Request is shown as DIRECTProfile routingReview the matched rule and selected proxy group.
Proxy group is selected, but request times outNode or destinationTry another available node and inspect Clash logs.
curl works, Claude Code does notApplication environmentLaunch it from the tested shell and verify variable inheritance.
Only some requests failService, DNS, or policyCompare domains and routes; check account and regional availability.

When sharing diagnostic output, remove subscription URLs, credentials, tokens, account identifiers, and other sensitive values. A proxy variable can reveal local network details, while a profile may contain private access information. You usually need to share only the client type, operating system, local listener type, sanitized error text, and whether the request appears in Clash’s connection view.

Diagnose Timeouts Without Guesswork

A timeout is a symptom, not a diagnosis. It can occur because the local client is unreachable, the chosen node cannot establish an outbound connection, a DNS lookup is delayed or incorrect, or the remote service does not accept the request. Start by noting when the failure occurs: before any connection appears in Clash, after a route is selected, or only after a long wait. That timing narrows the problem more reliably than repeatedly changing unrelated settings.

If the local proxy test fails immediately, return to the listener configuration. Check whether the port changed after an update, whether another application is occupying the expected port, and whether the client is configured for loopback-only access. If the test reaches Clash but stalls, inspect the active node and the log entry for the failed connection. A proxy group may still be selected even when its current node is unavailable, so try a different known-working node and repeat the same test.

If only certain destinations fail, inspect the profile’s rules and DNS behavior. Confirm that the relevant hostname is not being sent directly by a domain, suffix, process, or IP rule. If rules depend on resolved IP addresses, DNS results can affect the eventual match; domain-based rules may make the intended route easier to verify. Avoid changing DNS mode as a first response. Change one setting at a time, test again, and keep a note of the original value so you can revert if the result gets worse.

Also check for conflicting proxy settings. A terminal may already inherit a proxy from a shell startup file, development tool, container, or remote session. Having different uppercase and lowercase variables can create confusing results if a program prefers one form. Temporarily remove stale values, set both forms consistently, and launch Claude Code from a fresh terminal. If you use an IDE terminal, compare it with a standalone terminal; the IDE may start a different shell or pass a different environment.

Finally, separate network access from service eligibility. A successful request to a generic website proves neither that Claude Code’s required endpoints are reachable nor that your account, location, or service plan is eligible. If Clash shows successful connections to the relevant destinations but the application returns an access or authentication error, follow the service’s current account and availability guidance rather than weakening security settings or assuming that a different proxy node will solve it.

A repeatable troubleshooting sequence: verify the listener, test one request explicitly through it, confirm the selected route in Clash, launch Claude Code from the same shell, and then compare the application error with the Clash log. Change only one variable at a time.

Once the terminal can reach the local Clash listener and the connection view confirms the expected route, keep the setup minimal: use a known-good profile, a clearly identified local port, and shell variables that apply only where you need them. This makes future failures easier to isolate and avoids changing system-wide settings unnecessarily. If you still need to install or update a client, compare the available platform options and follow the setup steps for your operating system.

Get Started

Take Full Control of Your Traffic with Clash

Available on Windows, macOS, Linux, Android, and iOS. Flexible rules, simple setup, ready to use.

Download Free View Setup Guide →