Claude Code Proxy Setup With Clash for Reliable Terminal Access

Understand how Claude Code reaches the network

Claude Code runs in a terminal, but its network requests do not automatically follow the same path as traffic from a browser. A browser may read the operating system’s proxy setting, use a browser extension, or have its own proxy configuration. A command-line program may instead connect directly unless it is given proxy environment variables or its traffic is captured by a network-level feature such as TUN.

For a typical setup, the path is: Claude Code starts a request, the operating system or terminal directs it to Clash, the Clash core matches the destination against its rules, and the selected proxy group chooses a node. Each stage can fail independently. A working browser therefore does not prove that Claude Code is using Clash, and a connected Clash node does not prove that the relevant API domain is routed through that node.

Start by checking the actual route rather than repeatedly changing nodes. Keep the Clash client running, open its connection or traffic log, and then trigger one new request from Claude Code. Look for a connection associated with the API domain, the matched rule, and the selected proxy group. If no corresponding entry appears, troubleshoot the terminal-to-Clash connection first. If the request appears but fails, inspect the rule, node, DNS result, and the response reported by the command.

Claude Code may also contact more than one host during installation, authentication, updates, or normal use. A successful sign-in does not necessarily confirm that every later API request follows the same path. When diagnosing a failure, note what action triggered it and inspect the new connections produced by that action instead of assuming that one test covers all endpoints.

Prepare a Clash profile and confirm its listener

Before changing terminal settings, make sure the active profile loads successfully and that the Clash core is running. In Clash Verge or another desktop client, select the intended profile, wait for the configuration to finish loading, and confirm that a proxy group contains usable nodes. A profile can be selected while its subscription is expired, its providers have failed to update, or its group has no available outbound option.

Find the active local proxy port in the client’s settings or running configuration. Do not assume it is always 7890: profiles and clients can use different ports, and another local program may already occupy the expected one. A mixed-port accepts both HTTP and SOCKS requests. For Claude Code, an HTTP connection to a local mixed port is generally the simplest starting point because the HTTPS request can be carried through the HTTP proxy using the CONNECT method.

mixed-port: 7890
allow-lan: false
mode: rule

This is only an example of relevant YAML fields, not a complete profile. Do not replace a subscription-generated configuration with this snippet. Use the port actually shown by the running client, and make persistent changes through the client’s supported settings or override mechanism. Setting allow-lan: false keeps the listener limited to local use in this example; enabling LAN access is unnecessary for a terminal on the same computer and can expose the proxy to other devices.

Next, check that a proxy group used for external services is not set to DIRECT or to a failed node. In rule mode, the matching rule determines which group handles a connection; selecting a node in an unrelated group will not change that route. Temporarily selecting a known working node in the relevant group can help distinguish a node problem from a rule problem, but restore the intended group selection after testing.

Configure proxy variables for the terminal

For a first test, point the terminal’s HTTP and HTTPS proxy variables to the local HTTP or mixed port. Replace 7890 below if the active Clash listener uses a different port. The address uses http:// because the local proxy connection speaks HTTP; that does not mean the destination API request is sent without HTTPS encryption.

macOS and Linux shells

In a current terminal session, set both uppercase and lowercase forms for compatibility with tools that read one spelling rather than the other:

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"

Run Claude Code from that same terminal so it inherits the variables. If the variables are added to a shell startup file such as ~/.zshrc or ~/.bashrc, open a new terminal or reload the file before testing. Avoid putting credentials in a startup file unless the machine and file permissions are appropriately protected.

Windows PowerShell

Set process-level variables in the PowerShell window where Claude Code will run. These values apply to programs started from that window and do not require changing the system-wide proxy for every application.

$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

After setting the variables, start Claude Code from that PowerShell session. If the application was already running in another terminal or launched from a desktop shortcut, it may not inherit the new values. Close that process and start it from the configured shell before drawing conclusions.

If local services or domains must bypass the proxy, add them to NO_PROXY rather than disabling the proxy globally. Keep the list narrow: an overly broad entry can cause API traffic to go direct. To remove the temporary variables from the current PowerShell process, use Remove-Item Env:HTTP_PROXY, Env:HTTPS_PROXY, Env:ALL_PROXY, Env:http_proxy, Env:https_proxy, Env:all_proxy. In a POSIX shell, use unset for the corresponding names.

Choose system proxy or TUN mode deliberately

There are two practical ways to make terminal traffic reach Clash. They solve different problems, so begin with the more targeted option and use TUN only when the terminal or another required program does not honor proxy variables.

