Claude Code is designed to work from a terminal, but its first-run authentication, model requests, update checks, and remote tool calls all depend on network access. On a restricted, unstable, or selectively routed connection, the command may appear to install correctly and still fail when it tries to sign in or send a prompt. Clash Verge can help by providing a local HTTP or SOCKS proxy, applying rules to the relevant domains, and making the terminal use the same routing policy as other desktop applications.

The important distinction is that enabling the system proxy in Clash Verge does not always configure every terminal process. Browsers and many graphical applications read the operating system proxy automatically, while command-line tools often rely on environment variables such as HTTPS_PROXY or their own configuration files. A reliable setup therefore has three parts: a working Clash Verge profile, a listener whose address and port are known, and a terminal environment that points Claude Code and its supporting tools to that listener.

Understand how Claude Code and Clash Verge connect

Claude Code is a terminal application, but its network activity is not limited to one request. Depending on the installed version and enabled features, the workflow can include account authentication, API requests, package or component downloads, update checks, documentation access, and connections initiated by tools used inside a project. Some actions may open a browser for authentication, while the main model session remains in the terminal.

Clash Verge provides the local control layer. It starts a Clash-compatible core, imports a YAML configuration or subscription, exposes local listeners, applies DNS and routing rules, and optionally enables the operating system proxy or TUN mode. The graphical client is not itself the remote server. It only controls the local core and displays its logs. When a terminal request succeeds, the usual path is:

Claude Code
    ↓
HTTPS_PROXY / ALL_PROXY or application proxy settings
    ↓
Clash Verge local listener
    ↓
Clash rule matching and policy group
    ↓
Selected outbound node
    ↓
Remote service

This path explains why several apparently similar settings should not be confused. The system proxy changes a desktop operating system setting and is useful for applications that honor it. A local HTTP listener accepts HTTP proxy requests and is commonly suitable for HTTPS connections through the CONNECT method. A local SOCKS listener supports applications that explicitly understand SOCKS5. TUN mode works at a lower network layer and can capture traffic from programs that ignore proxy environment variables, but it requires additional permissions and may affect more applications than intended.

Component What it controls Typical troubleshooting question
Clash Verge profile Nodes, rules, DNS, listeners, and policy groups Does the profile load and does the selected group have a usable node?
HTTP listener HTTP proxy requests, including HTTPS tunneling Is the terminal pointing to the correct local address and port?
SOCKS listener Applications that support SOCKS5 proxying Does the command use a SOCKS-compatible URL rather than an HTTP URL?
System proxy Applications that read operating system proxy settings Does this specific terminal or tool inherit the system setting?
TUN mode Broader IP traffic interception through a virtual interface Are permissions, DNS behavior, and routing scope configured correctly?

For a first setup, an explicit HTTP proxy variable is usually easier to inspect than TUN mode. It keeps the experiment limited to the terminal and makes it clear whether Claude Code is using Clash Verge. TUN mode can be considered later when a tool ignores proxy variables or when several supporting processes must be covered consistently.

Prepare the Clash Verge profile and local listener

Open Clash Verge and select a profile that contains valid proxy nodes, policy groups, and rules. If the profile comes from a subscription, update it before testing so that expired nodes and outdated rule providers do not complicate the diagnosis. Check the active core shown by the client as well. A profile may contain fields supported by mihomo but not by an older or different core, so a configuration that imports successfully is not necessarily a configuration that starts correctly.

Check profile status before changing terminal variables

  1. Confirm that the profile is selected and has finished parsing without a YAML or compatibility error.
  2. Open the proxy or policy page and choose a group with a known working node. Do not leave the group on an empty selector or an unavailable automatic member while testing.
  3. Verify that the local HTTP or mixed listener is enabled. Record the bind address and port exactly as displayed in Clash Verge.
  4. Use the client’s connection view or a built-in test to confirm that a request can leave through the selected policy.
  5. Keep the Clash Verge log visible while running the terminal test. A request appearing in the log is useful evidence that the terminal reached the local core.

