Tutorial October 18, 2026

Claude Code With Clash: Configure Proxy Settings for the CLI

Get Claude Code terminal traffic working with Clash. This guide covers proxy modes, HTTP_PROXY and HTTPS_PROXY variables, route checks, and practical fixes for common connection errors.

Docker Proxy GitHub Acceleration Advanced Config YAML

1. Scope: what Clash can—and cannot—fix

If Claude Code works in a browser but fails in a terminal, the difference may be the network path rather than your account or project. Claude Code is a command-line tool: it starts from a shell, makes its own outbound requests, and may also be launched as a child process by an IDE. A browser’s successful connection does not prove that these terminal processes use the same proxy settings. Clash can provide a route for those connections, but it cannot fix an invalid credential, an account restriction, an expired login, or a service outage.

This guide focuses on practical routing with Clash clients that use Mihomo, including Clash Verge and Clash Verge Rev. The same checks are useful with other clients, although menu names, default ports, and system-proxy behavior vary. The examples use 127.0.0.1:7890 as a placeholder for a local HTTP proxy. Check your own client’s port settings before copying it: a mixed port may accept both HTTP and SOCKS connections, while a dedicated SOCKS port is not interchangeable with an HTTP proxy URL.

There are two common ways to connect a CLI to Clash. You can set proxy environment variables for the Claude Code process, or use Mihomo’s TUN mode to capture system traffic at the network layer. Environment variables are usually the clearest first test because they explicitly tell a compatible application which proxy to use. TUN can help when a process ignores those variables, but it introduces additional system-level routing and permission considerations. Start with one method, verify it, and only then add the other if necessary.

Treat the proxy as a routing choice, not a guarantee of privacy or service eligibility. Requests sent through a remote proxy node may be visible to infrastructure operators, and connection routing does not change the terms that apply to your account or organization. Do not send regulated, confidential, or customer data through a relay unless your security and data-residency policies allow it. Never share a configuration containing credentials, subscription URLs, or access tokens when asking for help.

2. Why “the browser works” is not a useful CLI test

A desktop client’s system-proxy toggle commonly configures applications that read the operating system’s proxy settings. A terminal command may instead inherit environment variables from the shell that launched it. An IDE can add another layer: it may have started before you enabled Clash, may use its own proxy preferences, or may launch an integrated terminal with an older environment snapshot. As a result, the browser can reach a service while Claude Code receives a timeout, a connection reset, or an authentication page that never finishes loading.

A command-line process can also create multiple kinds of connections during one task. It may need to establish HTTPS sessions, follow redirects, retrieve account or service metadata, and keep a response stream open while output arrives. A proxy that permits a short connection but interrupts a long-lived stream can look like an application bug. Likewise, a route that sends the initial request through a proxy but sends a related hostname directly can lead to confusing partial failures.

DNS behavior can contribute to the mismatch. In rule mode, Mihomo evaluates traffic against the rules in the active profile; in global mode, traffic follows the selected global policy. Fake-IP DNS, IPv4 and IPv6 selection, and application-level DNS resolution can all affect what the client observes. Do not assume that changing a domain rule will fix a process that never reaches Mihomo, or that a successful DNS lookup proves the TCP and TLS connections use the intended route.

Before changing settings, record the exact symptom and the time it occurs. Distinguish a name-resolution error from a refused connection, a TLS error, an HTTP response, and a timeout during streaming. Keep the Claude Code version, operating system, Clash mode, active proxy group, and whether you launched from a normal terminal or an IDE terminal in your notes. These details help you compare the same request across attempts rather than changing several variables at once.

3. Find the right Clash listener and policy

Open the active Clash client and locate the local port settings. Depending on the client and profile, you may see separate HTTP, SOCKS, or mixed-port values. A mixed port is generally convenient for command-line tools because it accepts more than one proxy protocol; however, the URL in the examples below uses the HTTP proxy scheme. Use the actual HTTP-compatible listener configured on your machine. If you enter a SOCKS-only port in an http:// URL, the application and listener will disagree about the protocol.

Next, check the routing mode and the policy group that should handle Claude Code traffic. In Rule mode, a connection is routed according to the first matching rule, so a broad rule placed earlier in the profile can take precedence over a later service-specific rule. In Global mode, the selected global group controls more traffic than just the CLI. Choose the narrowest setup that matches your needs, and leave unrelated work—such as internal Git servers or company services—on the routes required by your organization.

