Use Claude Code With Clash: A Terminal Access Setup Guide

Why Claude Code Needs Its Own Clash Proxy Setup Key Takeaways

Spin up with the smallest possible change. If your Clash client exposes a local HTTP or mixed port, configure Claude Code to use that listener and test a short request.

Claude Code brings Anthropic’s AI-assisted coding workflow into a terminal: it can inspect project files, suggest changes, work commands with your approval, and continue a conversation while you work. That makes it different from simply opening Claude in a browser.

A browser may already follow your operating system’s proxy setting, while a command-line process can spin up with no proxy configuration at all. When that happens, the browser signs in successfully but Claude Code hangs, reports a network fault, or cannot reach the model API.

Clash can help route this traffic, but it does not without you proxy every program on your computer. In system-proxy mode, Clash typically advertises a local HTTP or mixed proxy for applications that honor operating-system proxy settings. Countless terminal tools do not.

The key point:They may open a direct TLS connection unless they read proxy environment variables, or unless a TUN front end captures the connection. The practical question is therefore not only “Is Clash connected?” but also “Can this Claude Code process reach the Clash listener?”

There are as a rule several network stages to consider. Installing Claude Code may involve a package manager or an installer host. Signing in may open a browser and use an verification flow. Once authenticated, Claude Code makes requests to Anthropic services and may also contact supporting services for configuration or product functionality.

These stages can take different routes, so a successful package installation does not prove that sign-in or model requests will work. Likewise, successful browser sign-in does not prove the terminal process can entire its own API requests.

Let me put it this way:Only move to TUN mode if the application does not honor the proxy variables, another network component bypasses them, or you want broader system-level capture. This approach makes troubleshooting easier: it separates a proxy setting problem from a DNS, rule, credential, or service availability problem.

Prepare Clash and Choose a Route in Brief

Do not begin by adding every Anthropic-related domain it is possible to find to a large rule list. Endpoint names and supporting services can change, and a copied rule may be stale or broader than necessary. First reproduce the failure while watching Clash’s connection log.

Before changing shell settings, confirm that your Clash client is running and that its active profile has working nodes. Open the client’s settings and note the local HTTP or mixed-port.

A mixed port accepts both HTTP proxy requests and SOCKS traffic, but a conventional HTTP proxy variable are best off point to a listener that supports HTTP proxying. Do not assume that the port number is the same on every machine: it can be changed in the profile, client settings, or a merge override.

Concretely:Check the listener from the same computer that works Claude Code. A common local address is 127.0.0.1, but use the address shown by your client. If you use a remote Clash host, a container, or a virtual machine, loopback means that environment itself—not necessarily the desktop where the GUI is open.

In that situation, you must expose or forward the listener deliberately and protect it with firewall rules. A proxy port exposed to an untrusted network can allow other devices to use your connection.

Next, choose a routing policy. For an initial test, select a known working proxy group yourself fairly than relying on an unfamiliar automatic selection. If your profile supports domain rules, inspect the live connection view after a sign-in or short prompt.

Where this lands:The destination host, matched rule, and selected outbound provide better evidence than guessing which rule list are best off contain an endpoint. Add narrow rules only when the connection log shows that a specific request is being sent through the wrong route.

If no relevant connection appears, investigate whether the process is using the listener or whether TUN capture is needed. If a connection appears with a direct route, adjust the matching rule or proxy group. If it reaches the intended outbound but fails, examine response time, DNS, TLS, credentials, and service availability separately.

Configure Proxy Variables for the Terminal A Closer Look

Use NO_PROXY only for destinations that are best off bypass Clash, such as local development services you must reach straightforward. A broad bypass pattern can accidentally exclude a remote service from proxying. Likewise, a proxy variable does not guarantee that every dependency or child process will honor it.

For countless command-line applications, setting HTTP_PROXY and HTTPS_PROXY is the simplest way to point traffic at Clash. The values below use an example local HTTP listener on port 7890; replace the port with the one shown in your client.

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"

