Claude Code With Clash Verge: Reliable Terminal Access Guide

Why Terminal Proxy Settings Matter for Claude Code

Claude Code brings an AI-assisted development workflow to the command line. It can inspect a project, read local files, propose changes, run development commands, and communicate with remote services. That workflow depends on more than a browser connection. The terminal process must be able to resolve service domains, establish HTTPS connections, authenticate successfully, download required resources, and keep connections alive while a request is being processed. If only the browser is configured for a proxy, Claude Code can still fail even though ordinary websites open normally.

Clash Verge can solve this problem by exposing a local HTTP or SOCKS5 proxy and allowing terminal applications to use that endpoint. It can also operate in TUN mode, which captures traffic at the virtual network interface level instead of relying on each application to understand proxy variables. These are different mechanisms. An environment variable tells a proxy-aware program where to send requests; TUN mode redirects a wider range of device traffic through the Clash core. Choosing the narrower mechanism first usually makes troubleshooting easier.

There are several symptoms that look similar but have different causes. A login page may open in a browser while the command-line authentication callback fails because the terminal does not inherit the browser's proxy settings. An API request may reach the service but time out because the selected node is unstable or because a rule sends the domain to DIRECT. A package or model-related download may fail because the shell uses a different resolver, an expired proxy variable, or a network tool with its own configuration. The first step is therefore to separate three layers: Clash Verge itself, the terminal's proxy configuration, and the application or authentication flow.

Understanding Clash Verge Local Ports and Modes

Open Clash Verge and first confirm that the core is running. The exact labels vary between Clash Verge releases and mihomo-based builds, but the important values are the mixed port, HTTP port, SOCKS port, and external controller address. A mixed port accepts both HTTP proxy and SOCKS5-style connections on one listener, while separate HTTP and SOCKS ports make the protocol choice explicit. Do not copy a port number from an example without checking the active profile and system settings in your own installation.

A common local arrangement looks like this:

The loopback address 127.0.0.1 means “this computer.” It is normally the right address when Claude Code and Clash Verge run on the same desktop. If Clash Verge runs inside a virtual machine, container, remote desktop session, or another device, loopback may point to the wrong machine. In that case, use the reachable LAN address only after checking the listener's bind address and firewall policy. Exposing a proxy listener on all interfaces can allow other devices on the network to use it, so avoid broad binding unless that is an intentional and protected design.

Start with Rule mode rather than Global mode. Rule mode lets the profile determine which destinations use a proxy, which go direct, and which are rejected. Global mode is a useful diagnostic tool: if a request works only in Global mode, the node is probably reachable but the rule set is not matching the destination as expected. It is not necessarily the best permanent setting because development tools also contact package registries, source-control services, telemetry endpoints, certificate hosts, and authentication domains that may not all belong to the same routing category.

System proxy and TUN mode should also be treated separately. Enabling the system proxy changes the proxy settings exposed to applications that honor the operating system configuration. TUN mode works more broadly, but it introduces another layer involving virtual adapters, DNS interception, route installation, and permission prompts. A reliable setup does not require every feature to be enabled at once. Test the local proxy first, then add TUN only if an application remains outside the proxy path.

Hands-On: Configure and Verify the Terminal Proxy

The following procedure uses a temporary shell configuration so that the test is reversible. It is best performed in the same terminal session from which Claude Code will be launched. First select a known working proxy group in Clash Verge and confirm that the core is not paused. Then identify the active HTTP or mixed port. In the examples below, 7890 is only a placeholder for the port shown by your client.

Windows 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:7891"
$env:NO_PROXY    = "127.0.0.1,localhost,::1"

curl.exe -I https://example.com

PowerShell environment variables affect processes started from that shell after the variables are set. They do not retroactively alter an already running Claude Code process. Close or restart the terminal application if necessary, and launch the coding tool from the configured session. On Windows, curl may resolve to a PowerShell web command in some environments, so curl.exe is useful when you want the native curl behavior and its familiar proxy options.

macOS and Linux shells

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"
export NO_PROXY="127.0.0.1,localhost,::1"

curl -I https://example.com