Approach How traffic enters Clash Best use Checks and limitations
Terminal proxy variables The application connects to the local HTTP or mixed proxy port. Testing Claude Code specifically, or keeping proxy behavior limited to selected shell sessions. Claude Code must inherit the variables, and the configured port must be listening. Other programs are unaffected unless they inherit the same environment.
System proxy Applications that read the operating system proxy setting send requests to Clash. Desktop applications and command-line tools that explicitly use system proxy settings. Many command-line programs ignore the system proxy. Confirm an actual request in Clash’s connection log.
TUN mode A virtual network interface routes a broader set of device traffic through the Clash core. Applications that ignore proxy variables or when broader device-level capture is required. Requires supported client and core features, appropriate permissions, and correct DNS and routing behavior. It can affect more traffic than intended.

For a controlled Claude Code test, terminal variables are usually the easiest starting point because they make the intended local proxy explicit. The system proxy can be convenient, but its presence in the operating system settings is not enough to prove that a CLI program uses it. If variables are set correctly and the request still bypasses Clash, TUN may be an option, provided the installed client and Mihomo core support it on that operating system.

When enabling TUN, follow the client’s permission prompts and check its status indicator rather than assuming that switching the toggle on completed the setup. Avoid running multiple proxy clients or enabling several competing virtual network adapters during diagnosis. They can create overlapping routes, conflicting DNS behavior, or unexpected traffic capture. Change one mechanism at a time, then confirm the resulting connection in the Clash log.

Verify the route, DNS, and proxy connection

First check that the local proxy port accepts connections. On macOS or Linux, curl can make a request through the configured proxy without changing global system settings:

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

On Windows, the same command is available in a current PowerShell environment if curl resolves to the expected executable. If needed, call curl.exe explicitly. A returned HTTP status—including an error status—can still show that a connection reached the server; this test is about establishing the HTTPS connection through the local proxy, not proving that a particular Claude Code operation is authorized.

While the request runs, inspect Clash’s connection log. Confirm that the destination appears, that it is handled by the intended rule and proxy group, and that the selected node is the one you expect. If curl succeeds but Claude Code fails, the local listener and at least one routed request are working. Focus next on inherited environment variables, the specific action’s destination, authentication, or a separate connection made by the CLI.

DNS can complicate the picture. With a domain-based rule, Clash needs to identify the destination domain; with an IP-based connection, resolution may happen before the connection reaches the proxy unless the configured DNS and routing features preserve the domain information. A DNS failure may appear as a lookup error before any useful proxy connection is established. Check the client’s DNS status and logs, and avoid adding speculative DNS fields to a subscription profile before confirming which core is active and which settings it supports.

Do not use one successful request as evidence that every hostname is covered. Review the new log entries for the exact operation that fails, including any separate authentication, update, or service request. If the rule sends the traffic to DIRECT, adjust the appropriate rule or group using the profile’s supported configuration method. If the rule selects a proxy but the connection fails, test a different healthy node in that same group and compare the results.

Troubleshoot common Claude Code connection failures

Use the symptom to choose the next check. Changing the node, DNS settings, terminal variables, and TUN state all at once makes it difficult to identify the cause and can hide a configuration error.

  • Connection refused to 127.0.0.1: The configured port is not listening, the port number is wrong, or the Clash core has stopped. Check the running client’s port and confirm that its core started successfully.
  • The request succeeds in a browser but no terminal connection appears in Clash: The browser is using a different route, or the terminal process did not inherit the proxy variables. Start Claude Code in the shell where the variables are set and retry one operation.
  • A connection appears with a DIRECT policy: The request reached Clash, but the matched rule selected a direct route. Inspect rule order and the selected policy group. A node selection in another group will not override the matching rule.
  • The log shows a proxy node but the request times out: Confirm that the node is available, test another node in the same group, and check whether the failure is consistent for the same destination. A successful latency test does not guarantee that every destination or protocol will work through that node.
  • DNS lookup fails before a connection is logged: Check whether the system resolver or Clash DNS can resolve the relevant host. Look for DNS errors in the client log and review TUN DNS handling if TUN is enabled. Do not assume that changing the proxy node will repair a local resolver failure.
  • Only one Claude Code action fails: Inspect the connection log while repeating that exact action. Different operations can contact different hosts or use a different authentication flow, so test and route the destination that actually fails.
  • Variables appear set but behavior does not change: Check them in the same shell that launches Claude Code, close old processes, and verify that no startup script or application wrapper overwrites them. Also check for a conflicting NO_PROXY entry.

Keep secrets out of diagnostic output. Do not paste API credentials into a proxy URL, YAML profile, terminal command saved in shell history, or a report shared with others. Connection logs can reveal domains, local addresses, and usage patterns; review and redact them before sharing. If credentials may have been exposed, rotate them through the service that issued them.

Once requests are visible in Clash and consistently use the intended policy, keep the simplest working setup. For many users that means process-level proxy variables and the existing profile, without enabling TUN or making broad DNS changes. If a wider capture method is required, document the client’s TUN state and any DNS changes so that future failures can be compared against a known working configuration.

Download Clash