Claude Code With Clash Verge: Terminal Access Setup Guide

Claude Code is designed to run inside a terminal, which makes its network behavior different from that of a browser. A browser may follow the operating system proxy automatically, while a shell process usually depends on environment variables, its own configuration, or a virtual network interface. As a result, turning on Clash Verge's system proxy does not necessarily make Claude Code's sign-in flow, API requests, package downloads, and Git operations use the same route.

A reliable setup should separate three questions: whether Clash Verge is running with a usable proxy group, whether the terminal can reach the required services through the local proxy port, and whether Claude Code is receiving the correct proxy or API environment variables. This guide uses that order to build a practical configuration for everyday coding sessions without changing the project files or hard-coding credentials into a repository.

Understand the Traffic Path Before Changing Settings

When Claude Code cannot sign in or reports that a request failed, the error may come from several independent layers. The terminal may not know that a local proxy exists, Clash Verge may be listening on a different port than expected, the selected node may fail to reach the destination, or the authentication flow may be blocked in the browser rather than in the terminal.

The basic path usually looks like this:

Claude Code process
        ↓
shell proxy variables or TUN interception
        ↓
Clash Verge local HTTP, SOCKS5, or mixed port
        ↓
selected Clash proxy group
        ↓
remote service

Clash Verge commonly exposes an HTTP port, a SOCKS5 port, or a mixed port that accepts more than one proxy protocol. The exact port is configurable, so do not assume that a port number copied from another tutorial is correct on your machine. Open Clash Verge's settings or dashboard and identify the address and port currently used by the local listener. In most desktop installations the address is 127.0.0.1 or localhost, but the port may differ between profiles.

This distinction prevents a common mistake: repeatedly switching proxy nodes when the actual problem is that Claude Code never reached the Clash listener. First verify the local path, then verify the remote path, and only after that investigate account or application-level errors.

Prepare Clash Verge for Terminal Requests

Check the Core, Profile, and Proxy Group

Start Clash Verge and confirm that a profile is loaded and the mihomo core is running normally. The profile should contain at least one usable proxy node and a proxy group that can be selected for the destinations used by your coding tools. If the profile was recently updated, check the logs for YAML parsing errors, failed subscription updates, or nodes that have disappeared from the provider response.

For a first test, choose a known working node or a simple proxy group rather than a complicated automatic rule group. This reduces the number of variables. Once the terminal connection works, you can return to the normal rule-based group and confirm that its rules select the expected outbound.

Identify the Correct Local Listener

Find the HTTP or mixed port in Clash Verge. A mixed port is often convenient because many command-line tools understand HTTP proxy syntax while some tools need SOCKS5 support. If you use a SOCKS5-only port, make sure the application or environment variable explicitly uses the socks5:// scheme. Do not confuse a Clash controller or external-control port with a traffic proxy port: the controller API manages the core, while the HTTP, SOCKS, or mixed listener carries application traffic.

For example, if Clash Verge shows a mixed listener on port 7890, the local proxy URL is commonly written as:

http://127.0.0.1:7890

If the listener is SOCKS5 instead, use a separate URL:

socks5://127.0.0.1:7891

The values above are examples only. Replace them with the actual address and port shown by your client. A wrong port normally produces an immediate connection-refused error, while a reachable listener with a bad node may produce a timeout or a remote handshake failure.

Choose System Proxy, Environment Variables, or TUN

For a terminal-only setup, environment variables are usually the easiest method to understand and reverse. They affect the current shell or command, and they do not silently change the routing behavior of unrelated applications. System proxy settings are useful for browsers and GUI programs that read the operating system configuration, but they are not a guarantee for command-line tools.

TUN mode can be useful when a program ignores proxy variables or when several applications need consistent routing. However, it adds another layer involving a virtual adapter, DNS handling, routing rules, and operating-system permissions. It should not be enabled merely because the system proxy toggle did not affect the terminal. First test explicit proxy variables; use TUN when there is a clear need for network-layer interception.

Configure the Terminal Environment

Most command-line networking tools recognize some form of HTTP_PROXY, HTTPS_PROXY, and ALL_PROXY. Support is application-specific, and variable names can be case-sensitive on some systems. Setting both uppercase and lowercase forms is often practical for mixed toolchains, especially when a package manager, Git, and a language runtime are involved.

For an HTTP or mixed Clash listener, a temporary configuration in a POSIX-compatible shell can look like this:

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 http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export all_proxy="$ALL_PROXY"

For a SOCKS5 listener, use the appropriate scheme supported by the program:

export ALL_PROXY=socks5://127.0.0.1:7891
export all_proxy="$ALL_PROXY"

On Windows PowerShell, the equivalent temporary variables are:

$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:ALL_PROXY = "http://127.0.0.1:7890"
$env:http_proxy = $env:HTTP_PROXY
$env:https_proxy = $env:HTTPS_PROXY
$env:all_proxy = $env:ALL_PROXY

These commands only affect the current terminal process and programs launched from it. That is useful during diagnosis. If the setup works, you can place the variables in a shell profile such as ~/.zshrc, ~/.bashrc, or the appropriate PowerShell profile, but consider the side effects first. A global proxy setting can route package downloads, Git remotes, cloud command-line tools, and internal company services through Clash as well.

Exclude Local and Private Destinations When Necessary