Many installations use a loopback address such as 127.0.0.1 with a port such as 7890, but these values are not universal. Clash Verge profiles, user changes, and other local services can use different ports. Never copy a port from an old guide without checking the current interface. If the listener binds only to 127.0.0.1, that is normally appropriate for a local terminal; exposing a proxy listener to the local network is unnecessary for this use case and increases risk.

If the profile uses a policy group for work or developer services, inspect the relevant rules rather than assuming that all domains follow the same route. A rule may send one domain to DIRECT, another to a selected group, and unmatched traffic to MATCH. A successful connection to one website therefore does not prove that the authentication or model endpoint used by Claude Code follows the desired policy.

Configure the terminal to use Clash Verge

The most portable approach is to set proxy environment variables in the shell session that launches Claude Code. Use the HTTP listener address recorded from Clash Verge. The HTTPS_PROXY variable tells many command-line clients how to establish HTTPS connections through an HTTP proxy; HTTP_PROXY covers plain HTTP requests, and ALL_PROXY is useful for tools that use a general proxy setting. Lowercase variants improve compatibility with software that checks only lowercase names.

Windows PowerShell

$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"

claude

Replace 7890 with the actual HTTP or mixed-port value shown by Clash Verge. These assignments affect the current PowerShell window and processes started from it. That makes them suitable for a controlled test. To remove them after testing, close the window or run:

Remove-Item Env:HTTP_PROXY
Remove-Item Env:HTTPS_PROXY
Remove-Item Env:ALL_PROXY

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="http://127.0.0.1:7890"

claude

For a temporary test, run these commands only in the current shell. If the result is stable and the proxy is always available, the variables can be added to the shell’s startup file, such as ~/.zshrc or ~/.bashrc. A startup-file entry should be deliberate: it can affect Git, package managers, container tools, language runtimes, and unrelated scripts. A project-specific launcher is often safer than globally changing every terminal command.

Verify the listener before testing authentication

Use a simple HTTPS request from the same shell. The exact destination can be a permitted, stable endpoint that you normally use for connectivity testing. For example, with a command-line client that supports an explicit proxy:

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

On Windows, curl.exe can be used explicitly if the shell resolves another command with the same name. The important result is not merely an HTTP status code. Watch the Clash Verge connection log and confirm that the request appears, the expected policy is used, and the selected node completes the TLS connection. If the request fails immediately with a connection-refused message, the local port is wrong or the listener is stopped. If it reaches Clash but fails remotely, inspect the selected node, DNS behavior, rules, and remote availability.

A SOCKS listener requires a different URL scheme. Do not point an HTTP proxy variable at a SOCKS-only port. When a tool supports SOCKS5, its syntax may look like socks5h://127.0.0.1:7891; the actual port must come from Clash Verge. The h in socks5h asks the proxy to resolve the hostname, which can avoid a local DNS path that is inconsistent with the selected route. Support varies by program, so an HTTP or mixed listener is generally simpler for the first Claude Code test.

Run Claude Code and complete the login flow

Install Claude Code through its documented distribution method, then launch it from the same terminal where the proxy variables were set. Installation and runtime are separate tests. A package manager may use its own proxy settings, while Claude Code may read environment variables when it starts. If installation succeeds but the first model request fails, inspect the runtime process rather than assuming that the installer’s network path is still active.

Start the command normally:

claude

Follow the authentication instructions presented by the installed version. Some versions or account configurations may open a browser, display a device flow, or request credentials through a terminal prompt. If a browser opens, remember that the browser may follow the system proxy while the terminal follows environment variables. Both paths must be able to reach the required authentication service. If the browser succeeds but Claude Code reports a callback or token error, check whether local callback traffic should bypass the proxy.

Local addresses should generally remain direct. A common exclusion pattern is:

NO_PROXY="localhost,127.0.0.1,::1"

