Claude Code Proxy Setup: Configure Clash Verge for Terminal Access

Separate Clash Verge from terminal proxy settings

If Claude Code opens but cannot sign in, fetches fail, or requests time out, first check whether the problem is in Clash Verge or in the terminal environment. Clash Verge controls the mihomo core and can route traffic from applications in several ways. A terminal command-line program, however, does not necessarily use the same proxy settings as a browser. The desktop client can show that its system proxy is enabled while a shell-launched process still connects directly.

For Claude Code, the most reliable starting point is to provide an HTTP proxy through the environment variables HTTP_PROXY and HTTPS_PROXY. The proxy URL will commonly look like http://127.0.0.1:7890, but 7890 is only an example. Use the actual HTTP or mixed-port shown in Clash Verge. Do not assume that the browser’s proxy setting, a SOCKS port, or a port used by another Clash client is the right value.

It is normal for an https:// destination to use a proxy URL beginning with http://. In this arrangement, the terminal connects to a local HTTP proxy, asks it to establish a tunnel to the HTTPS server, and then negotiates TLS with that server. The scheme in the proxy URL describes the connection to the local proxy; it does not turn the destination into an unencrypted HTTP request.

• Clash Verge: provides a running core, a listening proxy port, a selected route, and the rules or mode that decide where traffic goes.
• Your shell: passes environment variables to new processes launched from that shell.
• Claude Code: reads the proxy environment provided to its process when making network requests.

Confirm the listener and route in Clash Verge

Before changing shell profiles or reinstalling Claude Code, confirm that the Clash core is running and that the local listener accepts connections. Open Clash Verge and check its current proxy-port settings. Depending on the version and configuration, the interface may show separate HTTP and SOCKS ports or a mixed port that accepts both HTTP and SOCKS connections. Choose the HTTP-capable listener for the examples in this guide. If you recently edited a port, restart or reload the core if the interface requires it.

Next, check the active mode and the selected policy. In Rule mode, the core evaluates rules from top to bottom and sends a request to the policy matched by its destination. A usable proxy node in a group does not guarantee that Claude Code will use that node: a domain rule might send the API connection to DIRECT, or the selected group might point to a failed node. In Global mode, traffic handled by the core uses the global policy, which can be useful for a short diagnostic comparison. Return to your normal mode after testing.

1. Confirm that the core status is running and note the active HTTP or mixed-port.
2. In the proxy or policy-group view, select a known working node or group. Check that the group is not set to a dead or unavailable option.
3. Open the connection or log view, then make one test request from the terminal. Look for the destination host and the policy shown for that connection.
4. If the request appears in the log but uses an unexpected route, inspect the matching rule or test briefly in Global mode. Do not add broad rules until you know which destination is being matched.

Clash Verge labels and menu placement can differ between releases, and Clash Verge Rev is a separate maintained client variant. The important facts are the running core, the actual listening port, the current mode, and the route selected for the request—not a specific menu name. A successful browser test alone is not enough if the browser uses a different proxy configuration from the terminal.

System proxy and TUN mode are optional ways to capture other application traffic; they are not substitutes for verifying Claude Code’s own proxy settings. System proxy settings are honored by many desktop applications but not every command-line program. TUN mode can capture more traffic at the operating-system level, but it may require elevated permissions and can introduce routing or DNS conflicts. Start with the explicit environment-variable method below because it is easier to inspect and undo.

Set proxy variables for the current terminal

Use a temporary setting first. It applies only to commands started in the current shell and is removed when that shell closes. Replace 7890 with the HTTP or mixed-port you verified in Clash Verge. Keep the variable value as a local proxy URL; do not paste a node address or subscription URL into it.

macOS and Linux shells

In Terminal, run the following commands before starting Claude Code:

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

Setting both uppercase and lowercase forms helps when a tool or dependency checks one convention rather than the other. If you want to test the proxy without launching Claude Code, use curl:

curl -I --proxy "$HTTPS_PROXY" https://api.anthropic.com

A response such as 401, 403, 404, or 405 can still show that DNS, the proxy connection, and TLS negotiation completed; the server response may simply be expected for an unauthenticated request to that endpoint. By contrast, Could not resolve proxy usually points to a wrong proxy host, while Connection refused often means that the local port is not listening. A timeout needs further separation: check the Clash connection log to see whether the request reached the core and which route it selected.

To remove the temporary variables in the same shell, run:

unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy

Windows PowerShell

In the PowerShell window where you will run Claude Code, set the variables like this:

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

These values apply to that PowerShell process and the programs it starts. If you start Claude Code from a different window, Windows Terminal profile, integrated editor terminal, or IDE task runner, that process may not inherit the same environment. To clear the temporary values, use:

Remove-Item Env:HTTP_PROXY, Env:HTTPS_PROXY, Env:http_proxy, Env:https_proxy

Do not set a persistent user or system variable until the temporary test works. Persistent settings can affect other command-line tools and may remain active after Clash Verge is closed. If you do make them persistent, record the original values and remove or restore them when you no longer want terminal traffic to use the local proxy.