Many Unix tools recognize lowercase names as well as uppercase names, but not every program behaves identically. For a predictable session, define both forms when a tool appears to ignore the uppercase variables:

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

Use a harmless HTTPS request to test connectivity before starting an interactive coding session. A response header proves that the request completed, but it does not prove that every Claude-related endpoint will work. It does confirm that the shell can reach at least one HTTPS destination through the selected local listener. To compare direct and proxied behavior, run the same request once with the variables set and once after temporarily using unset HTTP_PROXY HTTPS_PROXY ALL_PROXY http_proxy https_proxy all_proxy. Restore the variables afterward rather than adding permanent changes before the basic path is understood.

Test SOCKS5 and DNS behavior

When using SOCKS5, the distinction between local DNS resolution and proxy-side DNS resolution matters. A command using socks5:// may resolve the hostname locally before opening the SOCKS connection, while socks5h:// asks the SOCKS proxy to resolve the hostname. The latter can avoid local DNS failures or misleading results when the destination is reachable only through the proxy path.

curl --proxy socks5h://127.0.0.1:7891 -I https://example.com

If the HTTP proxy test succeeds but the SOCKS test fails, check the port and protocol rather than changing the routing rules immediately. If both fail, inspect Clash Verge's connection log. No matching connection usually means the terminal did not use the proxy variable, while a rejected or timed-out connection indicates that the request reached the core and encountered a node, DNS, TLS, or rule problem.

Launch Claude Code after verification

Only after the basic request works should you start Claude Code from the same terminal. Keep the first test small: open a non-critical project, ask for a local file summary, and then perform one network-dependent action. This separates local file and shell permissions from authentication and remote request problems. If the tool has its own documented proxy or network settings, those settings take precedence over generic shell variables in some versions. Check the tool's help output and configuration documentation instead of assuming that every option follows curl's naming conventions.

Design Routing Rules for Development Services

Once the terminal can use Clash Verge, routing quality becomes the next concern. A development session may contact several classes of destination: the main service API, authentication and browser handoff domains, package registries, language or toolchain mirrors, source-control hosts, certificate or time services, and local network addresses. Sending all of them through one policy may work, but it makes failures harder to classify. A better profile uses a named proxy group and keeps local addresses direct.

The exact domain list depends on the service, account region, installed integrations, and the version of the command-line tool. Do not invent a universal list from an old configuration. Instead, observe the Clash Verge connection log during sign-in and during a normal request. Identify the hostname, confirm whether it is an API endpoint or an authentication endpoint, and add a narrow rule only when the observed behavior justifies it.

rules:
  - DOMAIN,localhost,DIRECT
  - DOMAIN,127.0.0.1,DIRECT
  - IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - DOMAIN-SUFFIX,example-development-service.com,Claude-Proxy
  - RULE-SET,development-services,Claude-Proxy
  - MATCH,Default

The domains above are illustrative placeholders, not a recommendation to route a real service by an unverified suffix. Replace them with the domains shown by your own logs or with a maintained rule provider that you trust. Keep the policy names consistent: Claude-Proxy and Default must exist under proxy-groups, and the spelling, capitalization, and spaces must match exactly.

Rule order is decisive. Localhost and private network ranges should be handled before broad proxy rules. A specific authentication or API domain should appear before a broad catch-all category if the two policies differ. MATCH belongs at the bottom because it handles every connection that reaches it. A rule placed after MATCH is unreachable and cannot repair a routing mistake.

Use DOMAIN-SUFFIX carefully. It matches the specified domain and its subdomains, but a suffix that is too broad can route unrelated services through the same proxy. Prefer an exact DOMAIN rule when the log shows one stable hostname, and use a suffix only when subdomains are genuinely part of the service. Avoid routing by a keyword such as “api” or “auth” unless there is no more precise option; keyword rules can capture unrelated destinations.

For mihomo profiles, RULE-SET, GEOSITE, and related features may be available depending on the profile and core version. A profile intended for the original Clash Premium core may not accept every mihomo-specific rule type. If Clash Verge reports a configuration parse error, check the active core, the profile syntax, and the policy names before modifying unrelated sections.

TUN Mode, DNS, and Authentication Boundaries

