Claude Code With Clash Verge: Reliable Terminal Access Setup

Why Claude Code Needs a Terminal Proxy Plan Explained

Claude Code is designed for the shell rather than a browser tab. It reads a project directory, runs commands with your approval, exchanges prompts and tool results with Anthropic services, and keeps enough state alive to make an interactive coding session feel continuous. That workflow creates a different networking problem from opening a webpage. A browser may already follow the operating system proxy, while the terminal process, its login helper, Git, npm, and any child process may use separate proxy rules—or no proxy at all.

This is why a developer can visit an AI website successfully and still see Claude Code authentication failures, stalled requests, or a session that disconnects after the first response. The browser used for sign-in may reach the authorization page through Clash Verge, but the CLI may fail when it exchanges the callback code, refreshes a token, or opens a long-lived API connection. Similarly, the command used to install the package can succeed through one registry path while the running application later connects directly to an endpoint that is unavailable on the local network.

Clash Verge helps when it is treated as a complete terminal connectivity layer, not merely as a tray application that changes browser proxy settings. You need to decide which traffic should be captured, which outbound group should carry Claude-related requests, how DNS should resolve service hostnames, and whether a system proxy is enough for your shell. For many users, the most reliable arrangement is a stable Mihomo profile, a carefully selected proxy group, and either explicit terminal environment variables or TUN mode for applications that ignore ordinary HTTP proxy settings.

Symptoms and Root Causes to Check First in Detail

Before changing several settings at once, classify the failure. A useful diagnosis starts with the phase that breaks: installation, authentication, the first model request, tool execution, or a long-running session. Each phase can use different hosts and different capture behaviour. Treating every error as a “bad node” often wastes time and makes the configuration harder to understand.

• Installation fails: npm, pnpm, or another package manager cannot retrieve metadata, a tarball download hangs, or a Git dependency times out. This normally points to registry, CDN, or certificate routing rather than Claude Code itself.
• Browser login opens but never completes: the browser reaches the authorization page, but the CLI cannot receive or exchange the callback. Check localhost callback handling, terminal proxy variables, and whether the token exchange host took a different route.
• Authentication repeatedly expires: the initial sign-in works, but refresh requests fail later. This can indicate inconsistent DNS, a proxy that interrupts persistent connections, a system clock problem, or a process that starts without the same environment variables as your interactive shell.
• The first prompt stalls: the CLI starts normally but waits indefinitely after submitting a request. Look at the Clash Verge connection log while reproducing the problem; confirm whether the relevant remote host appears and which rule selected it.
• Short prompts work while larger tasks fail: long responses, streaming output, or repeated tool calls expose packet loss, connection reuse, node instability, and idle timeout problems that a quick connectivity check will not reveal.
• Git or package commands fail only inside Claude Code: child processes may not inherit the proxy variables you set in one terminal, or the application may launch them with a restricted environment. Confirm the environment from the same process context instead of testing only in a separate shell.

There is also an important distinction between HTTP proxy support and traffic capture. A terminal program that understands HTTP_PROXY or HTTPS_PROXY can send requests to Clash Verge’s mixed port. A program that ignores those variables will continue to open direct sockets. System proxy mode covers applications that consult the operating system settings, but it does not magically intercept every native process. TUN mode works at a lower network layer and can cover more applications, although it introduces virtual adapter permissions, DNS choices, and possible conflicts with VPN software.

Start by opening Clash Verge’s connection view and reproducing one failure. Search for the hostname or a distinctive part of it rather than guessing from an old rule list. If no matching connection appears, the process is probably bypassing the system proxy and the mixed-port variables. If a connection appears with DIRECT, the rule order or profile policy is the next place to inspect. If it uses the expected proxy group but repeatedly disconnects, test another node and examine latency, TLS errors, and connection duration instead of rewriting every rule.

Prepare a Stable Clash Verge Profile Made Clear

