Claude Code With Clash: Terminal Setup And Access Guide

Why Claude Code Needs a Reliable Clash Route

Claude Code brings an AI coding assistant into the terminal, where it can inspect a project, explain unfamiliar code, edit files, run tests, and help you iterate without leaving your shell. That workflow is much more sensitive to network quality than a casual browser session. A browser may retry a page silently, while a command-line request can fail immediately when authentication, model discovery, streaming output, or tool execution uses a route that is slow or unreachable.

Clash provides a practical way to control that route. Instead of sending every connection through one fixed tunnel, you can use a local HTTP or SOCKS proxy, choose a reliable proxy group for AI service domains, and keep package registries, local Git servers, and domestic resources on a direct connection. This split-routing approach usually gives Claude Code a stable path without making the entire terminal environment unnecessarily dependent on a remote node.

The important detail is that Claude Code is a terminal application, not a browser tab. It may read proxy-related environment variables such as HTTP_PROXY, HTTPS_PROXY, and ALL_PROXY, but it will not automatically inherit a browser extension's proxy settings. Likewise, enabling a system proxy in Clash may help some applications while leaving other command-line tools untouched. A successful setup therefore has three parts: a working Clash profile, a proxy endpoint that the shell can reach, and a routing policy that covers the domains used by your authentication and model requests.

Use a legitimate account and subscription

Clash only controls local traffic routing. It does not provide an Anthropic account, an API key, or access to Claude services. Follow the service terms that apply to your account and location, and never paste an API key into a public issue, shared shell history, or configuration file that will be committed to Git.

Prepare the Clash Terminal Proxy

Install a maintained Clash client for your operating system, such as Clash Verge Rev on Windows or macOS, Mihomo-compatible builds, or an Android client when the terminal is running inside a mobile environment. The menus vary between clients, but the networking concepts are the same. Import a valid subscription profile, select a responsive node, and confirm that the client is running before changing shell variables.

Before configuring Claude Code, verify these items:

A Clash profile has been imported and activated successfully.
At least one proxy node passes the client's latency or connectivity test.
The local HTTP or mixed port is enabled and listening on the local machine.
The proxy mode is set to Rule, unless you are temporarily testing with Global.
Your system clock is accurate, because incorrect time can break HTTPS certificates and authentication.

Most Clash clients expose a mixed port, which accepts both HTTP proxy and SOCKS5-style connections. A common example is 7890, but you must use the port displayed by your own client. Do not assume that every Clash fork uses the same value. In the client dashboard, look for labels such as Mixed Port, HTTP Port, or Port. If the dashboard shows an HTTP port of 7890, the terminal proxy URL is usually http://127.0.0.1:7890.

The loopback address matters. 127.0.0.1 means “this computer,” so the request first reaches Clash locally and is then forwarded according to your active rules. Avoid binding the controller or proxy port to a public network interface unless you understand the security implications. An exposed Clash port can allow other devices on the same network to use your proxy or modify the client if the external controller is insufficiently protected.

Before opening Claude Code, test the proxy with a simple HTTPS request. Replace the example host with a domain that your account is expected to reach:

curl -I https://example.com
curl -I -x http://127.0.0.1:7890 https://example.com

The first command tests your normal route, while the second explicitly asks curl to use Clash. The second request should either return an HTTP response or at least progress beyond the connection stage. A certificate warning, connection refusal, or long timeout is useful evidence: it tells you that the problem exists before Claude Code is involved.

Tip: confirm the actual local port

When curl reports “connection refused,” do not immediately change DNS or proxy rules. First check whether Clash is running, whether the selected port is correct, and whether another application has already occupied that port.

Configure Proxy Variables for Claude Code

Once the explicit curl test works, configure the shell environment used to launch Claude Code. Environment variables are preferable to editing the application or placing credentials inside a project file because they are easy to inspect, change, and remove. They also allow separate settings for a normal terminal, a project-specific shell, or a temporary troubleshooting session.

On macOS, Linux, WSL, and other POSIX-like shells, use the following form. The exact port must match your Clash client:

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=socks5://127.0.0.1:7891

claude

Some command-line clients interpret ALL_PROXY differently or prefer a SOCKS5 URL for it. If HTTPS requests fail with the SOCKS setting, start with the HTTP proxy for both HTTP_PROXY and HTTPS_PROXY. You can also set lowercase variants because different libraries inspect different spellings:

export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export all_proxy="$ALL_PROXY"

For a short-lived test, place the variables on the same command line instead of writing them into your shell profile:

HTTPS_PROXY=http://127.0.0.1:7890 \
HTTP_PROXY=http://127.0.0.1:7890 \
claude

This method is useful when you only want Claude Code to use Clash while package managers and local development tools continue using their normal route. If the test succeeds, you can decide whether to add the exports to ~/.zshrc, ~/.bashrc, or a project-specific launcher. Avoid adding them globally if your work environment has internal services that should never be sent to an external proxy.

On Windows PowerShell, the equivalent syntax is:

$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:ALL_PROXY = "socks5://127.0.0.1:7891"

claude

These variables last only for the current PowerShell session. In Command Prompt, use set instead:

set HTTP_PROXY=http://127.0.0.1:7890
set HTTPS_PROXY=http://127.0.0.1:7890
claude

After setting a variable, inspect it before launching the assistant. This catches common mistakes such as an extra quotation mark, a missing scheme, or a port copied from the Clash controller rather than the proxy listener:

echo $HTTPS_PROXY
curl -v https://example.com

