Claude Code With Clash Verge: Setup Guide for Stable Access

Claude Code is becoming a practical command-line companion for developers who want to inspect repositories, edit files, run tests, and review implementation plans from a terminal. However, the experience depends heavily on stable access to the authentication service, model API, package registries, and documentation sites. A browser may appear to work while terminal requests still fail, because command-line applications do not always use the same proxy settings as Clash Verge or your browser.

This guide explains how to use Clash Verge with Claude Code in a controlled and maintainable way. You will learn how to import a subscription, select a reliable proxy group, enable the correct local port, configure terminal environment variables, choose between system proxy and TUN mode, and create targeted routing rules. The goal is not to send every connection through a proxy, but to make Claude Code traffic predictable without disrupting local development tools.

Understand the Connection Path Before Changing Settings

A common mistake is to assume that selecting a node in Clash Verge automatically proxies every application on the computer. In reality, applications can connect through several different paths. A browser may follow the operating system proxy, a terminal program may read HTTP_PROXY and HTTPS_PROXY, and another application may ignore both and connect directly through the operating system network stack.

Claude Code can also involve more than one type of request. The initial sign-in flow may open a browser or use an authorization endpoint. Model requests are sent to the service API. Installation and updates may use a package registry. Git operations, documentation lookups, and tool calls may contact additional domains. If only one of these paths is proxied, authentication can succeed while model requests fail, or installation can work while later requests time out.

Before configuring anything, confirm that you are using an account, subscription, and network connection permitted in your location. A proxy can improve transport reliability, but it cannot fix an invalid account, an expired subscription, insufficient API access, or a service-side outage.

Prepare Clash Verge and Select a Reliable Proxy

Install a current Clash Verge or Clash Verge Rev release from a trusted project source, then open the application and import your subscription URL. The exact names of menus can differ between builds, but the workflow is generally the same: add a profile, download the configuration, activate it, and select a proxy group.

1. Open the Profiles or Profiles/Subscriptions page in Clash Verge.
2. Add your subscription URL, or import a local YAML profile if your provider gives you one.
3. Click the profile update or download action and wait until the configuration is parsed successfully.
4. Activate the profile. An imported profile that is not active will not control traffic.
5. Open the Proxies page and choose a stable node or an automatic selection group.
6. Confirm that the selected group is actually used by the final rules in the profile.

For Claude Code, consistency is usually more valuable than the lowest single latency result. An unstable node can pass a quick delay test but fail during a long model response, a large repository operation, or an authentication redirect. Prefer a node with low packet loss, predictable HTTPS performance, and enough bandwidth for concurrent terminal requests.

Clash Verge normally exposes a local mixed port that accepts both HTTP proxy and SOCKS5 connections. Check the active port on the Settings page instead of assuming a default. Common examples include 7890, 7897, or another port chosen by the application. The port is local to your computer, so it must be used with the loopback address 127.0.0.1.

Do not enable several competing proxy layers at the same time during initial testing. For example, avoid combining an application-specific VPN, a browser extension proxy, system proxy, and TUN mode until the basic path is known to work. Multiple layers can introduce loops, unexpected DNS behavior, or confusing error messages.

Configure the Terminal Proxy for Claude Code

System proxy mode affects applications that honor the operating system proxy settings. Terminal programs are less consistent, so the most portable approach is to define proxy environment variables in the shell. Use the HTTP proxy URL for both HTTP and HTTPS variables because HTTPS requests commonly use the HTTP CONNECT method through a local proxy.

On macOS or Linux, open a new terminal and run the following commands. Replace 7890 with the mixed or HTTP port shown in Clash Verge.

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

HTTP_PROXY and HTTPS_PROXY are recognized by many package managers and network libraries. ALL_PROXY is useful for tools that support a generic proxy variable, but some programs prefer HTTP-style variables and may ignore it. NO_PROXY prevents local services, development servers, and loopback addresses from being sent through Clash.

For Bash or Zsh, place the variables in ~/.bashrc, ~/.bash_profile, or ~/.zshrc if you want them to apply to every new terminal. A safer alternative is to create a small project-specific script and source it only when working with Claude Code.

#!/usr/bin/env bash
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1,::1

echo "Claude Code proxy environment enabled"
echo "HTTP proxy: $HTTP_PROXY"

On Windows PowerShell, use the equivalent syntax:

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

These variables apply only to the current shell session unless you save them through your shell profile or Windows environment settings. Temporary variables are useful for troubleshooting because they make it easy to compare proxied and direct behavior. Start with a new terminal after changing persistent settings; an already open terminal will not automatically receive updated environment variables.

Some tools accept lowercase variable names while others check uppercase names. If a program does not appear to honor the configuration, you can define both forms:

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

Do not put subscription URLs, API keys, account tokens, or passwords inside shell scripts that may be committed to a repository. The proxy address is normally safe to expose locally, but credentials should remain in the appropriate environment or credential store.

Choose Between System Proxy and TUN Mode

Clash Verge usually provides a system proxy switch and a TUN mode switch. They solve different problems. System proxy mode changes operating system proxy settings, allowing compatible applications to send HTTP and HTTPS traffic to Clash. It is simple, transparent, and a good first choice when the terminal is configured with explicit environment variables.