On PowerShell, the equivalent is:

$env:NO_PROXY = "localhost,127.0.0.1,::1"

Do not add broad domain exclusions simply because one request failed. An exclusion can force sensitive or restricted traffic outside Clash Verge and may produce confusing results. Add only addresses that are clearly local or required by the authentication flow, then retest. Likewise, avoid placing access tokens, API keys, or subscription URLs in shell history, screenshots, project files, or shared configuration. Proxy variables should contain the local listener address, not account credentials.

After login, make a small, low-risk request inside a test project. Confirm three things at the same time: Claude Code reports a usable session, the Clash Verge log shows the expected outbound connections, and the response completes without repeated retries. A successful login alone proves only that authentication worked; it does not guarantee that later model requests, tool downloads, or external service calls use the same route.

Observation Likely area to inspect First action
No request appears in Clash Verge Shell variables or application proxy support Print the variables, start a new shell, and run an explicit curl -x test
Connection refused on localhost Listener state, address, or port Read the current listener value from Clash Verge and confirm the core is running
Clash receives the request but it times out Node, policy group, DNS, or remote route Switch to a known working node and inspect the connection log
Browser login works but terminal login fails Different proxy inheritance or callback behavior Compare browser system-proxy settings with terminal environment variables
Login works but model requests fail Service routing, account access, or endpoint policy Check the exact failed hostname and its Clash rule instead of changing every rule

Choose between explicit proxy variables and TUN mode

Explicit proxy variables are usually the best starting point for a developer terminal because they are visible, reversible, and limited to processes launched from that shell. They also make it easier to compare direct and proxied behavior. Use this mode when Claude Code and its dependencies honor standard proxy variables and when you want project commands to have predictable network scope.

TUN mode is useful when a program ignores proxy variables, uses a networking library without proxy support, or starts child processes that do not inherit the expected environment. In Clash Verge, enabling TUN normally requires elevated permissions and may change DNS handling, route installation, and the behavior of applications across the entire system. It can solve coverage problems, but it also makes diagnosis harder because a request may be intercepted even when the terminal contains no proxy variables.

Approach Advantages Limitations Recommended use
HTTP proxy variables Easy to inspect, limited scope, simple to disable Only affects tools that honor the variables Initial Claude Code and terminal testing
SOCKS proxy variables Useful for SOCKS-aware tools and remote DNS options Not supported consistently by every command-line client Programs that document SOCKS5 support
System proxy Convenient for browsers and desktop applications Many terminal programs ignore it Browser-based authentication and GUI tools
TUN mode Captures broader traffic, including applications without proxy support Requires permissions and can affect unrelated applications Only after explicit proxy testing is insufficient

Do not enable both TUN mode and several unrelated proxy layers while diagnosing the first failure. Multiple interception methods can create loops, inconsistent DNS results, or misleading logs. Start with one path, record the result, and change one variable at a time. Once the workflow is stable, decide whether a persistent shell configuration or TUN mode provides a better balance between convenience and control.

Maintain a reliable developer workflow

Keep a small checklist for future failures. Confirm that Clash Verge is running, the profile is current, the selected policy group has a healthy member, and the local listener has not changed. Then verify the environment variables in the current terminal and inspect the Clash connection log for the exact hostname that failed. Network conditions can change independently of Claude Code, so compare a direct test, an explicit proxy test, and the application log instead of repeatedly reinstalling the command.

When a project uses Git, package managers, containers, or remote development tools alongside Claude Code, configure each tool according to its own proxy documentation. Inherited environment variables may be helpful, but they can also send package downloads or internal services through an unintended route. Use NO_PROXY for clearly local services, avoid committing proxy settings to repositories, and remove temporary variables when working on a network that does not require them.

Choose a client and continue setup

Download a suitable Clash client, then use the quick-start guide to import a profile, verify the listener, and configure terminal routing step by step.

Download Clash View Tutorial