Do not skip this:These variables affect processes started from that shell, so close and reopen the terminal—or spin up a new shell session—after changing persistent settings.

The proxy URL begins with http:// even when the destination website uses HTTPS. In this arrangement, the client asks the local HTTP proxy to create a tunnel to the HTTPS destination; the remote connection is still encrypted with TLS.

Do not change it to https:// unless your local proxy listener itself is explicitly configured to accept TLS connections.

The key point:On macOS or Linux, the commands above apply to the current shell. To make them persistent, add the relevant exports to the configuration file used by your shell, such as ~/.zshrc or ~/.bashrc, then reload that file or open a fresh terminal.

$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

Avoid putting proxy settings in a project file that may be committed to version control. On Windows PowerShell, use session-scoped environment variables for a swift test:

Launch Claude Code from that same terminal session so it inherits the variables. If you launch it from an IDE, a desktop shortcut, a task runner, or a separate terminal profile, it may not inherit the environment you just configured. When in doubt, spin up Claude Code straightforward from the shell where you set the variables.

Let me put it this way:If your system or toolchain supports ALL_PROXY, you may also test it with an appropriate listener URL, but do not set it blindly: SOCKS and HTTP listeners use different URL schemes, and an incorrect scheme can make a working proxy appear broken.

A fair few applications use their own network library, ignore these variables, or spin up another process with a different environment. The Clash log is the quickest way to see whether the connections you care about arrived at the listener.

1. Confirm the listener: In Clash, verify the active HTTP or mixed port and make sure the client is running.
2. Set the variables: Use the example for your shell, replacing 7890 with your actual listener port.
3. Spin up Claude Code from that shell: Do not assume an already-open IDE or terminal has received newly added variables.
4. Watch the connection log: Work a small request and check whether the expected destination appears in Clash.
5. Test persistence separately: Once the temporary setup works, add it to your shell configuration and open a fresh session to verify it.

Test Sign-In and Model Requests in Order What Matters

For an initial setup, prefer a manual proxy-group selection over a response time-testing group that may switch nodes during your test. Once the workflow is trustworthy, it is possible to return to your normal group and observe whether automatic switching changes the result.

Test the connection in stages fairly than repeatedly reinstalling the CLI. First, confirm that the local listener is available and that a easy request through it can reach a destination you are permitted to access.

Concretely:Then launch Claude Code from the configured shell and entire sign-in. Finally, send a short prompt from a test directory. This order helps identify whether the failure is local to Clash, specific to the verification flow, or limited to model requests.

Verification may involve both the terminal and a browser. The browser can open successfully and entire its part of the flow while the CLI still cannot exchange or receive the resulting authorization information. Conversely, the terminal may reach the relevant service while the browser is using a different proxy route.

Keep the Clash connection view open during the entire sign-in process, including after the browser returns focus to the terminal. If the flow stalls, note which connections appeared and whether they used the intended outbound.

Where this lands:After sign-in, send a short, low-impact prompt and wait for the response to finish. A connection that succeeds at the beginning but fails during a longer response may indicate a less trustworthy route, a timeout, a connection interruption, or a rule that sends later traffic differently.

Test the same prompt again without changing settings, then compare the timestamps and matched rules in Clash. If the result varies between attempts, first stabilize the selected proxy group before editing multiple routing rules.

• No relevant connection in Clash: The CLI may not be using the proxy variables, may have been started from another environment, or may need TUN capture. Confirm the process launch path before changing domain rules.
• Connection appears as direct: Inspect the matched rule and rule order. A broad direct rule may match before a more specific proxy rule.
• Connection uses the intended node but times out: Test a different known-working outbound and inspect whether the route remains trustworthy for a sustained request.
• Sign-in succeeds but a prompt fails: The verification flow and model request are separate tests. Check the later connection in the log instead of assuming the browser result proves API reachability.
• HTTP faults appear immediately: Read the exact status and message. A proxy connection failure, an verification rejection, and a service-side fault require different fixes.

