Why Claude Code needs a real proxy path
Claude Code is not simply a webpage opened in Chrome. It is a terminal-based coding assistant that may need to authenticate, establish API sessions, stream model output, inspect project files, and keep a long-running connection alive while an agent task is running. Each part of that workflow can expose a different networking problem. A browser test that loads a normal website therefore proves very little about whether Claude Code can complete sign-in or maintain an inference stream.
The terminal process also runs outside the browser's extension environment. It may inherit operating-system proxy variables, use its own HTTP client, resolve DNS through a different path, or ignore a proxy setting that was changed after the shell started. On macOS and Linux, HTTP_PROXY, HTTPS_PROXY, and ALL_PROXY can influence command-line tools, but not every dependency interprets those variables in exactly the same way. A configuration that works for curl may still fail inside Node.js, Python, or the Claude Code launcher.
Clash Verge helps by giving those processes a predictable outbound path. Its Mihomo-compatible core can accept traffic through a mixed port, expose a TUN interface, apply domain-based rules, and show connection logs that reveal which policy group handled each request. The important word is predictable. The goal is not to force every connection through the fastest-looking node, but to make authentication, model traffic, package downloads, Git operations, and ordinary domestic traffic behave according to deliberate rules.
Before changing credentials or reinstalling the CLI, separate the symptoms. A failed sign-in points toward authentication endpoints, browser handoff, or local callback behavior. A request that starts and then stalls points more strongly toward streaming, DNS, node stability, or an idle connection timeout. A command that cannot download an update may be using a different process environment from the command that successfully reaches the model service.
Install Clash Verge and import a subscription
Start with a current Clash Verge Rev or another maintained Clash Verge distribution that includes a Mihomo-compatible core. The exact menu labels can change between releases, so focus on the concepts rather than copying a screenshot from an older tutorial. Download the installer from a project release page or a source you can verify, select the package matching your operating system, and allow the application to create its local configuration directory when it first launches.
After opening the client, find the profile or subscription area. Most providers give you a subscription URL, usually ending in a YAML, YAML-compatible, or provider-specific endpoint. Copy the complete URL rather than copying only the visible part of a web dashboard link. In Clash Verge, add a remote profile, paste the URL, assign a recognizable name such as work-ai, and trigger an update. If the provider offers both Clash and generic formats, choose the Clash or Mihomo-compatible option unless its documentation says otherwise.
A successful import does not automatically mean the profile is usable. Open the profile preview and check whether it contains proxies, proxy-groups, and rules. Some providers return an HTML error page when a subscription has expired or when a request requires an account cookie. That page can be saved with a YAML-looking filename but will fail as soon as Mihomo parses it. A blank profile, a parser error, or a profile with no proxy groups should be treated as an import problem before you investigate Claude Code.
Choose the imported profile as active, then select a real node in its primary proxy group. Avoid testing with an empty selector, a group whose members are all unavailable, or a load-balance group that is still performing its first health checks. For the first connection test, a manually selected node is easier to reason about. Once authentication and a short model request work, you can move to url-test, fallback, or another automated policy.
| Check | What to verify | Why it matters |
|---|---|---|
| Profile source | The URL comes from your provider or a trusted administrator | Prevents importing an altered or expired configuration |
| Parser result | Clash Verge accepts the file without YAML or schema errors | Confirms the core can read the profile |
| Active group | A concrete node is selected for the first test | Removes automatic selection from the diagnosis |
| Core status | The Mihomo core is running and the local controller responds | Separates application issues from remote connectivity issues |
Keep the provider's original profile intact when possible. If you need custom rules, use an override or a local copy rather than editing a remote subscription that will be overwritten during the next update. Record the profile update time and the selected group while troubleshooting. Node lists can change between tests, and without that information a later comparison may be misleading.
Choose the right proxy mode for terminal access
Clash Verge normally gives you several ways to send traffic through the core. System proxy mode changes the operating system's HTTP and HTTPS proxy settings. It is convenient for applications that honor those settings, and it is often enough for a browser, package manager, or a terminal process that reads standard environment variables. However, command-line tools do not all behave alike. Some read only uppercase variables, some prefer lowercase variables, and some ignore proxy variables for selected requests.
A mixed port accepts both HTTP proxy and SOCKS5-style connections through one local endpoint. In a typical setup it may look like 127.0.0.1:7897, but you must use the port displayed by your own Clash Verge installation. To test a shell session explicitly, set temporary variables instead of changing your whole operating system:
export HTTP_PROXY=http://127.0.0.1:7897
export HTTPS_PROXY=http://127.0.0.1:7897
export ALL_PROXY=socks5://127.0.0.1:7897
export NO_PROXY=localhost,127.0.0.1,::1Do not assume that every program should receive every variable. Some tools interpret ALL_PROXY as a SOCKS URL and fail when given an HTTP URL. Others support only HTTP CONNECT. If a command behaves strangely, inspect its documentation and try a minimal environment. You can also launch a single test command with variables attached, which avoids contaminating unrelated development tasks:
HTTPS_PROXY=http://127.0.0.1:7897 \
HTTP_PROXY=http://127.0.0.1:7897 \
claudeTUN mode works at a lower level. It creates a virtual network interface and allows the Mihomo core to capture traffic from applications that do not understand system proxy settings. This can be useful when Claude Code launches helper processes, uses a runtime that ignores environment variables, or contacts an endpoint through a library that does not expose proxy configuration. TUN mode also carries more responsibility: it can capture package managers, Git, containers, local services, and other traffic you did not intend to proxy.
Use system proxy or explicit terminal variables first because they are easier to scope and reverse. Move to TUN only when logs demonstrate that the Claude Code process is bypassing the mixed port or when the application stack cannot be configured otherwise. Before enabling TUN, review the mode, DNS behavior, auto-route option, and process permissions. Exclude local networks and private services when appropriate. A TUN configuration that fixes Claude Code but breaks a company intranet or a local database is not a successful final configuration.
After changing a mode, completely restart the terminal and Claude Code process. Long-lived shells, editor terminals, background agents, and authentication helpers can retain old variables or old DNS state. Test the effective environment with a simple command, then run Claude Code from the same terminal where you made the change. If you use an IDE-integrated terminal, remember that the IDE may have started before Clash Verge or before the variables were updated.
Build practical routing rules for Claude Code
Once the basic proxy path works, improve reliability with rules rather than leaving every connection to a broad final match. First identify the hostnames that actually appear in the Clash Verge log during authentication and model requests. Do not copy an unverified domain list from a forum and assume it remains correct forever. Service providers can change authentication, telemetry, documentation, update, and API endpoints. Your own logs are the best evidence for the traffic generated by your version of Claude Code.
Think in traffic families. The first family is account and authentication traffic, which may involve a browser handoff or an authorization service. The second is model and inference traffic, where long responses make node stability and stream preservation important. The third includes update servers, package registries, Git hosts, and documentation sites. The fourth is local development traffic such as localhost, private IP ranges, internal Git servers, databases, and container bridges. These groups should not be treated identically.
A generic rule design might look like this:
rules:
- DOMAIN-SUFFIX,example-auth-service.com,AI
- DOMAIN-SUFFIX,example-model-service.com,AI
- DOMAIN-SUFFIX,github.com,DEV
- DOMAIN-SUFFIX,npmjs.org,DEV
- DOMAIN-SUFFIX,internal.example,DIRECT
- IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
- IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
- GEOIP,LAN,DIRECT
- MATCH,DIRECTThe domains above are placeholders, not a recommendation to route those exact names. Replace them only after confirming the hostnames in your logs and provider documentation. The key structure is that AI endpoints share a stable policy group, development resources have their own behavior, private networks remain direct, and the final rule is explicit. If your environment requires all unknown external traffic to use a proxy, change the last line to a proxy group, but understand that this also affects software you did not intend to send through the tunnel.
Use DOMAIN-SUFFIX carefully. It matches a registrable suffix and can cover multiple subdomains, which is useful when a service legitimately distributes traffic across authentication and API hosts. It can also be too broad if the suffix is shared by unrelated products. Prefer a specific DOMAIN rule when only one hostname is confirmed. Avoid inserting a broad GEOIP or IP-CIDR rule above domain rules until you understand the consequences. An IP-based rule can win before a hostname-based rule and make the configuration appear inconsistent.
Rule order is decisive. Mihomo evaluates from top to bottom, so an early MATCH,DIRECT makes every later rule unreachable. Likewise, a broad provider rule above a local-network exception can capture traffic that should never leave your machine. Keep private and local exclusions near the top, place specific AI and development rules next, and reserve broad geographic or final-match behavior for the bottom.
Choose a dedicated AI policy group rather than pointing every rule at a group named PROXY. A dedicated group lets you select a stable node for long model streams while using a different group for ordinary browsing or downloads. If your provider has a health-check group, test whether it changes members during an active Claude Code task. A fast probe result is not proof that a node can preserve a long HTTP stream. For agent sessions, consistency can matter more than the lowest initial latency.
After editing rules, reload the configuration and watch the log in real time. Look for the hostname, matched rule, selected policy group, and final outbound. If the request never appears, the process may be bypassing Clash or failing before it opens a network connection. If it appears as DIRECT unexpectedly, inspect rule order and DNS mode. If it reaches the intended group but repeatedly resets, compare another node and check whether the issue follows the node rather than the rule.
Verify the setup and troubleshoot failures systematically
Begin with a controlled connectivity check through the same shell that will launch Claude Code. Test the local mixed port, then test a known endpoint that your environment is permitted to access. The purpose is not to prove that every website works; it is to confirm that the shell can reach the local proxy and that Clash Verge records the resulting connection. A successful browser page is weak evidence if the terminal process uses a separate environment.
For a sign-in failure, check whether the browser authorization page opened, whether the callback returned to the terminal, and whether the authentication hostname appears in the Clash log. A browser-based login can succeed while the CLI's follow-up token exchange fails. Conversely, the CLI may complete the remote exchange but fail to communicate with a local callback port because TUN or firewall rules changed loopback behavior. Keep localhost and 127.0.0.1 in NO_PROXY unless your specific workflow requires otherwise.
For a timeout during model output, record when the timeout occurs. A failure before any response suggests DNS, TCP, TLS, or policy selection. A failure after several paragraphs suggests an unstable node, a reset HTTP stream, an idle timeout, or a proxy that does not handle the connection style well. Try one manually selected node, then a second node in the same group. If both fail at the same point, inspect the client and service state. If only one node fails, stop rewriting rules and remove that node from the test.
For slow requests, distinguish connection latency from model generation time. Clash logs can show when a connection was opened and which outbound handled it, but they cannot make a remote model generate tokens faster. Compare a short prompt with a repository task, and avoid judging a node from one large request. Long coding sessions are sensitive to packet loss and stream resets that a quick HTTP check will never reveal.
| Symptom | Likely area | First action |
|---|---|---|
| Login page never opens | CLI environment, browser handoff, or DNS | Check process variables and authentication logs |
| Login succeeds but CLI remains waiting | Callback or token exchange | Keep loopback direct and inspect the next hostname |
| Prompt starts then times out | Node stability or long-stream handling | Try a fixed node and compare connection resets |
| Terminal bypasses Clash | Missing variables or unsupported proxy library | Use explicit variables, then evaluate TUN mode |
| Only internal tools break | Overbroad TUN or proxy rules | Add private-network and internal-domain exclusions |
When you change one variable, repeat the same test. Do not simultaneously switch the profile, node, DNS mode, TUN mode, and rule order; that destroys the comparison. Save a small troubleshooting record containing the date, Clash Verge version, active profile, selected group, shell variables, matched rule, and error text. This makes recurring failures easier to recognize after a subscription update.
Conclusion
Generic VPN applications and browser-only proxy extensions are convenient, but they often provide little visibility into terminal traffic. A browser extension may not cover Claude Code at all, while a one-click VPN can hide the distinction between authentication, inference, Git, package, and local-network connections. Some heavyweight clients also make split routing difficult to inspect, so users respond to every timeout by switching servers without learning which hostname failed.
Clash Verge offers a more useful workflow for technical users: explicit system-proxy and mixed-port options, optional TUN capture for applications that bypass environment variables, Mihomo rule evaluation, selectable policy groups, and connection logs that expose the actual decision path. The advantage is not a promise that every node is fast. It is the ability to reproduce a failure, isolate a hostname family, select a stable outbound, and keep local development traffic separate from external AI traffic. Once the initial profile and rules are correct, the same structure can support Claude Code, Git operations, package managers, and other terminal tools without turning the whole machine into an opaque tunnel.
Start with the smallest reliable setup: import a valid profile, select one known node, use explicit terminal proxy variables, keep loopback direct, and verify the authentication and model paths separately. Only then add TUN mode, automated groups, or broader rules. That measured sequence gives you a configuration that is easier to maintain when Claude Code, your provider subscription, or the Mihomo core changes.