Choose a routing mode and verify the connection

Once the terminal can reach the local listener, determine whether the request is actually routed through a working policy. Run a single test command, then check Clash Verge’s connection view for a destination such as api.anthropic.com. Confirm that the displayed policy is the one you intended. If the command produces no matching connection entry, first check that the variables are present in that terminal and that Claude Code was started from the same shell.

For a simple diagnosis, keep your normal configuration unchanged and make one controlled comparison. First test the explicit proxy with curl. Then launch Claude Code from the same terminal. If both requests appear in Clash logs and use the expected policy, the local proxy path is working. If curl succeeds but Claude Code does not appear in the log, focus on process inheritance, the Claude Code environment, or a different terminal session. If both reach the core but fail on the same route, investigate the selected node, DNS behavior, and core log entry.

Rule mode is generally the practical everyday choice when your configuration has suitable rules and policy groups. Global mode is a diagnostic tool, not a requirement for Claude Code. TUN mode can be useful if an application ignores proxy variables, but enabling it changes how broader system traffic is captured. Avoid changing Rule mode, DNS, TUN, and proxy ports at the same time; otherwise, a successful result will not tell you which change mattered.

Troubleshoot timeouts and persistent failures

“Connection timed out” does not identify a single cause. The delay can happen while resolving the destination, connecting to the local proxy, establishing a route through a node, completing a TLS handshake, or waiting for the remote service. Use timestamps and the Clash connection log to locate the stage instead of repeatedly switching nodes at random.

• No local connection in the log: Check that HTTP_PROXY and HTTPS_PROXY are set in the shell that starts Claude Code. Confirm the port with an explicit curl --proxy test.
• The local connection is refused: Verify that Clash Verge’s core is running and that the URL uses the correct port. A SOCKS-only listener may not accept an HTTP proxy request.
• The core logs a rule match to Direct: Check the rule and mode. Do not assume that enabling the system proxy overrides a rule in the core.
• The selected proxy policy fails: Test a known working node and check whether other destinations through that same node work. A policy group name in the log does not by itself prove that its current member is healthy.
• TLS or certificate errors appear: Check the system clock, the selected route, and whether security software is intercepting TLS. Do not disable certificate validation as a workaround.
• The proxy test succeeds but Claude Code reports an account error: Separate connectivity from sign-in and account access. A reachable endpoint does not guarantee that the account, credentials, or service permissions are valid.

Also check for stale or conflicting variables. A shell may contain an old HTTPS_PROXY value while HTTP_PROXY points to the current port. A terminal opened before a persistent environment change may retain the old values; close it and open a fresh one to retest. In PowerShell, inspect only the relevant variables with Get-ChildItem Env:HTTP_PROXY, Env:HTTPS_PROXY, Env:http_proxy, Env:https_proxy. On macOS or Linux, use env | grep -i proxy, but review the output before sharing it because proxy URLs may contain credentials.

If Claude Code is started by an IDE, a task runner, or a background process, test from a regular terminal first. GUI applications may not inherit environment changes made after they were launched, and integrated terminals can use a shell profile different from the one you edited. Once the regular terminal test succeeds, configure the IDE’s environment or launch it from a shell that already has the variables.

Finally, avoid treating TUN mode as a cure for every timeout. If you use it, check whether another VPN, security product, or network filter is also managing routes. Compare one change at a time, note the original settings, and turn off the temporary diagnostic mode when finished. If the failure persists, save the timestamp, the sanitized error, the destination, the selected policy, and a short relevant log excerpt; those details are more useful than a screenshot of the entire configuration.

FAQ

Does the Clash Verge system proxy automatically cover Claude Code?

Not reliably. System proxy settings are used by many graphical applications, but command-line tools may rely on environment variables or their own proxy configuration. Set HTTP_PROXY and HTTPS_PROXY in the shell that starts Claude Code, then verify the request in Clash Verge’s connection view.

Should the proxy URL start with http or https?

For a typical local Clash Verge HTTP or mixed-port listener, use a URL such as http://127.0.0.1:7890, with your actual port. The destination can still be HTTPS: the HTTP proxy establishes a tunnel for the encrypted connection. Use an https:// proxy URL only if the proxy listener itself is configured to accept TLS.

Can I use a SOCKS port instead?

Prefer the HTTP-capable or mixed listener with HTTP_PROXY and HTTPS_PROXY for this setup. SOCKS support depends on the application and its networking libraries; a port accepting SOCKS traffic is not automatically interchangeable with an HTTP proxy port. Check the client’s current port settings rather than guessing from a default.

Why does curl work while Claude Code still times out?

The two programs may not share the same environment, shell, or process launch path. Start Claude Code from the exact terminal where the successful curl test ran, and check that its request appears in Clash Verge. If it does appear, compare the destination and selected route; if it does not, investigate environment inheritance before changing core rules.