Some development environments need direct access to local services, corporate hosts, or private IP ranges. The NO_PROXY variable can keep selected destinations out of the proxy path:

export NO_PROXY=localhost,127.0.0.1,::1
export no_proxy="$NO_PROXY"

Add internal domains only when you understand the network boundary. An overly broad value can bypass the proxy for a public service that you intended to route through Clash. Conversely, omitting localhost may cause a callback, local API, or development server to be sent through the proxy unnecessarily.

Test Connectivity Before Launching Claude Code

Testing the local proxy independently is faster than using Claude Code as the first diagnostic tool. Confirm that the listener accepts connections and that a simple HTTPS request can complete. The exact test URL should be a service that is permitted and relevant to your environment; the important point is to compare a direct request with a request using the local proxy.

With curl, an explicit HTTP proxy test can be written as:

curl -I --proxy http://127.0.0.1:7890 https://example.com

To test the variables in the current shell, run:

curl -I https://example.com

If the explicit proxy command works but the second command fails, the shell variables were not exported correctly or curl is not reading the variable form you set. If both fail with connection refused, verify the port and whether Clash Verge is running. If the local listener responds but the request times out, inspect the selected node, proxy group, DNS mode, and Clash runtime logs.

Use a verbose request when the result is ambiguous:

curl -v --proxy http://127.0.0.1:7890 https://example.com

Look for the connection to 127.0.0.1, the proxy CONNECT request for HTTPS, and the point at which the failure occurs. A successful connection to the local port proves only that the application reached Clash; it does not prove that the remote service accepted the connection.

After the basic request succeeds, launch Claude Code from the same terminal so it inherits the variables. Avoid opening a new terminal window that has a different shell profile or environment. If Claude Code still reports a network error, compare its launch environment with the shell used for the successful test:

env | grep -i proxy

On PowerShell, use:

Get-ChildItem Env: | Where-Object { $_.Name -match "proxy" }

Do not paste the output into public issue trackers if it includes proxy credentials, private hostnames, or account-related values.

Handle Sign-In and API Credentials Separately

Claude Code authentication may involve a browser-based sign-in flow or an API key, depending on the product mode and installation. These are not identical network paths. The browser may use the operating-system proxy or its own proxy settings, while the terminal process uses environment variables. It is therefore possible for the browser page to load successfully while the terminal cannot complete its callback, or for the terminal to reach an API endpoint while the browser session is not authenticated.

For browser-based sign-in, keep Clash Verge running throughout the process and make sure the browser and terminal use a compatible route. If the sign-in page opens but the callback does not return to Claude Code, check whether a local callback address is being excluded or intercepted. A local callback such as localhost normally should remain direct; proxying it can prevent the browser from reaching the process waiting on the local machine.

For API-key authentication, set the credential in the method recommended by the current Claude Code documentation or installer. A common shell pattern is:

export ANTHROPIC_API_KEY="replace-with-your-key"

Do not place a real key in a project repository, a committed .env file, shell history, screenshots, or a shared terminal recording. If a key has been exposed, revoke it through the relevant account console and create a replacement. Proxy variables and API credentials should be treated differently: the proxy URL describes routing, while the API key authorizes service usage.

Some tools also support a custom API endpoint variable or organization-specific settings. Only set such variables when the service or your administrator explicitly requires them. An incorrect base URL can look like a proxy failure because the request reaches a server that does not expose the expected API path. When debugging, start with the default endpoint and the smallest supported set of environment variables.

Make the Setup Reliable for Daily Coding

Once Claude Code can start and complete a basic request, test the operations you actually use. Ask it to inspect a local file, run a harmless project command, and perform a small request that requires network access only if the project permits it. Git operations and package managers may have separate proxy settings, so a working Claude Code session does not automatically prove that every development tool is configured.

Keep the configuration minimal. A good daily setup normally has one selected Clash profile, one verified local listener, and one clearly documented shell method. Avoid changing the node, DNS mode, TUN state, and environment variables at the same time. When something breaks after a profile update, compare the current configuration with the last known working state and read the Clash logs before making further changes.

• Start Clash Verge first: confirm the core is running, the profile is loaded, and the selected group has a healthy node.
• Verify the local port: use the port shown by Clash Verge rather than relying on a copied example.
• Export variables in the launch shell: start Claude Code from that same shell so it inherits the proxy configuration.
• Keep local callbacks direct: include localhost and loopback addresses in NO_PROXY unless your environment requires another arrangement.
• Protect credentials: keep API keys and subscription links out of source control and shared logs.
• Reset temporary settings: remove shell variables when testing a direct connection, so a previous proxy does not confuse the comparison.

If the terminal works only with TUN mode enabled, record that fact and document the required permissions and DNS behavior. If it works with explicit environment variables, prefer that narrower configuration for ordinary coding sessions. The right choice depends on whether you need to proxy one command, one terminal, or nearly every application on the device.

For a final diagnosis, classify the failure by where it occurs: no local listener means a Clash Verge configuration problem; a reachable listener with a failed remote connection points to the node, rule, DNS, or upstream network; a successful network test with a failed sign-in points to authentication or browser callback handling; and a successful sign-in with API errors points to credentials, endpoint configuration, account permissions, or application-specific behavior. This classification is more dependable than repeatedly reinstalling Claude Code or switching random nodes.