Why Claude Code Needs a Terminal Proxy

Claude Code is not simply a browser tab with an AI chat window. It is a command-line development tool that runs inside your shell, reads project files, executes approved commands, communicates with Anthropic services, and may contact package registries or source-control hosts during a normal coding session. That difference explains why a browser can open Claude successfully while Claude Code authentication hangs, model requests fail, or an otherwise healthy terminal reports a network error.

When you start Claude Code from PowerShell, Windows Terminal, macOS Terminal, iTerm2, or a Linux shell, the process follows the networking rules available to that process. It may not inherit the proxy selection you made in a browser extension. It may also ignore the operating system’s graphical proxy setting unless the runtime explicitly reads it. A terminal command can therefore open a direct TLS connection while Chrome is using Clash Verge without any problem.

The practical goal is not to force every connection through one remote node. The goal is to create a predictable path for the hosts that Claude Code actually needs. Authentication endpoints, model API endpoints, update sources, npm or pnpm registries, Git hosting, and ordinary project traffic can have different reliability requirements. A well-designed Clash terminal proxy setup makes those choices visible in the connection log instead of leaving the shell to guess.

This guide uses Clash Verge with a Mihomo-compatible core because it gives desktop users a manageable interface for subscriptions, mixed ports, system proxy settings, TUN mode, and rule inspection. The same reasoning applies to other Clash clients, but menu names and permission prompts can differ. You should also remember that a proxy client cannot bypass an account restriction, repair an invalid API key, or make an expired subscription valid. It only provides a controllable network route.

Prepare Clash Verge and Import a Reliable Profile

Before diagnosing Claude Code, establish a known-good Clash baseline. Download Clash Verge Rev or another maintained Mihomo client from a source you trust, and select the build that matches your operating system and CPU architecture. On Windows, most current computers use x64, while Apple Silicon Macs need an arm64 build. Linux users should confirm whether their desktop session can create a TUN device and whether the distribution’s firewall or policy framework permits the helper process.

Next, obtain a current subscription URL from your provider. A subscription is more than a list of addresses: it normally contains proxy definitions, proxy groups, DNS settings, and routing rules. Importing a random YAML file from a forum may produce a familiar interface while silently using obsolete ciphers, dead servers, or rules that send AI service traffic to DIRECT. If your provider offers separate Mihomo, Clash Meta, or sing-box formats, choose the format intended for the core used by Clash Verge.

1. Open the Profiles or Subscriptions view in Clash Verge and paste the provider’s HTTPS subscription URL. Give the profile a clear local name such as work-ai-2026 rather than leaving several entries with identical dates.
2. Download and activate the profile. Confirm that proxies and proxy groups appear, then select a group with at least two usable nodes. Do not assume that the first item in a list is the fastest or most reliable route.
3. Check the core version and mode. Use the Mihomo-compatible core supplied by the maintained client. A profile containing modern transports can fail if an old core parses only part of the YAML.
4. Choose a stable proxy group for interactive AI traffic. Prefer a manually selected or carefully tested group while troubleshooting. An aggressive automatic group that changes nodes every few seconds makes authentication and streaming failures difficult to reproduce.
5. Test a normal HTTPS page and inspect Connections. The page test only proves basic connectivity. The connection panel is more valuable because it shows the process, hostname, matched rule, selected group, and final outbound node.

Keep the original subscription profile untouched when possible. If you need custom rules, create a local override, mixin, or separate copy rather than repeatedly editing the provider’s downloaded file. Providers may overwrite local changes during an update, and a small formatting mistake can prevent the entire profile from loading. Export a backup before changing DNS, TUN, or rule providers so that you can return to a known working state.

Mixed Port, Environment Variables, and the First Test

Clash Verge usually exposes a mixed port, which accepts both HTTP proxy and SOCKS5-style clients. The exact port depends on your profile and client settings, so read it from the dashboard rather than copying a number from an old tutorial. In the examples below, 7890 is only a placeholder. Replace it with the port shown in your own Clash Verge installation.

# PowerShell
$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:7890"

# macOS or Linux
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:7890"

