Claude Code With Clash Verge: A Practical Terminal Setup Guide

Understand the terminal proxy path before changing settings

Claude Code brings AI-assisted coding into a terminal, but the terminal does not automatically use the same proxy settings as a browser. A browser may follow the operating system proxy, a browser extension, or its own network configuration, while a command-line process usually reads environment variables or uses the network stack provided by its runtime. This difference explains why a website can open normally while Claude Code reports a timeout, connection reset, failed sign-in, or an inability to reach the API.

Clash Verge sits between the application and the network. Its mihomo core receives local proxy connections, selects a policy group, applies rules, resolves domains according to its DNS configuration, and then connects to the remote service. Claude Code must be directed to the local listener exposed by Clash Verge. In a typical configuration, mixed-port: 7890 accepts HTTP and SOCKS5 proxy traffic, while 127.0.0.1 limits access to the local computer.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

The exact port may be different on your machine. Open Clash Verge’s settings or the active configuration and look for the mixed port, HTTP port, or SOCKS port. Do not assume that every Clash client uses 7890. A wrong port produces errors that look like an unavailable remote service even though the actual problem is simply that no local process is listening there.

Prepare Clash Verge for a predictable Claude Code route

Before launching Claude Code, start Clash Verge and confirm that the intended profile is active. The profile should contain usable proxy nodes, a working policy group, and rules that do not accidentally send the required service domains directly. If the subscription has several groups such as “Node Select,” “Auto,” or “Streaming,” select a group that has passed a recent health check. A node can show a low latency value and still fail to establish a stable HTTPS connection, so treat latency as a useful signal rather than proof of application compatibility.

For a first test, use rule mode rather than global mode. Rule mode keeps ordinary local traffic direct while sending domains matched by the profile through the selected proxy. This makes it easier to identify whether the route is correct and avoids unnecessarily proxying package registries, private repositories, or local development services. If the profile has no suitable rules for the service you need, temporarily testing global mode can distinguish a rule problem from a general connectivity problem. Restore rule mode after the test.

Choose system proxy mode or TUN mode

System proxy mode is usually the best starting point for a terminal setup. It changes the operating system’s HTTP and HTTPS proxy settings, but applications must still honor those settings. TUN mode creates a virtual network interface and can capture traffic from applications that ignore system proxy variables. It may also involve administrator approval, route changes, DNS interception, and conflicts with another VPN or security product.

• Start with system proxy mode: Use it when Claude Code accepts proxy environment variables and you want a narrow, easy-to-debug configuration.
• Consider TUN mode: Use it when a tool ignores both system proxy settings and explicit proxy variables, or when several applications need transparent routing.
• Avoid running two tunnel services together: Another VPN, corporate endpoint client, or transparent proxy can change routes and DNS responses.
• Keep LAN access disabled unless required: allow-lan: false prevents other devices on the local network from using the listener.

Make sure the Clash Verge core is actually running before testing the terminal. On Windows, check the tray status and the active port in the dashboard. On macOS and Linux, inspect the dashboard and, if necessary, verify that a process is listening locally. A terminal proxy variable pointing to 127.0.0.1:7890 is useful only while Clash Verge owns that port.

# macOS or Linux
nc -vz 127.0.0.1 7890

# Windows PowerShell
Test-NetConnection 127.0.0.1 -Port 7890

A successful local port test proves only that something is listening. It does not prove that the selected proxy node, DNS mode, or remote route is working. Continue with an HTTPS request through the same proxy that Claude Code will use. Keep the target generic and do not paste private subscription URLs, authentication headers, or API keys into public logs.

curl -I -L \
  --proxy http://127.0.0.1:7890 \
  --connect-timeout 10 \
  --max-time 30 \
  https://example.com

If this request fails, troubleshoot Clash Verge before changing Claude Code. Look at the core log for DNS failures, rejected rules, connection resets, TLS errors, or a proxy-group selection that points to an unavailable node. If the request succeeds but Claude Code still fails, the next place to inspect is the shell environment and the application’s own authentication flow.

Configure proxy variables in the shell

Most command-line tools discover a proxy through environment variables. Set both uppercase and lowercase names because different libraries look for different spellings. The value should normally include a scheme and a local port. For a Clash Verge mixed or HTTP listener, use http://127.0.0.1:7890. The word “HTTP” describes the local proxy protocol; it does not mean that HTTPS destinations are downgraded. An HTTP proxy can establish a CONNECT tunnel for HTTPS requests.

PowerShell on Windows

For a temporary session, open a new PowerShell window and run:

$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:http_proxy = $env:HTTP_PROXY
$env:https_proxy = $env:HTTPS_PROXY
$env:NO_PROXY = "localhost,127.0.0.1,::1"

claude

These values disappear when the PowerShell window closes. That is useful while diagnosing the setup. If the request works, you can decide whether to store them as user-level environment variables through Windows settings. Permanent variables affect package managers, Git, language tooling, and scripts launched from the same account, so review them before making the change global.

macOS and Linux shells

For Bash, Zsh, or a similar shell, export the variables in the current session:

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

claude

To make the setting persistent, add it to the shell startup file used by your interactive terminal, such as ~/.zshrc or ~/.bashrc. Do not place secrets in that file. A local proxy address is not a secret, but a subscription URL, API key, OAuth token, or generated credential must be protected. After editing the file, open a fresh terminal or reload it with the appropriate shell command.

