1. Scope, intent, and boundaries
This guide is for developers who run Claude Code from a terminal and use Clash Verge as their local proxy client. Claude Code can inspect a repository, edit files, execute approved commands, and stream long responses while you work. That workflow is productive only when authentication, API requests, tool calls, and package-related traffic follow predictable network paths.
The objective is not to route every connection through a single remote server. A better design is usually selective routing: send Claude-related traffic through a stable proxy group, keep internal Git services and company systems on DIRECT, and choose whether public package registries should follow the proxy or your normal connection. This reduces unnecessary latency and makes failures easier to diagnose.
Clash Verge does not provide Claude access by itself, and a proxy cannot replace an eligible account, valid credentials, an active subscription, or an organization’s security approval. If your employer prohibits sending source code or prompts through a third-party relay, that policy takes priority over any configuration shown here. Treat proxy nodes as untrusted infrastructure, avoid placing secrets in prompts, and review Claude Code’s permission behavior before allowing it to modify a production repository.
The examples below use Mihomo-compatible concepts because current Clash Verge builds commonly rely on Mihomo-compatible profiles. Menu names can differ slightly between Clash Verge releases, operating systems, and localized interfaces. Always validate the resulting behavior in the client’s connection log instead of assuming that a rule was applied merely because the YAML file loaded successfully.
2. Why Claude Code needs more than a “VPN on” switch
A conventional VPN toggle assumes that one application, usually a browser, owns most of the network activity. Claude Code creates a more fragmented footprint. The terminal process may open HTTPS connections for authentication and model streaming, while an editor extension or an embedded terminal launches a separate child process with a different environment. Git, npm, Python, Docker, and remote development tools may continue making connections at the same time.
This is why a browser test can succeed while Claude Code still reports a timeout. Chrome may honor the operating system proxy, but a terminal process may read only HTTPS_PROXY. Conversely, a shell may use the proxy correctly while an IDE window keeps an old environment snapshot from before Clash Verge started. Long-lived connections create another variable: a request that works for a few seconds may fail later when a streaming connection is interrupted by an unstable node or an idle timeout.
The practical traffic categories usually include Claude authentication and API requests, browser-based login redirects, DNS resolution, telemetry or update checks, repository access, package downloads, and local tool calls that never need to leave the machine. The important distinction is between remote model traffic and local project operations. Running git diff, reading a local file, or invoking a test runner is not made more reliable by sending it through a proxy.
Clash Verge is useful because it exposes several control layers at once: system proxy mode for applications that follow OS settings, mixed-port proxying for explicit environment variables, rule-based routing for domains, and TUN mode for applications that ignore ordinary proxy variables. Each layer solves a different problem. Enabling all of them without understanding their interaction can produce loops, duplicate routing, or an apparently random mixture of direct and proxied connections.
3. Inventory Claude Code and project surfaces first
Before changing a profile, write down how you launch Claude Code. A process started from a normal shell is different from one started by VS Code, a JetBrains terminal, a remote SSH session, a container, or a task runner. Record the operating system, shell, editor, installation method, and whether the process is expected to inherit system proxy settings.
Next, separate the workflow into a few testable surfaces:
- Authentication: browser redirects, account pages, device authorization, or token refresh operations.
- Model session: HTTPS requests and streamed responses created by Claude Code.
- Project access: local files, Git remotes, package registries, and artifact servers.
- Child processes: shell commands, language servers, test runners, and package managers launched by the assistant.
- Network tools: commands such as
curl,npm,pip, or cloud CLIs that Claude Code may invoke with your approval.
Do not assume that every hostname used by the web login is also the hostname used for the model session. Authentication can involve redirects, static assets, identity providers, and security checks. Product endpoints may also change, so copying a hostname list from an old forum post is less reliable than observing current connections.
In Clash Verge, open the connection or logs view while reproducing one operation at a time. Start with login, then send a short Claude Code prompt, then run a harmless local command, and finally test a repository operation. Note the requested domain, selected rule, selected proxy group, and whether the connection was closed or kept open. This small inventory tells you which rule is missing and prevents an oversized catch-all rule from masking the real issue.
4. Choose the right Clash Verge mode
For many desktop applications, System Proxy is the least invasive starting point. It allows applications that respect the operating system’s HTTP or SOCKS proxy settings to use Clash Verge while applications with explicit direct networking remain unchanged. This is often sufficient for browser authentication and terminal tools that inherit system settings, but it is not universal.
A mixed port is useful when you want to configure the terminal explicitly. The following example uses a placeholder port; check the actual value shown by Clash Verge before exporting it:
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=127.0.0.1,localhost,.local,internal.example.com
Do not blindly set every variable in every shell startup file. First test the current session, then decide whether persistence is appropriate. NO_PROXY is especially important for local services, loopback addresses, Kubernetes APIs, and corporate domains that must remain on an internal route. A badly chosen wildcard can send private traffic to an external node or cause internal services to fail certificate validation.
Use TUN mode when Claude Code or its parent application ignores system proxy settings and does not honor environment variables. TUN can capture more traffic, including applications with their own networking stack, but it also increases the blast radius of a configuration mistake. Exclude local networks and required corporate interfaces according to your organization’s design, and check whether your operating system prompts for elevated permissions.
A useful decision table is:
| Situation | Recommended starting point | What to verify |
|---|---|---|
| Browser login works, terminal does not | Explicit environment variables | Child process inherited the variables |
| Terminal variables work, IDE does not | Restart the IDE or use TUN | IDE was launched after proxy activation |
| Internal Git fails after proxy setup | Add precise NO_PROXY or DIRECT rules | Internal DNS and certificates remain reachable |
| Streaming stops during long prompts | Use a stable proxy group and test another node | Idle timeout, packet loss, and node health |
5. Design rules with a small blast radius
Start with explicit service rules and place them above broad regional or catch-all rules. A conceptual Mihomo fragment might look like this:
rules:
- DOMAIN,git.internal.example.com,DIRECT
- DOMAIN-SUFFIX,internal.example.com,DIRECT
- DOMAIN,claude.example.com,Claude-AI
- DOMAIN-SUFFIX,anthropic.com,Claude-AI
- DOMAIN-SUFFIX,anthropic.cloud,Claude-AI
- MATCH,PROXY
The domains above are illustrative rather than a promise of a permanent production hostname list. Replace them with domains observed in your current logs and documentation. Do not route every domain containing a familiar brand name without checking its ownership. Authentication providers, corporate identity systems, and cloud consoles may need a different path from model traffic.
Create a dedicated proxy group such as Claude-AI instead of placing Claude traffic directly into a general-purpose group. A dedicated group makes node comparison easier and lets you choose a fallback strategy. For example, you might prefer a low-latency node for interactive prompts, while retaining a second region as a manual fallback when the primary route becomes congested.
Use domain rules before GEOIP, RULE-SET, or MATCH rules when there is a specific requirement. Rule order is decisive: the first matching rule usually wins. If a broad “domestic direct” rule appears above your Claude service entries, the later proxy rule will never be reached. After every change, reload the profile and inspect the log for the exact rule name selected by a test request.
DNS deserves separate attention. Fake-IP mode can be convenient for rule matching, but some login flows, local discovery systems, and applications with strict address expectations behave better with compatible DNS handling. Do not switch DNS modes repeatedly while changing several other settings, because you will lose the ability to identify which change fixed or caused the problem. Clear the application’s cached sessions only after confirming that the route and DNS result are stable.
6. Configure the terminal without breaking Git
Test the proxy from the same shell that will launch Claude Code. Use a harmless request to confirm that the proxy port is reachable and that DNS resolution behaves as expected. Then inspect the environment:
env | grep -i proxy
curl -I https://example.com
git config --global --get http.proxy
git config --global --get https.proxy
A common mistake is configuring both shell variables and global Git proxy settings without recording why. Git may then continue using a stale proxy even after Clash Verge changes groups. If your organization has separate routes for public and internal repositories, prefer host-specific Git configuration or environment variables rather than a permanent global proxy that captures every remote.
For Claude Code, launch it from the tested shell rather than from a different terminal window. If you use an IDE, completely restart the IDE after changing proxy variables. Integrated terminals often inherit the environment from the parent process, not from the current desktop settings. Remote SSH sessions and containers are separate network namespaces in practical terms; a proxy configured on the host does not automatically configure the remote environment.
Keep credentials out of shell history. Proxy URLs containing usernames or passwords can be saved by terminal history, process listings, CI logs, or IDE diagnostics. Prefer the authentication mechanisms supported by your node provider, and never paste a complete profile containing private keys into a public issue or chat.
7. Troubleshoot timeouts, sign-in loops, and interrupted streams
When Claude Code fails, classify the symptom before changing the configuration. A connection refusal usually points to a local port, firewall, or unavailable proxy listener. A DNS error points toward resolver behavior or a malformed hostname. A TLS error may involve interception, an incorrect system clock, certificate stores, or a proxy that does not handle the connection correctly. A long pause followed by a timeout more often indicates packet loss, an overloaded node, or a route that cannot maintain the session.
Authentication and sign-in
If browser login loops, compare the browser’s selected Clash rule with the terminal’s selected rule. Keep the complete authentication sequence on a consistent path where possible; changing exit regions between redirects can trigger security challenges or invalidate a session. Check system time, disable conflicting VPN software, and avoid running multiple proxy clients that compete for the same system settings.
Streaming and long prompts
If the first response tokens arrive and then stop, test a different node in the same dedicated group. Look for repeated connection resets, rising latency, or a proxy group that automatically switches nodes during an active session. Long prompts also increase upload duration, while repository context can produce larger responses and more tool calls. A node that feels fast for a small web page may still be unsuitable for a long-lived stream.
Wrong route and direct fallbacks
If the request is consistently marked DIRECT, inspect rule order and confirm that the hostname is the one actually requested. A browser’s visible URL is not always the API hostname. If the request is proxied but should be internal, add a narrow direct rule and preserve internal DNS behavior. Avoid solving one failed domain by routing all traffic through the proxy; that can hide a rule error while degrading Git, package managers, and local development services.
A safe reset procedure
- Save a copy of the working profile and note the current Clash Verge mode.
- Disable unrelated VPN clients and confirm that the mixed port is listening.
- Test one domain from the terminal, then reproduce the Claude Code failure.
- Read the Clash log and record the rule, group, node, and error type.
- Change one variable only, reload the profile, and repeat the same test.
- After recovery, document the final rules and the reason each exception exists.
8. Frequently asked questions
Does Claude Code always require TUN mode?
No. If the terminal process honors system proxy settings or explicit HTTP_PROXY and HTTPS_PROXY variables, a mixed port may be enough. TUN mode is useful when the application or its parent environment ignores those settings, but it should be introduced deliberately because it captures a wider range of traffic.
Should Git use the same proxy as Claude Code?
Not necessarily. Public Git hosts may work well through the proxy, while internal repositories usually need a direct or corporate route. Test each host independently and use specific rules or host-specific Git settings instead of assuming that one path is correct for every repository.
Why does the browser work while Claude Code fails?
The browser and terminal may use different proxy settings, DNS resolvers, certificate stores, or authentication sessions. The browser may also be using a system proxy while Claude Code is reading no environment variables. Launch both from known environments and compare their Clash log entries.
Is the fastest node always the best choice?
No. Interactive Claude Code sessions depend on stability, sustained throughput, and the ability to keep a streaming connection open. A node with slightly higher initial latency but fewer resets can provide a better development experience than a nominally faster node that changes routes or drops long requests.
Compared with simple VPN clients that offer only an all-or-nothing switch, Clash Verge gives Claude Code users more useful control: a dedicated group for model traffic, direct exceptions for internal Git, explicit terminal variables, and logs that reveal which rule actually handled a connection. Those controls do require more initial testing, but they prevent the common trade-off where fixing an AI coding session quietly breaks package downloads or corporate services. If you want a client that supports these routing choices across desktop platforms, you can start with the available Clash builds and then apply the smallest configuration that matches your workflow.
Ready to get started?
Choose a Clash client, prepare a stable proxy group, and keep Claude Code traffic separate from your local development services.