Start Here: What the Proxy Needs to Do
Claude Code runs in your terminal, so it does not always follow the same proxy settings as a browser. Turning on the system proxy in Clash Verge or starting the Mihomo core may route browser traffic successfully while leaving a command-line process unable to reach Anthropic’s services. The key is to give Claude Code a proxy address it can use and then confirm that the traffic is actually routed through the intended Clash policy.
This guide focuses on the common desktop setup: Clash Verge or Clash Verge Rev running a Mihomo-compatible core, with a local mixed port such as 7890. The same principles apply to other Mihomo clients, although menu names and default ports can differ. You will check the local listener, set proxy variables in the terminal that launches Claude Code, test connectivity, and investigate routing or authentication failures without changing more settings than necessary.
A terminal proxy has three separate parts: the Clash process must be running, a local proxy port must be listening, and the shell must pass that address to the Claude Code process. A failure at any one of these layers can look like an application error. For example, “connection refused” usually points to a missing listener or wrong port; a timeout may indicate a routing or node problem; and an authentication error usually means the network connection worked but the account or credentials need attention.
What You Will Configure
A local HTTP proxy environment variable for Claude Code, plus a repeatable way to verify the listener, connection, and Clash rule used by terminal traffic.
Before proceeding, make sure you have installed Claude Code using its supported installation method, can open your Clash client, and have a working profile with at least one usable proxy group or node. Do not paste subscription links, API keys, login tokens, or full environment dumps into public support channels. The commands below use a loopback address, 127.0.0.1, which means the proxy is on the same computer; it is not a remote server address.
1Verify the Clash or Mihomo Proxy Listener
First confirm which local port your client is listening on. In Clash Verge or Clash Verge Rev, open the settings or Mihomo configuration area and look for the mixed port, HTTP port, or SOCKS port. A typical setup uses 7890 as a mixed port, but yours may be different. Do not assume the example port is correct: using the wrong number is one of the most common reasons a terminal reports that it cannot connect.
A mixed port accepts both HTTP proxy requests and SOCKS connections. For Claude Code, starting with the HTTP form is usually the simplest option. If your configuration exposes separate ports instead, use the HTTP port for HTTP_PROXY and HTTPS_PROXY; do not point an HTTP proxy variable at a SOCKS-only listener. A SOCKS listener can be useful for tools that explicitly support it, but client support and environment-variable behavior vary.
If these commands show no listener, open the Clash client and ensure the core is running. Check the configured port again and repeat the command with that port. On some systems, another application may already occupy the expected port, causing the proxy core to fail to bind. The client’s log or core status panel can help distinguish that situation from a stopped core.
Choose the Right Proxy Address
For a local mixed port of 7890, the address commonly takes this form:
Use 127.0.0.1 rather than a LAN IP when Claude Code runs on the same computer. A loopback address keeps the proxy endpoint local and avoids exposing the proxy listener to other devices. Avoid changing the controller or external management port to solve a terminal connection problem: the controller is an administrative API, not the HTTP proxy endpoint. It should remain protected and should not be published to the public internet.
Also confirm that the selected Clash profile is loaded and that its proxy group has a working node selected. A listening port only proves that a local process accepts connections; it does not prove that the selected node can reach Anthropic’s services. If browser traffic is working but the terminal is not, continue with environment variables before changing the profile or DNS configuration.
2Set Proxy Variables in the Terminal
Command-line programs inherit environment variables from the shell that starts them. Set the variables in the same terminal session where you will run claude. This makes the configuration easy to test and avoids changing network behavior for unrelated applications. The standard uppercase variable names are widely recognized by command-line tools; setting lowercase equivalents as well can improve compatibility with software that checks only lowercase names.
macOS and Linux
In a Bash, Zsh, or compatible shell, replace 7890 with your actual HTTP or mixed port:
The value for HTTPS_PROXY commonly still begins with http://. That describes the protocol used between your terminal and the local HTTP proxy. The proxy then carries the HTTPS connection to the destination. Do not change it to https:// unless your local proxy listener is explicitly configured to accept TLS connections from clients.
These exports apply only to the current shell and programs started from it. If you open a new terminal window, run the commands again. To make them persistent, add the exports to the appropriate shell startup file, such as ~/.zshrc or ~/.bashrc, then open a new shell. For a shared or managed computer, session-only settings are often safer. If you do add them to a startup file, remember that any application launched from that shell may inherit the proxy variables.
Windows PowerShell
In PowerShell, set process-scoped variables before launching Claude Code:
PowerShell’s $env: assignments affect the current process and child processes, so a new terminal session will not automatically inherit them. This is useful for a quick test. If you use Windows Command Prompt instead, the equivalent syntax is set HTTP_PROXY=http://127.0.0.1:7890 and set HTTPS_PROXY=http://127.0.0.1:7890, followed by launching claude from that same window.
When setting variables permanently, avoid storing secret values in shell history or committing local configuration files to a repository. Proxy addresses shown here contain no credentials. If your proxy requires authentication, follow the proxy provider’s instructions and use a method that protects credentials; do not share a terminal screenshot or diagnostic output that reveals them.
Handle Local Addresses Carefully
Some development tools need to contact local services directly. If an existing NO_PROXY or no_proxy setting is present, preserve its entries rather than replacing it blindly. Typical exclusions include localhost and 127.0.0.1, but whether to include them depends on which local services your workflow uses. In most cases, Claude Code’s requests to Anthropic should not be excluded from the proxy; adding broad domains or wildcards to NO_PROXY can accidentally send those requests directly.
Environment variables are not a guarantee that every executable will use the proxy. A terminal application may use a networking library with different proxy support, or a wrapper script may launch the process with a cleaned environment. If the variables appear correct but the request still fails, test the local proxy independently and check the process’s launch method before editing more configuration.
3Test Routing and Fix Common Connection Errors
Before reopening Claude Code, test whether a basic HTTPS request can use the local proxy. The following command asks curl to use the proxy explicitly, so it can help separate a Clash connectivity problem from a Claude Code-specific problem:
A response from the remote service—even an HTTP error that says authentication or a particular API operation is required—can still demonstrate that DNS resolution, proxy connection, and TLS negotiation completed. What matters in this test is whether you receive a timely HTTP response rather than a local connection error or a long timeout. A successful curl test does not validate Claude Code credentials, but it is a useful network check.
Next, inspect Clash’s connection or traffic panel while running the test and then while starting Claude Code. Look for the destination domain, the selected rule, and the proxy group or node handling the connection. The exact interface labels differ between clients. If the traffic appears in the panel but is matched to DIRECT, review the active profile’s rules and rule order. If it is matched to the expected proxy group, confirm that the group has a usable node and that the node can reach the destination.
Pro Tip: Check the Request, Not Just the Switch
A system-proxy toggle is not a reliable test for terminal routing. Confirm the actual Claude Code or curl connection in Clash’s traffic view, then check which rule and outbound group handled it.
When reviewing rules, use the narrowest change that matches your needs. A domain suffix rule for anthropic.com can route relevant Anthropic domains through a selected proxy group, but it should be inserted before a broader rule that would otherwise send the same traffic directly. The policy name in the rule must match an existing group in the profile. Profiles and providers differ, so do not paste a rule using a made-up group name and assume it will work.
Some workflows use additional service domains for account login, console pages, or related features. Do not assume that every login or API request uses one hostname. Use the client’s connection log to identify the destination that failed, then add or adjust a rule only when the existing policy is responsible. Keep rule ordering in mind: a matching rule earlier in the list may take precedence over a later one.
| Symptom | Likely cause | What to check |
|---|---|---|
| Connection refused immediately | Wrong port, stopped core, or no listener | Check the mixed or HTTP port and verify that it is listening locally. |
| Request hangs or times out | Unusable node, routing rule, DNS, or network restriction | Check the Clash connection entry, selected group, and whether the same proxied curl request succeeds. |
| Browser works but Claude Code fails | Terminal process did not inherit proxy variables | Set variables in the same shell and launch claude from that session. |
| HTTP response appears, but sign-in fails | Authentication, account, or authorization issue | Confirm Claude Code’s account and login state; do not treat every HTTP error as a proxy failure. |
| One terminal works but another does not | Different shell environment or launch context | Compare the proxy variables in each terminal and check whether the editor launches its own environment. |
Interpret Errors by Layer
Connection refused usually means the local TCP connection could not reach a listening proxy. Recheck the address, port, and core status. Timeouts are less specific: the local listener might be reachable while the selected node, DNS path, or remote service is not responding. Compare the result with a direct local-proxy test and inspect the matching Clash connection.
Proxy-related errors can also come from a protocol mismatch. For example, an HTTP proxy variable pointed at a SOCKS-only port is not equivalent to configuring a SOCKS-aware client. Confirm the type of listener before switching variable names or adding a third-party wrapper. Authentication or permission errors are different again: if the service returned an HTTP response, the network path may be working, and the next step is to check your Claude Code account, subscription, or organization access.
If terminal traffic never appears in Clash, verify that Claude Code was launched after the variables were set and that the variable values are spelled correctly. In an IDE’s integrated terminal, inspect its shell settings and restart the terminal after changing environment variables. If traffic appears but uses the wrong route, adjust the active profile’s rule or proxy group and then repeat the test. Avoid changing DNS mode, TUN mode, and system proxy settings all at once; changing one variable at a time makes the cause of a fix—or a new failure—much easier to identify.
Finally, remove temporary proxy settings when you no longer need them. In macOS or Linux, use unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy. In PowerShell, use Remove-Item Env:HTTP_PROXY, Env:HTTPS_PROXY, Env:http_proxy, Env:https_proxy. Then start a fresh terminal process and check that the variables are gone. This is especially useful on shared devices or when switching between networks and development environments.
With the local listener confirmed, proxy variables set in the correct shell, and the actual connection visible in Clash’s traffic panel, you can identify whether a failure belongs to the local port, the profile’s routing policy, the selected node, or Claude Code’s own authentication. That layered approach is more reliable than repeatedly toggling system proxy or TUN mode without checking what the terminal is doing.