Why Claude Code needs a coherent proxy path

Claude Code runs in your terminal, but its network activity is not limited to the command you type. Depending on your workflow, setup may involve installing or updating the CLI, authenticating through a browser, contacting Anthropic services, and keeping longer-lived connections open while the assistant streams a response. A browser that loads normally is useful evidence, but it does not prove that every process launched from your shell can reach the same services through the same route.

Clash makes routing decisions per connection. That flexibility is valuable when your work requires separate policies for local development, documentation, package registries, and AI services. It can also make troubleshooting confusing: the browser’s OAuth page may use one route, the terminal process another, and a DNS rule or catch-all policy a third. The result can look like an invalid account, a broken installation, or an unresponsive model even when the underlying problem is simply that different parts of the workflow have different network paths.

Start with one goal: make the terminal process and its authentication flow use a predictable, authorized route. Avoid changing several layers at once. If you enable TUN, edit DNS settings, add domain rules, and change shell variables in one session, you will have no clear way to tell which change fixed the issue—or introduced a new one. Begin with Clash’s local HTTP proxy, test a single shell command, and add complexity only when a specific requirement calls for it.

ℹ Scope: Use Claude Code and proxy routing only in locations and on accounts where Anthropic’s terms, local rules, and your employer’s or school’s policies permit them. These steps help diagnose ordinary connectivity; they are not a way to bypass access controls.

Prepare Clash and verify the local listener

Before changing Claude Code settings, confirm that your Clash client is running and has an active profile. In Clash Verge, Clash Verge Rev, or another Mihomo-based client, check that the profile has loaded successfully, the core is running, and the intended proxy group has a usable selection. A profile can appear in the client while its nodes are unavailable or its rules send the relevant traffic to an unexpected group, so do not treat a visible profile name as proof of a working route.

Find the local HTTP or mixed-port value in the client’s settings. The frequently used example port 7890 is not universal; use the value shown in your own client. An HTTP proxy is a convenient first test for terminal applications that support proxy environment variables. A mixed port can accept HTTP proxy requests as well as SOCKS connections, but the address and port still need to match the listener actually enabled in your configuration.

  1. Check the port. In the Clash client, locate the HTTP or mixed-port setting and note the port number. If the client allows you to change it, make the change deliberately and confirm the new value before testing.

  2. Choose a route. Select a policy group and a node that are permitted for your account and location. For the initial test, keep the routing policy simple enough that you can identify which group handles a request.

  3. Confirm the client is listening. Use the client’s connection or log view while making a test request. A healthy-looking terminal command with no corresponding Clash connection may mean the process did not use the proxy at all.

  4. Keep a clean baseline. Temporarily avoid running multiple proxy clients or VPNs that may compete for system settings. Do not disable a managed network control on a work device; ask your administrator how to test within the approved setup.

You can test the local proxy without Claude Code. Replace the example port if yours differs: 

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

This test checks whether curl can reach a site through the local listener; it does not prove that Claude Code is configured correctly or that every Anthropic-related endpoint is reachable. If the command fails, first inspect Clash’s logs and connection view, then confirm that the selected group has a working route. If it succeeds but Claude Code still fails, continue with the shell environment and the CLI’s own diagnostics rather than changing the Clash profile at random.

Set proxy variables in the terminal session

Many command-line tools check standard proxy environment variables, but support varies by application, runtime, and version. Claude Code’s behavior can also change as its installation and networking components evolve. Set the variables for a test session, verify that the process can make a request, and consult the current Claude Code documentation if your version reports that it ignores a particular setting. Do not assume that enabling the system proxy in a desktop client automatically configures every shell process.

macOS and Linux shells

For a temporary test in a POSIX-compatible shell, export both uppercase and lowercase forms. Using the same local HTTP listener for HTTP and HTTPS destinations is normal: HTTPS is carried through the proxy using a CONNECT request rather than being sent as plain HTTP. Keep the scheme in the proxy URL as http:// when the local listener speaks HTTP, even when the destination begins with https://. 

export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export ALL_PROXY="http://127.0.0.1:7890"
export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export all_proxy="$ALL_PROXY"

Run the command that starts Claude Code from the same terminal session so it inherits the variables. To avoid leaving a temporary setting in your shell, close that terminal or unset the variables after testing: 

unset HTTP_PROXY HTTPS_PROXY ALL_PROXY
unset http_proxy https_proxy all_proxy

If the temporary test works and you want a persistent setup, add the exports to the startup file used by your actual shell—for example, the relevant Zsh or Bash configuration file—and open a new terminal to verify them. Avoid placing subscription URLs, passwords, API keys, or other secrets in a shell startup file. Proxy environment variables should contain the local listener address, not authentication credentials for an unrelated account.

Windows PowerShell

In PowerShell, set environment variables for the current process before launching Claude Code: 

$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:ALL_PROXY = "http://127.0.0.1:7890"
$env:http_proxy = $env:HTTP_PROXY
$env:https_proxy = $env:HTTPS_PROXY
$env:all_proxy = $env:ALL_PROXY