Import a subscription that explicitly supports the Mihomo or Clash Meta feature set used by your client. Clash Verge is a graphical frontend; the active core and the downloaded profile determine whether modern transports, rule providers, DNS modes, and TUN settings are available. If your provider offers several subscription formats, choose the Mihomo-compatible export rather than a legacy profile intended for an abandoned client.

After importing the profile, activate it and verify that the proxy groups contain more than one usable option. For interactive coding, a group with a stable manual choice is often easier to troubleshoot than an aggressively changing automatic group. URL testing can be useful, but a group that switches nodes during a long Claude Code session may interrupt streaming output or invalidate a connection that was already established. Begin with one known-good node, then compare alternatives deliberately.

A practical profile should separate ordinary domestic traffic from service traffic that requires the proxy. The exact hostnames can change as providers evolve their authentication and API infrastructure, so do not blindly copy an old “AI rules” list. Prefer a provider-maintained rule set, inspect live connections, and keep application-specific rules narrow. A broad rule that sends every cloud, code-hosting, or package domain through one remote group can make development slower and can also route private repositories or local services unnecessarily.

Configure the Terminal and TUN Coverage Under the Hood

For a terminal-first workflow, first test explicit proxy variables because they are easy to enable, disable, and audit. In Clash Verge, identify the local mixed port shown by the application. Then set the variables in the same shell from which you launch Claude Code. A typical HTTP-compatible setup looks like this:

# Replace 7890 with the mixed port shown by Clash Verge
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 NO_PROXY=localhost,127.0.0.1,::1

The variable names are case-sensitive in some tools and duplicated uppercase/lowercase variants are handled differently across runtimes. If a package manager or SDK documents its own proxy option, follow that documentation rather than assuming every client reads ALL_PROXY. Keep NO_PROXY focused on local callback and development addresses. Adding a large, unverified list of public domains to NO_PROXY can accidentally send authentication or API requests direct.

1. Confirm the local listener: open Clash Verge and record the mixed port, then verify that no other application is already occupying it. A wrong port produces immediate connection refusal and can look like a remote outage.
2. Set the variables in a fresh shell: export HTTP_PROXY, HTTPS_PROXY, and, when supported, ALL_PROXY. Keep localhost in NO_PROXY so a browser callback and local development server are not sent through the remote proxy.
3. Test from that exact shell: use a harmless HTTPS request to a service you are authorized to access, then inspect the Clash connection log. The important result is not only a successful response; it is proof that the process created a connection through the expected local listener.
4. Launch Claude Code from the same environment: do not start the CLI from a desktop shortcut while testing variables that exist only in your terminal. If you use a shell alias, task runner, IDE terminal, or launch script, print the relevant environment there as well.
5. Reproduce one failure and inspect the match: note the hostname, selected rule, proxy group, and disconnect timing. Change one variable at a time so the improvement can be attributed to a specific setting.
6. Enable TUN only when required: if the CLI or a child process ignores proxy variables, activate TUN mode in Clash Verge, grant the requested administrator or system extension permissions, and retest with explicit variables removed if necessary.

TUN mode is useful when Claude Code launches native helpers, language runtimes, or tools that do not understand proxy environment variables. It can also make behaviour more consistent between a terminal, an IDE, and a background process. However, it is not automatically better for every machine. Check that the TUN stack does not conflict with another VPN, corporate endpoint agent, virtualization platform, or security product. If local services stop resolving after TUN is enabled, review the DNS and route exclusions before changing the Claude-specific rules.

On Windows, service mode and administrator permissions may be required for the virtual adapter. On macOS, system extension approval and network permission prompts can affect whether the adapter is actually active. On Linux, the interface and routing table may require elevated privileges. In all three cases, confirm the operational state in Clash Verge rather than relying on a toggle that appears enabled. A TUN switch can remain selected while the helper service has failed or the interface has been removed.

Diagnose Authentication, DNS, and Node Quality Explained

Authentication should be tested as a sequence, not as one button. First check whether the browser authorization page opens. Next check whether the CLI receives the callback or returns to the prompt. Finally check whether the application can make an authenticated request and maintain the session. These stages may involve different processes and therefore different proxy inheritance. If the browser succeeds but the CLI does not, focus on the terminal environment and callback path instead of replacing the account.