Environment variables are usually the least invasive starting point, but they only help applications that honor them. Some native programs, language runtimes, credential helpers, and subprocesses ignore HTTP proxy variables or deliberately open their own sockets. If the terminal test succeeds but Claude Code or one of its child processes never appears in the Clash connection log, TUN mode may be appropriate.

Enable TUN mode in Clash Verge only after recording the working proxy configuration. Grant the requested administrator permission, select a suitable stack if the client offers more than one, and verify that the virtual interface is active. TUN capture can affect the whole device, including local services, virtual machines, containers, and other development tools. Keep local bypass rules for loopback, private address ranges, and internal domains so that a local development server does not accidentally leave the machine through a remote node.

DNS is part of the same path. With rule-based routing, the core may need the original domain name to select a policy. If the operating system resolves a hostname before Clash sees the connection, an IP-based rule can produce a different result from a domain rule. mihomo's DNS settings, enhanced mode, fake-IP behavior, and fake-IP filter can change how applications observe addresses. A fake address is not a real destination; it is a mapping maintained by the core so that the original domain can still be associated with the connection.

Do not add a blanket DNS bypass merely because one service fails. First check whether the DNS request appears in the Clash log, whether the selected upstream responds, and whether IPv6 returns an unreachable address. If the network has no usable IPv6 route, disabling IPv6 in the profile can prevent applications from trying an unavailable AAAA result before falling back to IPv4. If local domains end in .lan, .local, or another private suffix, place them in an appropriate fake-IP filter or direct-resolution policy according to the network design.

Authentication deserves a separate boundary. A browser-based login may open outside the terminal, while the command-line process waits for a callback on localhost. The external authentication page may need proxy access, but the local callback should remain direct. Never route loopback traffic through a remote proxy. If the browser returns successfully but the terminal still waits, check the callback port, local firewall, already running authentication processes, and whether the browser and terminal are using the same account or environment.

Diagnose Timeouts, Failed Downloads, and Unstable Sessions

When Claude Code reports a generic network error, begin with the smallest reproducible request. Confirm that Clash Verge shows an active node and that the terminal variables point to the current port. Then test DNS, HTTPS, and the target service separately. A failed DNS lookup points to the resolver path; a successful lookup followed by a connection timeout points more toward routing, the node, or a firewall; a TLS or certificate error requires checking system time, certificate stores, interception software, and whether the proxy path is being altered.

• No request in the Clash log: the process probably ignored the proxy variables, inherited a different environment, used a separate proxy setting, or was started before the variables were exported.
• Request appears as DIRECT: inspect rule order, domain matching, the active profile, and whether the process connected by IP instead of hostname.
• Request appears on the proxy but times out: test another node or group member, check congestion, and compare the same destination in Global mode.
• Authentication opens but callback fails: preserve direct access to loopback and inspect local firewall or port conflicts.
• Downloads stop midway: check whether the tool supports resume, whether the proxy node handles long-lived connections, and whether a package manager has its own timeout or proxy configuration.
• Only one subprocess fails: compare its environment with the parent shell and inspect whether it starts through a service manager, task runner, container, or IDE process.

Switching nodes can help, but it should be treated as a diagnostic action rather than a permanent fix. Record which node, rule, and destination were used when the request succeeded. If one node works only in Global mode and another works in Rule mode, the problem is likely the profile's matching logic rather than the command-line client. If every node fails for one domain while other domains work, investigate service-side restrictions, certificate validation, or a required authentication endpoint.

For long coding sessions, stability is more valuable than a momentarily high speed test. Prefer a proxy group with health checking or a manually verified fallback, provided the profile supports it. Avoid editing the subscription's generated YAML directly if Clash Verge will overwrite it on the next update. Use the client's profile override mechanism or a separate local configuration layer when available. Keep custom rules short, documented, and easy to remove.

A practical final checklist is simple. Clash Verge must be running with the intended profile and node. The local port must accept the protocol you selected. The shell must expose the variables before Claude Code starts. A basic HTTPS request must succeed. The connection log must show the expected domain and policy. Local callback addresses must remain direct. Finally, a small test project should complete authentication and one ordinary request before you rely on the setup for a longer development session.