Use the following checks to narrow down the cause:

Do not skip this:Long-running terminal requests are sensitive to interrupted connections, so the node with the lowest one-time ping is not necessarily the best choice for a sustained session.

Troubleshoot Timeouts, Verification, and Routing Key Takeaways

A fair few command-line proxy guides stop at setting one environment variable and leave users to guess why browser sign-in, terminal requests, or long responses still behave differently; broad rule packs can create the opposite problem by routing unrelated traffic without explaining the match.

If Claude Code reports a timeout, first determine which part timed out. A delay before the browser opens suggests a different problem from a browser that entires sign-in while the CLI waits, or a model request that spin ups and then stops.

Record the exact message, the time, the shell used, the selected Clash group, and the matching connection-log entries. These details make it much easier to distinguish a local configuration problem from a temporary upstream issue.

The key point:Check the port and address before editing anything else. A common mistake is using the controller port instead of the HTTP or mixed proxy port. Another is setting 127.0.0.1 inside a container or remote shell, where it points to that isolated environment fairly than the computer running Clash.

If the listener is on the host, use a network path that is actually reachable from the process and configure the host firewall deliberately. Do not expose the proxy listener publicly as a shortcut.

Next, verify that the variables are present in the process environment. In the same terminal where you spin up Claude Code, print the proxy variable values and check for spelling mistakes, extra quotation marks, an incorrect port, or a stale shell session.

Let me put it this way:Be careful when sharing diagnostic output: proxy URLs can contain credentials in a fair few setups. If you have both uppercase and lowercase variables defined differently, make them consistent for the test.

When Clash shows a connection, inspect rule order. Mihomo-style rules are evaluated in order, so a broad direct rule placed above a specific proxy rule can determine the route before the narrower rule is reached.

Prefer a targeted rule for a hostname that you actually observed over a large collection of speculative rules. If the profile is generated by a provider, use a supported override or rule-provider mechanism fairly than editing a downloaded profile that will be overwritten on upgrade.

Concretely:DNS can complicate diagnosis, especially when fake-IP mode, external DNS settings, and applications with their own resolver behavior interact. Do not change DNS mode simply because a request failed. First compare the hostname shown in the connection log with the rule that matched it.

If the connection is classified unexpectedly, inspect the active DNS and fake-IP configuration and make one change at a time. Retest after each change so it is possible to identify which adjustment mattered.

Consider TUN mode when explicit proxy variables do not capture the CLI’s traffic or when the application uses a network path that ignores them. TUN mode can route a wider range of system traffic, but it also affects more than Claude Code. It may require elevated permission, a virtual network front end, and compatible DNS handling.

Where this lands:Enable it only after confirming that you need system-level capture, then test local development tools, internal networks, and other applications that are best off remain reachable. If TUN makes the symptom change but does not resolve it, return to the connection log and identify the remaining failing stage.

Verification faults deserve a separate check. A proxy can deliver a request successfully while the service rejects the account, credential, or authorization flow. Read the fault text carefully and confirm that Claude Code is using the intended sign-in method.

Avoid repeatedly deleting configuration or reauthenticating without evidence; doing so can remove useful local state without fixing routing. If a request works on one network but not another, compare the route and the exact fault fairly than sharing tokens or account details in a public support post.

Do not skip this:Finally, rule out temporary service and network problems. Retry once after a short interval, compare with a different trustworthy outbound, and test another permitted network if available. If only one route fails while other destinations work, focus on that route or its matching policy.

If several unrelated services fail through the same listener, investigate Clash’s general connectivity, DNS, and system firewall before changing Claude Code settings. A concise record of the test—what you ran, which proxy setting was active, what Clash logged, and the resulting fault—will make the next troubleshooting step far more precise.

Clash keeps the workflow focused on the actual listener, observable connection rules, and staged tests, so it is possible to make a small change and verify its effect before expanding the configuration. If you want a Clash client and setup resources to follow this terminal-first approach, browse the download choices and choose the client that fits your operating system.