These variables affect processes launched from that shell. They do not automatically change every application on the computer, and they do not guarantee that every Node.js library will honor them. Some tools recognize only uppercase names; others inspect lowercase http_proxy and https_proxy. If a command still connects directly, set both cases for a short diagnostic session or use the tool’s own proxy option.

# macOS or Linux, when a program expects lowercase variables
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:7890"

# Verify that the variables exist in the current shell
env | grep -i proxy

On Windows, remember that a variable set in one PowerShell window is not necessarily present in a newly opened Command Prompt window. Likewise, a graphical IDE launched before the variable was set will keep its original environment. Start a fresh terminal or restart the editor after changing proxy variables. For a durable development setup, place only non-secret proxy settings in the appropriate shell profile, and avoid recording credentials in command lines.

Choose System Proxy, Environment Variables, or TUN Mode

There are three practical ways to connect Claude Code to Clash. The lightest method is a shell-level proxy variable. It is easy to enable for one project and easy to remove, but it works only when the application and its dependencies honor the variables. The second method is the operating system proxy toggle in Clash Verge. This helps applications that read Windows, macOS, or desktop environment proxy settings, but command-line runtimes are inconsistent. The third method is TUN mode, which creates a virtual network interface and captures traffic below the application layer.

Start with shell variables because they make the test boundary clear. Launch Claude Code from the same terminal where the variables are defined, then watch the Clash connection panel while signing in or sending a small request. If no relevant connection appears, the process may not be using those variables, the hostname may be resolved by another component, or the request may have failed before network access. This is more useful information than repeatedly changing nodes without observing the process.

System proxy mode is convenient when Claude Code opens a browser for OAuth. The browser may follow the system setting while the original terminal process still uses a direct route. That can create a confusing half-success: the authorization page loads, the user grants access, and the CLI waits forever for the token exchange or callback. In that situation, examine both the browser connection and the terminal connection. The browser’s success does not prove that the CLI’s HTTPS socket took the same path.

TUN mode is appropriate when Claude Code launches helper processes, native binaries, Git commands, package managers, or other components that ignore traditional proxy variables. In Clash Verge, enable the TUN feature and approve the system or helper permission requested by your platform. Use the recommended stack mode and DNS configuration supplied by the client unless you have a specific reason to change them. On Windows, a virtual adapter or service may require administrator approval. On macOS and Linux, the application may need permission to install a network extension or create a TUN device.

Do not enable TUN mode while several other proxy clients are active. Multiple virtual adapters, competing DNS listeners, or two clients attempting to manage the same system proxy can produce intermittent loops. Disable old VPNs and Clash forks during testing, then reboot if an adapter remains in a failed state. When TUN is active, check that the default route and DNS requests are handled as intended. A TUN interface that captures TCP but leaks DNS can still produce inconsistent rule matches and misleading authentication failures.

Route Claude Code and Supporting Hosts

Claude Code traffic is usually a group of related connections rather than one permanent hostname. The authentication flow may contact an account or console domain, while model requests use an Anthropic API endpoint. Installation and updates may involve npm, a package CDN, GitHub, or another release host. Your exact host list can change as the product evolves, so do not blindly copy a static “Claude domains” list from an old post. Use the live connection log during a controlled sign-in and a small model request, then record the hostnames that actually appear.

A sensible policy often separates three classes. First, route Anthropic authentication and API hosts through a stable proxy group. These connections should not switch nodes in the middle of a login or long model stream. Second, decide separately how package registries and release sources should travel. They may work through DIRECT on your network, but if metadata loads while tarballs time out, the registry and CDN need to be inspected independently. Third, keep local development traffic, private intranet addresses, and local machine names on DIRECT unless your organization requires another route.

rules:
  - DOMAIN-SUFFIX,anthropic.com,AI
  - DOMAIN-SUFFIX,claude.ai,AI
  - DOMAIN-SUFFIX,github.com,DEV
  - DOMAIN-SUFFIX,githubusercontent.com,DEV
  - DOMAIN-SUFFIX,npmjs.org,DEV
  - DOMAIN-SUFFIX,npmjs.com,DEV
  - DOMAIN,registry.yarnpkg.com,DEV
  - DOMAIN-SUFFIX,local,DIRECT
  - GEOIP,LAN,DIRECT
  - MATCH,DIRECT