SOCKS listeners and compatibility

Clash Verge may expose a SOCKS5 listener in addition to the mixed port. Some command-line programs support ALL_PROXY=socks5://127.0.0.1:7891, but support varies by runtime and dependency. A tool can accept the variable and still fail because its HTTP library does not implement SOCKS5, does not resolve DNS through the proxy, or uses a separate networking path for authentication. For the broadest initial compatibility, test the HTTP-style mixed listener first.

Perform a complete terminal test before signing in

A reliable setup is easier to diagnose when tested in layers. The following sequence deliberately moves from the local listener to a generic HTTPS request, then to the Claude Code command. Perform it in the same terminal where Claude Code will run, because environment variables are inherited by child processes and can differ between PowerShell, Command Prompt, integrated IDE terminals, and graphical launchers.

1. Confirm the Clash Verge core: Verify that the selected profile is running and note the actual mixed port. Check that the policy group has a usable selection.
2. Confirm the local listener: Run Test-NetConnection on Windows or nc -vz on macOS and Linux. A refused connection means the port or core state is wrong.
3. Confirm an HTTPS route: Use curl --proxy against a harmless public HTTPS address. Check the Clash Verge connection log while the request is running.
4. Confirm inherited variables: Print the variable names and local proxy address. Avoid displaying any variable that could contain credentials.
5. Launch Claude Code from that terminal: Start the CLI after the variables are set rather than launching it from a desktop shortcut with a different environment.
6. Complete authentication: If a browser window opens, make sure the browser itself can reach the sign-in page. Browser access and terminal API access are related but separate tests.
7. Run a small request: Ask for a short explanation of a local file or a simple project command. This avoids confusing a network failure with a large context, permission, or project configuration problem.

On Windows PowerShell, you can inspect only the relevant values like this:

Get-ChildItem Env:HTTP_PROXY,Env:HTTPS_PROXY,Env:NO_PROXY

curl.exe -I -L `
  --proxy $env:HTTPS_PROXY `
  --connect-timeout 10 `
  --max-time 30 `
  https://example.com

On macOS or Linux, use:

printf 'HTTP proxy: %s\n' "$HTTP_PROXY"
printf 'HTTPS proxy: %s\n' "$HTTPS_PROXY"
printf 'NO_PROXY: %s\n' "$NO_PROXY"

curl -I -L \
  --proxy "$HTTPS_PROXY" \
  --connect-timeout 10 \
  --max-time 30 \
  https://example.com

If the generic request is successful but the sign-in page does not open, check the default browser, system proxy setting, DNS filtering, and any corporate security policy. If sign-in completes but subsequent Claude Code requests fail, inspect the Clash Verge log at the exact time of the request. A rule may be sending one domain through a different policy group, or the selected node may allow the login page but reset longer API connections.

Troubleshoot common errors and keep the setup safe

Claude Code errors should be compared with the Clash Verge core log and the terminal’s own output. A timeout before any connection appears in the core log often means the process is not using the proxy variables or the variable points to the wrong port. A connection that appears in the log but ends with a reset suggests a node, routing, TLS, or remote-service problem. A DNS error can come from the mihomo DNS mode, a blocked resolver, or a rule that sends DNS traffic in an unexpected direction.

• Connection refused: Check whether Clash Verge is running, whether the port is correct, and whether another application has replaced the configured listener.
• Proxy connection failed: Test another policy group or node, then inspect the core log for handshake and outbound errors.
• Timeout: Confirm that the terminal inherited the variables. Test with curl from the same shell and check whether TUN or another VPN changed the route.
• Certificate or TLS error: Do not disable certificate verification as a first response. Test another node, check the system clock, and review whether antivirus software is intercepting HTTPS.
• Sign-in opens but does not finish: Check the browser’s network path, callback handling, firewall prompts, and whether a stale session is cached. Restarting the CLI after changing proxy settings may be necessary.
• Requests work in one terminal but not an IDE: The IDE may have been opened before the variables were set, or its integrated terminal may use a different shell startup file.
• Local development stops working: Add only local addresses to NO_PROXY, such as localhost,127.0.0.1,::1. Do not broadly bypass domains unless you understand the effect.

When the configuration works, keep the setup minimal. Use the mixed port that has been verified, one shell configuration method, and one clearly selected policy group. If a project uses local package registries, internal Git servers, Docker services, or remote development hosts, decide separately whether each should be direct or proxied. A broad NO_PROXY list can unintentionally bypass the route needed by a private service, while an overly narrow list can send local traffic through an external node.

Protect authentication data throughout the process. Do not paste complete subscription URLs, access tokens, API keys, OAuth callback URLs, or terminal transcripts containing credentials into issue reports or screenshots. When sharing a diagnostic command, replace the subscription token with a placeholder and redact authorization headers. If a credential appears in a public log, revoke or rotate it through the relevant service rather than relying on deletion of the post.

Finally, remember that Clash Verge does not repair an expired account, an unavailable service, an invalid model setting, or a project permission error. Its role is to provide a local routing path. Once the local port, proxy request, shell variables, and core logs all agree, remaining failures should be investigated in Claude Code’s authentication state, account access, project permissions, or service status. This separation keeps the terminal workflow understandable and makes future changes safer.