Why Claude Code needs a deliberate proxy setup

Claude Code brings an AI coding assistant into your terminal, where it can inspect project files, explain code, and help with development tasks. That workflow depends on network requests made by the process running in your shell. A browser that works through Clash Verge does not prove that Claude Code is using the same route: the browser may follow the operating system’s proxy setting, while a terminal process may rely on environment variables or its own network implementation.

This difference explains a common pattern: Claude Code starts normally, but sign-in, requests, or longer responses fail; meanwhile, ordinary websites continue to load. The issue may be a missing proxy variable, a proxy port copied from the wrong setting, a Clash rule sending a request DIRECT, or an unstable selected node. It can also be unrelated to routing—for example, invalid credentials, an account restriction, or a service-side error. Changing proxy settings blindly makes these cases harder to distinguish.

This guide uses Clash Verge as the desktop control panel and assumes you have a valid Clash-compatible subscription or configuration. Menu labels can vary by Clash Verge version and operating system, so follow the function described rather than relying on a particular button name. A proxy can improve connectivity only where its use is permitted and where the service is available to your account; it does not grant access rights, repair account problems, or guarantee uninterrupted service.

Add a subscription and confirm that a proxy works

Start by making sure Clash Verge itself is in a known-good state. Obtain the client from a source you trust, open it, and check that Mihomo is running without a startup error. If another VPN or proxy application is already managing your system proxy or virtual network interface, pause it while testing. Two network tools attempting to control the same settings can produce confusing results, including a browser that works while command-line applications fail.

Add your subscription using the provider’s documented import method. Depending on the build, this may mean pasting a subscription URL into the profiles area or importing a local configuration file. A subscription URL is a credential: do not post it in a public issue, terminal recording, screenshot, or chat. Once the profile appears, update it if the provider requires an explicit refresh, then select it as the active profile. A profile merely being listed does not mean that its proxies are available or selected.

Next, choose a proxy group and a node that the provider identifies as suitable for your use. If the group supports automatic selection or URL testing, let it finish before drawing conclusions. A successful latency check is useful but limited: it indicates that a test endpoint responded, not that every service Claude Code uses will work or that a long response will remain stable. If your provider documents a recommended group for developer tools, use that guidance rather than guessing from a node name.

Check the port settings shown in Clash Verge before configuring the terminal. The mixed port can accept both HTTP and SOCKS connections in many Mihomo configurations, but the actual value is profile-dependent and may differ from common examples. Do not assume that a port such as 7890 or 7897 is correct for your installation. Record the address and port displayed in your client, and confirm the listener is enabled. For a local desktop setup, the address is often 127.0.0.1; use a different address only if you deliberately configured a remote proxy.

Choose a mode for diagnosis. Rule mode is usually the practical everyday choice because it sends traffic according to the active configuration. Global mode sends more connections through the selected proxy and can help determine whether a rule is responsible, but it is not proof that every application must use that mode. Test a short request first, then return to the intended operating mode. If the client offers a system-proxy toggle, remember that enabling it primarily configures applications that honor the operating system setting; it does not necessarily configure a shell process.

Configure the shell that launches Claude Code

Claude Code needs to run in an environment that knows where the local proxy listener is. For many command-line tools, the most direct approach is to set HTTPS_PROXY and, when needed, HTTP_PROXY in the same terminal session before launching the tool. Use the protocol that matches your Clash listener. For a mixed port accepting HTTP proxy connections, a typical value has this form:

export HTTPS_PROXY=http://127.0.0.1:PORT
export HTTP_PROXY=http://127.0.0.1:PORT
claude

Replace PORT with the actual port displayed in Clash Verge. These are examples for a POSIX-style shell such as zsh or bash; they are not commands to paste unchanged. If you choose a SOCKS listener instead, use the appropriate SOCKS URL scheme supported by the client and your runtime. Avoid mixing a SOCKS scheme with an HTTP-only listener, or an HTTP scheme with a port that expects a different protocol.

On macOS and Linux, these exports apply to the current shell and processes launched from it. If you open a new terminal tab, start a separate shell, launch Claude Code from an IDE, or run it under a task runner, that process may not inherit the same variables. Put persistent settings in the startup file for the shell you actually use only after a one-session test succeeds. Then open a fresh terminal and verify the variables there. On Windows, the equivalent process-level environment settings depend on whether you use PowerShell, Command Prompt, Git Bash, or a development environment; use syntax appropriate to that shell rather than copying POSIX export commands.

Some HTTP clients recognize lowercase variable names as well. If a tool behaves inconsistently, you can set lowercase counterparts to the same local endpoint, provided that doing so does not conflict with your organization’s environment policy. Review NO_PROXY too: it tells compatible clients to bypass the proxy for listed hosts. An overly broad entry can accidentally exclude the destination you are trying to reach. Conversely, removing a carefully maintained corporate NO_PROXY value may break access to internal services. Preserve existing entries and make the smallest necessary change.

Keep the proxy environment scoped to the development task if other programs on your machine should not use it. When you have finished testing, unset temporary variables or close that terminal. If Claude Code is started by an IDE, service, container, or remote development environment, configuring your interactive shell alone may have no effect; set the environment in the component that actually launches the process, and follow that platform’s security guidance.