TUN mode creates a virtual network interface and routes a broader range of traffic through Clash, including applications that do not understand HTTP proxy variables. It can be useful when Claude Code or an associated tool ignores the shell configuration. TUN mode also has greater impact: it may affect Docker, virtual machines, local development services, DNS behavior, and other applications that were previously direct.

Use one controlled method first. A practical sequence is to select a Clash node, enable the system proxy, set terminal environment variables, and test a simple HTTPS request. If that works, there is no immediate reason to enable TUN mode. If requests still bypass Clash, inspect the application behavior and then consider TUN mode.

When using TUN mode, review the DNS settings and bypass private networks where appropriate. Local addresses such as 127.0.0.1, 192.168.0.0/16, and development domains may need direct access. If a local service becomes unreachable after enabling TUN, check the routing mode and add a narrowly scoped direct rule instead of disabling all proxying.

Configure DNS and Targeted Routing

DNS problems often look like proxy problems. A domain may resolve to an unsuitable address, a local resolver may return inconsistent results, or an application may resolve a name before Clash has a chance to apply a domain rule. Mihomo-based profiles commonly use fake-ip with TUN mode because it preserves the original domain for rule matching. However, compatibility varies, so change DNS mode only after confirming the baseline configuration.

For a controlled custom profile, the important principles are to use reliable upstream resolvers, keep private domains direct, and avoid unnecessarily broad domain rules. The following example is a conceptual Mihomo configuration. Do not paste it over a provider-managed profile unless you understand which fields the provider expects you to preserve.

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - https://dns.cloudflare.com/dns-query
    - https://dns.google/dns-query
  fake-ip-filter:
    - "*.lan"
    - "*.local"
    - localhost.ptlogin2.qq.com

rules:
  - DOMAIN,localhost,DIRECT
  - DOMAIN-SUFFIX,local,DIRECT
  - DOMAIN-SUFFIX,lan,DIRECT
  - MATCH,Proxy

The final rule is important. If a profile uses a rule such as MATCH,DIRECT, selecting a proxy node in the interface may not proxy the domains you expect. Conversely, MATCH,Proxy sends everything not matched earlier to the proxy group, which can be convenient but may route ordinary local or domestic traffic unnecessarily. Always inspect the provider's existing rule order before adding custom entries.

Do not create rules based on guesses or broad keywords such as DOMAIN-KEYWORD,claude unless you have a clear reason. A keyword rule can match unrelated domains and may change behavior as services add new hostnames. Prefer specific DOMAIN or DOMAIN-SUFFIX entries that reflect the endpoints you have verified in your own logs. Service domains can change, so treat any list as a starting point rather than a permanent guarantee.

Test the Setup and Troubleshoot Failures

Test one layer at a time. First verify that Clash Verge is running and that the active profile has a selected proxy group. Next confirm the local port is listening. Then check whether the terminal variables are present and whether a simple HTTPS request appears in the Clash connection log.

echo "$HTTPS_PROXY"
curl -I --proxy "$HTTPS_PROXY" https://example.com
curl -I https://example.com
env | grep -i proxy

The first request explicitly tells curl which proxy to use. The second relies on the environment variable. Comparing the two helps identify whether the shell configuration is being read. In Windows PowerShell, use echo $env:HTTPS_PROXY and the corresponding curl.exe command if the PowerShell alias behaves differently.

Open Clash Verge's connection or logs panel while running the test. A request that appears there confirms that the application reached Clash. You can then inspect the matched rule, selected proxy group, and final node. If no request appears, the application is probably bypassing the proxy, the variable is misspelled, or another process is intercepting the connection.

• Sign-in fails, but ordinary websites work: check the browser used for authorization, callback handling, system proxy settings, and the connection log during sign-in.
• Sign-in succeeds, but model requests time out: verify that the terminal inherits the proxy variables and that the API request is not routed directly.
• Requests reset after several seconds: switch to a more stable node, test another proxy group, and inspect whether the timeout occurs during DNS, TLS, or response transfer.
• Package installation fails: configure the package manager separately if it does not honor shell variables, and check registry-specific proxy settings.
• Git operations fail: review Git's own configuration with git config --global --get http.proxy; Git may not use the same settings as your shell.
• Local development breaks: add local domains and private IP ranges to NO_PROXY or use direct routing for those destinations.

After changing a rule, restart the terminal application or create a fresh shell session. Some tools cache DNS results, connections, or authentication state. If a previous process was launched without proxy variables, modifying the current terminal does not change the environment of that running process.

Keep the Configuration Stable and Maintainable

A working setup should remain understandable. Record the Clash Verge port, the selected mode, the profile name, and the reason for any custom rule. Avoid editing a subscription-generated YAML file directly if updates overwrite local changes. Where supported, use a separate override or local patch mechanism, and keep a backup before changing DNS, TUN, or rule behavior.

Use a fixed node while diagnosing failures, then return to an automatic group after the connection is stable. Health checks should use a reliable HTTPS test URL and a reasonable interval; checking too aggressively can create unnecessary traffic and cause frequent switching. If Claude Code is performing a long operation, a slightly slower but stable node is often preferable to a rapidly changing “fastest” node.

Finally, disable the proxy environment when it is no longer needed if your workflow depends on direct access to internal services. A small helper script, a documented shell alias, and a clear NO_PROXY list are usually easier to maintain than a large collection of global rules. With the correct Clash Verge profile, an explicit terminal proxy, suitable DNS handling, and targeted routing, Claude Code can operate consistently without turning every connection on your computer into a proxy request.