Local callback addresses deserve special attention. OAuth-style login flows commonly open a browser and listen on a loopback address for the result. Sending localhost through a remote proxy can prevent the callback from reaching the waiting CLI. That is why a narrow NO_PROXY=localhost,127.0.0.1,::1 entry is generally safer than disabling all proxy variables during authentication. If your environment uses a custom local hostname, add only that hostname after confirming it resolves to the local machine.

DNS problems can produce confusing rule matches. With fake-IP or enhanced DNS modes, the process may receive a synthetic address while the policy engine still needs the original domain name to choose a rule. A misconfigured DNS mode can make a remote service appear local, send it to DIRECT, or cause a TLS certificate mismatch. Use the connection log and DNS settings together. Do not switch among redirection-host, fake-IP, and system DNS modes randomly; record the original configuration so you can revert after each test.

Node quality matters more for Claude Code than a single speed-test number suggests. A node may download a small webpage quickly but perform poorly during a sustained streamed response. Test at least two nodes from the same group and compare:

• Time to complete the sign-in or token exchange.
• Whether the first response begins promptly.
• Whether a longer request stays connected without repeated resets.
• Whether the selected node changes unexpectedly during the session.
• Whether Git, package downloads, and other required development services remain usable.

Use the narrowest rule change that proves the cause. If the log shows the request taking DIRECT, adjust the relevant domain policy or provider rule. If it already uses the intended group, test another node before editing YAML. If the request never reaches Clash, repair proxy inheritance or enable TUN. This three-way distinction—wrong rule, bad outbound, or missing capture—prevents the common cycle of changing all three at the same time.

Build a Reliable Daily Workflow in Detail

Once the initial test works, make the setup repeatable. Put stable proxy exports in a shell function or project-specific launcher rather than scattering them across multiple dotfiles. If you work on public repositories and private company code, consider separate launch profiles so credentials, package registries, and routing assumptions are not mixed. A project-level launcher can also print the active proxy mode at startup, which helps explain why an IDE terminal behaves differently from a normal shell.

Keep local traffic local. Development servers, container bridges, database ports, SSH connections to machines on your private network, and callback listeners often belong in NO_PROXY or a direct rule. At the same time, do not assume that every code-hosting request is local simply because the repository belongs to you. Git over HTTPS, Git over SSH, release downloads, package registries, and container registries may each need a separate configuration. Test the path actually used by your project.

When Claude Code invokes tools, watch for the difference between the parent process and the child process. A shell launched by the CLI may inherit environment variables, but an IDE task, language server, Docker container, or system service may not. If a command works when typed manually but fails when generated as a tool action, compare the environment, working directory, DNS view, and network namespace. This is often an integration boundary rather than a model or Clash error.

Security is part of reliability. Treat the subscription URL as a credential, keep API keys outside shell history where possible, and avoid logging full authorization headers while debugging. Do not solve an intermittent connection by disabling certificate verification, opening every port, or adding broad direct rules. A configuration that “works” only after removing TLS checks is not a reliable setup; it is a new security problem that can expose source code, tokens, and prompts.

Finally, update one component at a time. If you update Clash Verge, the Mihomo core, the subscription, and the Claude Code package together, you lose the ability to identify the change that fixed or caused the problem. Export or copy your current profile, note the date, and make a small test after each update. When a session becomes unstable, return to the last known-good node and profile before experimenting with advanced overrides.

Compared with browser-only proxy extensions, generic VPN clients, or legacy Clash forks, a terminal setup built around Clash Verge gives you clearer rule visibility, live connection evidence, Mihomo-compatible routing features, and a practical path from explicit shell variables to TUN capture when a child process ignores ordinary proxies. Those alternatives may be simpler for casual browsing, but they often provide little insight into why authentication, package downloads, or streamed coding requests fail. If you want one place to inspect the route, select a stable node, and reproduce the configuration described here, download Clash and use it as the starting point for a controlled Claude Code terminal setup.