These values apply to programs started from that PowerShell session; they do not automatically change settings for other terminals, already-running processes, or every Windows application. When testing from Windows Terminal, make sure the tab is actually running PowerShell rather than Command Prompt, Git Bash, or a remote shell. Each environment has its own syntax and process inheritance behavior.

Be cautious about making proxy settings permanent at the user or system level. A stale value can break unrelated tools when Clash is closed, its port changes, or you switch networks. If you need a lasting configuration, document where you set it and how to remove it. For a quick test, session-scoped variables are easier to reverse and make the result easier to interpret.

Route Claude Code traffic with observable rules

A proxy variable tells a compatible application where to send requests; it does not determine which Clash policy group ultimately handles each destination. That decision is made by the active profile’s rules and groups. Start by watching the Clash connection list while Claude Code starts, authenticates, or sends a short prompt. Inspect the destination host, matched rule, and selected group. These observations are more reliable than copying a long list of domains from a post written for a different CLI version or a different account flow.

Claude Code may contact more than one host as you use it. Authentication, product services, telemetry or diagnostics, and model requests can have distinct destinations, and the set can change over time. Do not infer that a single successful request proves the whole workflow is covered. Instead, note which connections appear during the exact action that fails, then decide whether those destinations should share a policy under your network rules.

Observed behavior What to inspect in Clash Useful next step
Claude Code starts, but authentication does not finish Browser and terminal connections, matched rules, and whether the callback returns to the CLI Test the browser flow and terminal flow separately; check for a competing proxy or blocked local callback
The CLI starts but a request times out Whether a connection appears, which group it uses, and whether the connection repeatedly reconnects Confirm the shell variables and selected route before editing DNS or adding broad rules
Some features work while others fail Whether different destination hosts match different policies Use observed hostnames to refine narrowly scoped rules in the correct order
Clash shows no related connection Whether the process inherited the proxy variables and whether the local port is correct Repeat the local curl test, then launch Claude Code from that same terminal session

When you do add rules, prefer specific, documented matches over a broad catch-all. Put a narrow rule above any general rule that would otherwise capture the same traffic, and verify the result in the connection view after saving the profile. If the policy requires certain destinations to remain direct or forbids proxying them, preserve that requirement rather than forcing a single route for every connection. A clean configuration is one whose behavior you can explain, not merely one that happens to work once.

Avoid treating DNS changes as a first-line fix. A hostname can resolve correctly while the application still uses the wrong proxy, and a proxy connection can fail even when DNS is healthy. Likewise, TUN mode is not required just because an application runs in a terminal. Try the explicit local proxy first; consider TUN only if the application does not support proxy variables and your network policy permits system-level traffic capture. If you do enable it, change one setting at a time and recheck the route in Clash.

Troubleshoot connection failures by layer

A useful diagnosis starts with the earliest failing layer, not the most alarming error message. “Unauthorized,” “network error,” and “timeout” describe different symptoms, but a short CLI message may not identify the cause. Check the local listener, the shell environment, DNS and routing, TLS trust, and authentication in that order. Keep the test small: launch the CLI, perform one action, and compare its timestamp with Clash’s logs.

No connection appears in Clash

First confirm that Claude Code was launched from the terminal where you set the variables. Print the relevant variable names and values, taking care not to share logs that contain sensitive information. Check for a misspelled variable, an incorrect port, or a different proxy scheme than the local listener supports. A common mistake is to set variables in one shell and start the CLI from an already-open terminal, a graphical launcher, or a separate integrated development environment that does not inherit them.

Connections appear but time out

Check which rule matched and which group was selected. Confirm that the selected node is available and that the profile has not routed the destination to a group you did not intend. If a request starts and then stalls, compare several attempts in the logs rather than immediately switching to a different DNS mode. A single short probe may succeed while a longer response stream fails; observe the actual Claude Code operation and note whether the connection closes, resets, or remains pending.

Authentication loops or TLS errors

If a browser sign-in appears successful but the CLI remains unauthenticated, check whether the browser and CLI can both reach the required services under the permitted network policy. Also check whether a local callback is blocked by another application or whether an old terminal session is using stale proxy settings. For a TLS or certificate error, verify the device clock and inspect whether an approved security product or corporate proxy is intercepting certificates. Do not disable certificate verification or install an untrusted root certificate as a shortcut; ask your administrator for the supported configuration.

After you find the cause, remove temporary test settings you no longer need and keep only the smallest routing changes that solve the observed problem. Record the working port, shell, rule, and policy group so that a future client or profile update does not turn a one-time fix into a mystery. When an update changes Claude Code’s endpoints or proxy behavior, repeat the same controlled tests instead of assuming that yesterday’s rule list still describes today’s connections.

Compared with a browser-only proxy toggle, a terminal-first setup needs more attention to process inheritance, local listener ports, and per-host routing; a system-wide tunnel can capture more traffic, but it also broadens the impact of a mistake and may conflict with managed-device policies. Clash gives you a practical middle ground: an explicit local proxy for compatible CLI tools, visible connection logs, and rules you can test without blindly redirecting everything. If you want a client workflow that makes those checks easier to manage, visit the Clash V.CORE download page and choose the option that fits your operating system and permitted network setup.