The example is a starting model, not a universal rule set. Replace AI and DEV with groups that exist in your profile. Some providers already define rule providers or use a different syntax. More importantly, avoid placing a broad GEOIP or catch-all line above the explicit AI rules. Clash evaluates rules in order; an earlier match wins. If an Anthropic hostname is captured by a domestic or direct rule first, adding a correct rule later will not change the result.

When debugging, temporarily use a manually selected node rather than a URL-test group. Authentication is stateful, and a node change between browser authorization and token exchange can look like an invalid session. Long streaming requests also benefit from route stability. Once the flow works, you can return to an automatic group and test its failover behavior deliberately. Record the selected node, approximate latency, and whether the request completed; “fastest” based on a short ping is not the same as reliable for a sustained AI response.

DNS deserves equal attention. Redirection rules operate on the hostname that Mihomo sees, while fake-IP or redirection modes can change how applications perceive an address. If DNS is resolved outside Clash, the connection may bypass the expected domain rule or receive an answer that is unreachable from the selected route. Use Clash Verge’s DNS settings consistently, avoid stacking several encrypted-DNS clients during diagnosis, and check the resolved result together with the matched rule. Change one DNS option at a time so that you can identify which setting improved or damaged the path.

Test Authentication, Streaming, and Updates

After the route is configured, test in layers instead of jumping directly into a large coding task. First, verify that Clash itself can reach a normal HTTPS destination. Second, check that the terminal sees the intended proxy environment or that TUN mode captures the process. Third, begin the Claude Code login flow and watch for new connections. If the browser opens but the terminal remains idle, investigate callback handling, environment inheritance, and whether the CLI was started before the proxy was enabled.

Once authentication completes, send a small request in a disposable project. Ask Claude Code to inspect a short README or explain a harmless function rather than immediately authorizing broad file changes. A short request confirms that the model endpoint is reachable and that response streaming works. If the first words appear and then the response stops, look for node switching, idle timeouts, connection resets, or a proxy group whose health check does not represent long-lived HTTPS streams.

Package operations should be tested separately. Run the package manager command that matters to your workflow, such as a dependency metadata check or a non-destructive version query. npm, pnpm, yarn, Git, and release download tools can each use different registries and proxy behavior. If installation fails with ETIMEDOUT while Claude requests succeed, do not change the Anthropic rule first. Inspect the registry hostname, redirect target, and tarball CDN in the connection list. Conversely, a successful package download does not validate the AI API route.

• Authentication stalls: confirm that both the browser and CLI have a working route, then check whether the callback or token exchange host was captured by the same policy.
• Unauthorized response: verify the account, API key, organization settings, and local clock. A proxy cannot correct invalid credentials or an account without access.
• Model request times out: test a stable node, inspect the API hostname, and disable automatic node switching during the reproduction.
• Streaming stops midway: check connection resets, idle timeout settings, and whether a network security product is terminating long HTTPS sessions.
• Install or update fails: inspect npm, pnpm, yarn, GitHub, and CDN destinations independently rather than assuming one registry rule covers every redirect.
• Claude Code works in one terminal only: compare environment variables, shell startup files, IDE launch environments, and whether one terminal was started before Clash became active.

Once everything works, document the setup for your future self. Record the Clash client version, core version, profile name, mixed port, selected rule groups, TUN status, and the date when the profile was last refreshed. Do not record subscription secrets or tokens in that document. A short troubleshooting note can save considerable time after an operating system update, a provider migration, or a client reset. If a later failure appears, compare the current connection log with the known-good notes before making several changes at once.

Compared with browser-only proxy extensions, terminal wrappers and lightweight VPN tools often provide poor visibility into which subprocess was captured, which rule matched, or why a streaming connection changed nodes; some also require manually maintained environment variables with little documentation. Clash Verge is not automatically the right choice for every developer, but in this Claude Code scenario it offers a useful balance of profile management, Mihomo routing, TUN coverage, mixed-port compatibility, and connection-level diagnostics. If you want a maintained Clash-based client that lets you reproduce the setup above and inspect each terminal request instead of guessing, you can download Clash Official Site and use it as the starting point for a more reliable Claude Code workflow.