Use Claude Code With Clash: A Terminal Access Setup Guide

Why Claude Code Needs Its Own Clash Proxy Setup from Practice

Claude Code brings Anthropic’s AI-assisted coding workflow into a terminal: it can inspect project files, suggest changes, be up and running 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 bring up with no proxy configuration at all. When that happens, the browser signs in successfully but Claude Code hangs, reports a network problem message, or cannot reach the model API.

Clash can help route this traffic, but it does not hands-free 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. A good number of terminal tools do not.

They may open a direct TLS connection unless they read proxy environment variables, or unless a TUN control panel 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 by built-in 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 credential check 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 all-in-one its own API requests.

Bring 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.

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 Lessons Learned

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 will want to 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.

Check the listener from the same computer that be up and runnings 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 step by step a bit 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.

The destination host, matched rule, and selected outbound provide better evidence than guessing which rule list will want to contain an endpoint. Add narrow rules only when the connection log shows that a specific request is being sent through the wrong route.

Do not begin by adding every Anthropic-related domain you get 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.

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 ping, DNS, TLS, credentials, and service availability separately.

Configure Proxy Variables for the Terminal in the Wild

For a good number of 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.

These variables affect processes started from that shell, so close and reopen the terminal—or bring up a new shell session—after changing persistent settings.

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"

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.

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.

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 rapid test:

$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

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, bring up Claude Code right off from the shell where you set the variables.

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.

Use NO_PROXY only for destinations that will want to bypass Clash, such as local development services you are expected to reach right off. 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.

A handful of applications use their own network library, ignore these variables, or bring 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. Bring 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: Be up and running 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 Hands-On Notes

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

Then launch Claude Code from the configured shell and all-in-one 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 credential check flow, or limited to model requests.

Credential check may involve both the terminal and a browser. The browser can open successfully and all-in-one 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 full 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.

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 settled 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.

Use the following checks to narrow down the cause:

• 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 settled for a sustained request.
• Sign-in succeeds but a prompt fails: The credential check flow and model request are separate tests. Check the later connection in the log instead of assuming the browser result proves API reachability.
• HTTP problem messages appear immediately: Read the exact status and message. A proxy connection failure, an credential check rejection, and a service-side problem message require different fixes.

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

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, Credential check, and Routing from Practice

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 all-in-ones sign-in while the CLI waits, or a model request that bring 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.

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 a bit 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 bring up Claude Code, print the proxy variable values and check for spelling mistakes, extra quotation marks, an incorrect port, or a stale shell session.

Be careful when sharing diagnostic output: proxy URLs can contain credentials in a handful of 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 a bit than editing a downloaded profile that will be overwritten on pull the latest.

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 you get 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 control panel, and compatible DNS handling.

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

Credential check problem messages deserve a separate check. A proxy can deliver a request successfully while the service rejects the account, credential, or authorization flow. Read the problem message 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 problem message a bit than sharing tokens or account details in a public support post.

Finally, rule out temporary service and network problems. Retry once after a short interval, compare with a different settled 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 problem message—will make the next troubleshooting step far more precise.

A handful of 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.

Clash keeps the workflow focused on the actual listener, observable connection rules, and staged tests, so you get 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 entrys and choose the client that fits your operating system.