Verify the route instead of guessing

Run a small, repeatable test while Clash Verge is open and the intended profile and node are selected. First confirm that your terminal can reach the local proxy listener. Then make an HTTPS request to an endpoint you are authorized to test through the configured proxy. A successful generic request establishes that the shell can use the listener, but it does not confirm that every Claude Code request follows the same path.

For a more useful check, watch the client’s Connections or equivalent live-traffic view while Claude Code performs a normal sign-in or request. Inspect the destination hostname, rule match, selected proxy group, and final outbound. Hostnames and request patterns can change, so treat live connection records as evidence for your current session rather than relying on a copied, permanent list of domains. If the relevant connection appears as DIRECT when you expected it to use a proxy, review the active rules and profile behavior. If it does not appear at all, check whether the process is using another network path, whether the request has started, or whether the client’s logging view filters it.

Use one change at a time. If Rule mode fails, temporarily test Global mode with the same terminal environment and node. If Global works but Rule does not, the contrast points toward routing policy or rule matching; inspect the live connection and adjust only the relevant configuration through supported profile overrides. If both modes fail, test the local listener, try a different healthy node, and verify that the account and service are functioning. Restore your normal mode after the diagnostic test.

Do not treat a browser test as a substitute for a terminal test. Browsers may use operating-system proxy settings, extensions, or their own network behavior. Likewise, a command-line connectivity check may succeed while Claude Code still reports a login, permission, quota, or service error. Record the exact error text and the time of the test, but remove tokens, authorization headers, subscription URLs, and other secrets before sharing logs.

Troubleshoot common Claude Code connection failures

  • The browser works, but Claude Code cannot connect: Confirm that the shell launching Claude Code has the correct proxy variables and that their port matches the Clash Verge listener. If you start the tool from an IDE, terminal multiplexer, container, or remote host, inspect that environment rather than assuming it inherits settings from your desktop shell.
  • Requests fail immediately with a connection-refused message: Check that Clash Verge is running, that the listener is enabled, and that the address and port are correct. A stale environment variable pointing to a previous port can cause this symptom even when the client interface looks healthy.
  • Some requests work, but longer responses time out: Check the selected node’s stability and the live connection record during a request. A node that passes a quick latency test may still struggle with sustained traffic. Try another provider-approved node, avoid changing several settings at once, and repeat the same request to compare results.
  • Rule mode fails but Global mode works: The active rule set may be classifying a relevant connection differently than expected. Use the connection log to identify the actual destination and matched rule, then adjust the appropriate supported override. Do not replace your whole configuration with an unverified rule list from an old post.
  • Claude Code reports authentication, access, or quota errors: Read the service’s message and check the account, credentials, and applicable usage limits. A network proxy cannot correct an expired login, an invalid key, or an account-level restriction. Avoid repeatedly changing nodes when the response clearly identifies an authorization problem.
  • Sign-in opens a browser, but the terminal session does not complete: The browser and CLI may have different proxy or callback behavior. Keep the terminal open, follow the current sign-in instructions, and check whether local callback traffic is being affected by proxy variables or a NO_PROXY setting. Do not publish callback URLs that contain temporary credentials.

When a change fixes the problem, make it durable in the correct place: the Clash profile or supported override for routing policy, the shell startup configuration for an interactive terminal, or the IDE or process manager for a tool launched elsewhere. Keep a note of the working port, mode, and node group without recording secrets. This makes future profile updates easier to diagnose and reduces the chance that a temporary Global-mode test becomes an unexplained permanent setting.

Frequently asked questions

Is enabling the system proxy enough for Claude Code?

Not necessarily. The system-proxy option helps applications that honor the operating system’s proxy settings, but terminal tools may use environment variables or their own networking configuration. If the browser works and Claude Code does not, configure and verify the environment of the process that launches Claude Code.

Which Clash Verge port should I put in HTTPS_PROXY?

Use the listener port shown in your active Clash Verge configuration, not a value copied from an unrelated guide. Confirm whether that port accepts an HTTP proxy connection or SOCKS, then use a matching URL scheme. If you change profiles or listener settings, check the port again.

Should I leave Clash Verge in Global mode?

Usually, treat Global mode as a diagnostic comparison rather than an automatic permanent fix. Rule mode can keep unrelated and local traffic on its intended route. If Global mode resolves the issue, inspect the live connection and rule match so you can correct the specific routing behavior and return to the mode that fits your needs.

Is it safe to share my logs when asking for help?

Only after reviewing them. Remove subscription links, tokens, authorization headers, account identifiers, and private project details. Share the error message, operating system, client mode, and relevant redacted connection information instead. Never post a complete credential-bearing configuration publicly.

Choose a workflow you can verify

Some app-specific proxy tools offer fewer visible routing controls, while a manually configured shell can be difficult to maintain across terminals and IDEs. Clash Verge provides a practical middle ground for this workflow: a selected profile and node, observable connections, rule-based routing, and a local listener that can be passed explicitly to command-line processes. Those controls do not guarantee that Claude Code will always connect, but they make it easier to distinguish a routing problem from a shell-environment, account, or service issue. If you want to test this setup with a compatible configuration, start with the client download and verify each step against your own system.

Download Clash →