PowerShell users can run $env:HTTPS_PROXY, while Windows users can also use curl.exe to avoid confusion with PowerShell's command alias. If a corporate network injects its own certificate or requires an authenticated proxy, do not disable TLS verification as a permanent workaround. Find the correct certificate and proxy policy first; skipping verification can expose tokens and source code.

Set Clash Rules Without Breaking Local Development

A terminal setup works best when the routing policy reflects how you actually work. Sending all traffic through a distant node can make Git clones, package downloads, Docker pulls, and local dashboards slower. Sending all traffic directly can cause Claude Code authentication or model requests to fail. In Clash, the goal is to route the necessary service domains through a dependable proxy group while retaining DIRECT for local and trusted resources.

Open the active profile and inspect its rule order. In rule-based mode, the first matching rule wins. A broad GEOIP,CN,DIRECT or DOMAIN-SUFFIX,example.com,DIRECT rule placed above a more specific proxy rule can send an AI-related request directly, even though the proxy node itself is healthy. When diagnosing a failure, use Clash's connections or logs panel and check the hostname, matched rule, policy group, and final outbound action.

Traffic type	Suggested policy	Reason
Claude authentication and API domains	Reliable proxy group	Requires a reachable and consistent HTTPS route
Local Git server or intranet	DIRECT	Preserves access to private network resources
Package registries	Rule-based choice	Different registries may perform better through different routes
Unknown destinations	Rule or fallback group	Avoids forcing every unclassified request through one node

Do not copy a domain list from an untrusted post and assume it will remain correct. Service endpoints and authentication flows can change, and a single product may use separate domains for login, API requests, telemetry, package retrieval, and documentation. Start with the hostname shown in Clash logs when Claude Code performs the failing action. Add only the narrowest rule needed, then reload the profile and test again.

For example, a Mihomo-style profile may contain rules with this general structure:

rules:
  - DOMAIN-SUFFIX,internal.example,DIRECT
  - DOMAIN-SUFFIX,provider.example,AI-PROXY
  - GEOIP,LAN,DIRECT
  - MATCH,Default

The names in this example are placeholders. Replace them only after verifying the real destinations and the policy group names in your profile. Some configurations use rule providers, scripts, or YAML anchors, so editing the generated subscription directly may be overwritten during the next update. If your provider supplies a managed template, put local overrides in the supported override section instead of modifying the downloaded file.

After changing rules, restart the terminal process. Existing shells may retain proxy variables, and a long-running Claude Code session may keep connections or cached authentication state. A clean restart makes it easier to tell whether the new policy is actually being used.

Test the Complete Terminal Workflow

Test in layers rather than launching a large coding task immediately. First confirm that Clash can reach the destination, then confirm that the shell uses the local proxy, and only then test Claude Code authentication. This sequence prevents you from confusing an invalid API key with a DNS problem or a dead proxy node.

Open Clash's log or connection view and keep it visible.
Run an explicit curl request through the local proxy.
Check that the request appears in Clash and is assigned to the intended policy group.
Launch Claude Code from the same terminal where the variables were defined.
Run a small request, such as asking it to describe the current project without modifying files.
Confirm that streamed output continues and that the process does not stop during authentication or model selection.

If Claude Code says that it cannot connect, check the error stage. A failure before any request appears in Clash usually points to an unset variable, an unsupported proxy format, a shell launched before the variables were exported, or an application that ignores those variables. A request that appears in Clash but is marked DIRECT suggests rule order or a hostname mismatch. A request assigned to the proxy group but timing out suggests node quality, server congestion, DNS behavior, or an upstream access issue.

Common symptoms and focused checks:

Connection refused: verify that Clash is running and that the terminal port is not the controller port.
Authentication loops: check system time, browser-based login completion, cookies, and whether the login host follows the same proxy route as the API host.
Streaming stops midway: try another node, inspect connection timeouts, and avoid unstable proxies that frequently rotate IP addresses.
Only one project fails: inspect project environment files, shell scripts, Git hooks, and local firewall rules before changing the global Clash profile.
Git or package commands break: use a narrower proxy scope or add direct rules for internal services instead of forcing the whole terminal through the AI route.

Pay special attention to credentials. If you place HTTPS_PROXY in a shared script, anyone who can read that script may learn details about your network. If a proxy requires a username and password, prefer the operating system's secure credential mechanism where supported rather than committing a URL containing credentials. Keep API keys in the environment or the official credential store, add secret files to .gitignore, and rotate a key immediately if it appears in terminal output or version control.

DNS settings can also produce misleading results. With system-proxy mode, some applications resolve a hostname locally before sending the connection through Clash. With TUN mode, Mihomo may handle more traffic at the network layer, but the exact behavior depends on the client, operating system, and DNS configuration. Do not enable several competing VPNs, browser DoH settings, and custom DNS redirectors while testing. Establish one predictable path first, then add advanced features one at a time.

Finally, keep a fallback plan. If a node becomes slow, switch the AI policy group to another tested node rather than rewriting every shell command. Update subscriptions periodically, but review generated changes before applying them to important workstations. A stable terminal workflow is not created by one magic switch; it comes from a visible proxy listener, explicit environment variables, understandable rules, and a repeatable test process.

Other proxy utilities may offer a quick global toggle, but they often provide limited visibility into which terminal request was routed, weak traffic splitting, or different configuration behavior across Windows, macOS, and Linux. Clash is more deliberate: it exposes local HTTP and SOCKS endpoints, rule and group policies, connection logs, and a broad ecosystem of maintained clients. If you want Claude Code to have a reliable route while local repositories and development services remain fast and predictable, download Clash and build the setup around the checks in this guide.