Do not copy a hostname list from an old forum post and assume it covers every current connection. Begin with the service hostnames shown in the failing request or in Mihomo’s connection view. A profile may need to route the API hostname used by the client, while sign-in or supporting requests may involve other hostnames. The exact set can change with product versions and account flows. Prefer a narrowly scoped rule based on observed traffic over a broad rule that sends every vendor-related domain through the same group without checking what it includes.

If you maintain your own Mihomo profile, a domain rule may look like the following. Replace the example group name with a policy group that actually exists in your configuration, and place the rule before any broader rule that would otherwise match first.

rules:
  - DOMAIN,api.anthropic.com,Claude-Proxy
  - MATCH,Other-Traffic

This is only an illustrative rule, not a complete profile. It does not create the Claude-Proxy group, define proxy nodes, or account for every hostname that a login or update flow might use. If a request is missing from the connection log, verify first that the CLI is reaching Clash at all. If it appears in the log with an unexpected policy, inspect rule order and the active configuration before adding more domains.

4. Set HTTP_PROXY and HTTPS_PROXY for Claude Code

For a compatible CLI process, set both uppercase variables so that HTTP and HTTPS requests have a proxy available. The proxy URL often starts with http:// even when the destination is an HTTPS service: this describes the local connection to the HTTP proxy, which can then establish a tunnel for TLS traffic. Do not change the URL to https:// unless your local listener is explicitly configured to accept TLS connections from clients.

Temporary settings for one terminal session

On macOS or Linux, open a new terminal and export the variables using your local Clash listener. Starting Claude Code from that same shell makes the variables available to the child process. This is a useful first test because it does not alter system-wide settings or other applications.

export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
claude

On Windows PowerShell, set the variables in the current session before launching the command. In Command Prompt, use the corresponding set syntax. These values are session-scoped; closing the terminal removes them. That makes them useful for diagnosing a problem without permanently changing your shell configuration.

$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
claude

If the temporary test works, decide how you want the setting to persist. Shell users can add carefully chosen exports to a shell startup file, but avoid doing so on machines where the proxy should only be used for specific projects. A project-specific launcher or documented team script can make the intended behavior clearer. On Windows, a profile or a small launcher can serve a similar purpose. Before saving anything permanently, confirm that the local Clash port does not change between profiles or client restarts.

Lowercase names and bypass rules

Some tools and libraries also inspect lowercase spellings such as http_proxy and https_proxy. If the uppercase variables are present but the process still appears to connect directly, you can test the lowercase forms as well, while keeping the values consistent. Avoid setting contradictory uppercase and lowercase values: different libraries may choose different spellings, which makes the result difficult to diagnose.

The NO_PROXY variable, sometimes written as no_proxy, lists destinations that should bypass the proxy. It can be useful for loopback addresses or internal services, but an overly broad entry may accidentally bypass the route you are trying to test. For an initial diagnosis, remove custom bypass entries or keep them as narrow as your environment requires. If your company mandates direct access to internal hosts, preserve those exceptions and confirm they do not match the service hostname involved in the failure.

An environment variable is a process instruction, not a setting that magically reaches every already-running application. If you set it in a new shell but launch Claude Code from an IDE that was opened earlier, the IDE may not pass the new values to its child processes. Restart the IDE after changing environment settings, or launch the CLI directly from the terminal where you set them. Avoid placing API keys or other secrets in shell commands that may be saved in history or exposed in process listings.

5. Verify the proxy path instead of guessing

First confirm that Clash is running and that its local listener is reachable. Check the client’s connection view while launching a small, non-sensitive network request through the same shell. A successful test request should appear in Clash’s logs or connection list and use the policy group you intended. If nothing appears, investigate the listener address, port, process environment, or firewall before editing domain rules.

You can use curl to test whether the local proxy accepts a connection. For example, request a public service endpoint through the proxy and inspect the verbose connection output. The destination may return an authorization error or another non-success status when you have not supplied application credentials; that alone does not mean the proxy failed. The useful signals are whether the proxy connection was established, whether TLS negotiation completed, and whether the request received an HTTP response.

curl -v --proxy "$HTTPS_PROXY" https://api.anthropic.com/

A test with curl is a diagnostic, not proof that every application uses the same network stack. Compare the request with Claude Code itself and watch Clash’s connection view during the attempt. If the command-line test succeeds but Claude Code still fails, confirm the variables are visible in the process-launching shell, restart any parent IDE, and check whether the CLI reports a more specific error. If neither test reaches the expected policy group, focus on Clash routing rather than changing application settings.

When a request appears in the logs, inspect the destination, policy, and result. A direct route where you expected a proxy usually points to the mode, rule order, or a bypass setting. A proxied request that fails during connection setup may point to an unavailable node, a listener mismatch, or a network restriction between the machine and the node. A completed TLS session followed by an HTTP error is a different class of issue: the service may be rejecting the request, the account may need attention, or a required authentication flow may not have completed.

For streaming or longer tasks, watch the connection for the entire operation. If output starts and then stops, record how long the connection remains open and whether Clash reports a timeout or closure. Try another suitable node if policy permits, but change only one variable at a time. A faster node can improve latency, while a distant or overloaded node can make time-to-first-response and long-lived sessions worse even though ordinary web pages load.

6. Common connection failures and practical fixes

Connection refused or connection timeout

A refused connection often means the local proxy address or port is wrong, the listener is not enabled, or another local service is blocking access. Compare the proxy URL with the actual port shown in Clash, and check whether the listener is bound to loopback or another interface. A timeout can also mean the CLI is bypassing Clash and attempting a direct connection, or that the selected relay cannot reach the destination. Use the connection log to distinguish a request that never reached Clash from one that reached Clash but failed upstream.

TLS errors, resets, or interrupted output

If a TLS error appears, verify that the environment variable uses the correct proxy scheme and that you have not pointed an HTTP client at a SOCKS-only listener. Do not disable certificate verification as a workaround: that weakens security and can hide the real problem. If responses begin but later stop, inspect node stability, idle timeouts, and the client’s connection record. Test a different policy group only if you are authorized to do so, then compare the same operation under the same conditions.

Authentication prompts or repeated login redirects

Authentication problems are not automatically proxy problems. Confirm the account is signed in, the relevant credentials are current, and the CLI is using the intended account or organization. If a browser-based flow is involved, note whether the browser and CLI use different routes or different network environments. A proxy can change the apparent network path, but it cannot make an account eligible for a service or repair an expired credential. Do not post authentication tokens, cookies, or full debug logs containing secrets when seeking help.

Works in a shell but fails in an IDE or service

An IDE, task runner, container, or background service may not inherit the environment of the terminal where you tested the proxy. Restart the parent application after changing variables, inspect the environment available to the actual child process, and check whether the process runs under a different user account. Containers may need a reachable host address rather than the host’s loopback address; do not assume that 127.0.0.1 inside a container refers to the computer running Clash. Keep any container-specific network changes limited to the environment you understand and administer.

7. Frequently asked questions

Does enabling Clash system proxy automatically cover Claude Code?

Not always. Some applications read the operating system’s proxy setting, while command-line tools may rely on environment variables or their own networking library. Set the variables in the shell that starts Claude Code, then confirm the request appears in Clash. TUN mode is another option when appropriate, but verify its behavior separately.

Should I use Clash’s HTTP port, SOCKS port, or mixed port?

Use a listener that supports the protocol named in your proxy URL. The examples use an HTTP proxy URL, so use an HTTP-compatible or mixed listener. A SOCKS-only port needs a SOCKS-aware client configuration instead. Check the port in the active Clash client rather than relying on a default copied from another computer.

Should I enable TUN mode as well as HTTP_PROXY?

Start with one method so that you can tell which one is carrying the request. Environment variables are easy to test for a compatible CLI. TUN can capture traffic from applications that do not honor proxy variables, but it changes system routing and may require permissions or DNS adjustments. Add it only when you have a clear reason and can verify the resulting path.

Can I use the same settings in an IDE terminal?

Yes, if the IDE terminal inherits the variables and the CLI supports them. If you changed the variables after opening the IDE, restart it before testing. When shell launches succeed but IDE launches fail, compare the actual environment and Clash connection logs instead of assuming both terminals have identical settings.

Some one-click VPN clients make it difficult to tell which route a single command used, and changing a system-wide mode can unintentionally affect internal repositories or other work. With Clash, a verified local listener, explicit proxy variables, connection logs, and ordered domain rules give you more control over Claude Code’s CLI path while leaving unrelated traffic on its required route. If that focused, observable setup fits your workflow, you can compare compatible clients and choose the one that suits your operating system.

Download Clash clients →

Ready to get started?

Choose a compatible Clash client, confirm its local proxy port, and apply the routing checks from this guide.