Why Claude Code Needs a Different Proxy Setup

Claude Code brings Anthropic’s coding assistant into the terminal. Instead of opening a browser chat, you run commands from a project directory, let the agent inspect files, approve edits, execute selected tools, and stream responses while you continue working in your normal shell. That workflow is powerful, but it also exposes a networking detail many beginner guides skip: a terminal process does not automatically behave like a browser.

A browser may inherit the operating system proxy configured by Clash Verge, while Node.js, Git, npm, and the Claude Code runtime can use their own HTTP or HTTPS connection logic. Authentication may open a browser successfully, yet the CLI still fails to exchange a token. Package installation can work through one route, while API streaming takes a different route and hangs after the first request. In other cases, the shell reaches Anthropic directly, receives a timeout or connection reset, and reports an error that looks like a Claude account problem.

This is why a Claude Code terminal proxy setup should be treated as three related but separate lanes: installing the command-line package, completing authentication, and maintaining stable API traffic during a coding session. Clash Verge can provide the proxy listener and rule engine, but it cannot force every application to use that listener unless you configure the operating system, environment variables, or TUN capture appropriately.

The goal is not to send every connection through one arbitrary node. A better configuration keeps local development services and private repositories on DIRECT, routes the required Anthropic and package-hosting traffic through a reliable proxy group, and leaves enough visibility in the Clash Verge connection log to identify the exact hostname that failed. This approach also makes troubleshooting repeatable when you switch projects, terminals, or machines.

The Traffic Lanes You Need to Account For

Before changing rules, separate the workflow into connection types. The exact hostnames can change as Claude Code evolves, and an organization may add a custom gateway, but the categories remain useful. Watch the live connection panel in Clash Verge while performing each action; the matched rule and selected proxy group are more trustworthy than a copied hostname list from an old forum post.

For most users, a dedicated rule group such as CLAUDE is easier to maintain than placing every AI-related domain into a generic PROXY group. The group can point to a stable node or a small manual selection. Avoid a latency-testing group that changes nodes during an active coding session; a brief health-check improvement is not worth interrupting a streaming response or invalidating a connection.

The package lane deserves separate attention. A global install command may contact the npm registry for metadata and then retrieve a tarball from another host. If the first request succeeds but the archive download fails, the problem is often a split between registry and CDN routing rather than a broken npm installation. Similarly, Claude Code updates or helper components may use GitHub infrastructure even when the primary package was installed from npm. Check the connection log instead of assuming that one successful domain proves the whole installation path is reachable.

Authentication is also not one single request. The CLI may launch a browser, wait for the user to approve access, and then perform a separate token exchange from the terminal. If only the browser is proxied, the approval page can finish while the CLI remains stuck at a waiting message. Conversely, if the browser callback is redirected to a local address, TUN mode or an overbroad rule can interfere with that local callback. Keep loopback and local development addresses direct, and inspect whether the callback is actually listening on the expected port.

Prepare Clash Verge Before Installing Claude Code

Start with one active Clash Verge profile. If Clash for Windows, another Verge build, or a second Mihomo client is running at the same time, several applications may compete for the same mixed port or TUN adapter. This can produce confusing results: the tray icon says the proxy is enabled, but the shell points to an old port; or a TUN interface exists while the active profile belongs to another process. Close competing clients and confirm which process owns the listener before testing Claude Code.

1. Update the profile: Open Clash Verge, select the intended profile, and refresh it. Confirm that the profile parses successfully and that at least one proxy node or proxy group is available.
2. Choose a stable group: Select a node manually or create a small group for Anthropic traffic. Prefer a route that remains stable during long HTTPS streams instead of choosing solely by the lowest ping.
3. Confirm the mixed port: In Clash Verge’s settings, note the local HTTP or mixed-port number. Common installations use a port such as 7890 or 7897, but never assume the number; copy the value displayed by your client.
4. Enable system proxy when appropriate: Turn on the system proxy option if you want applications that honor the operating system settings to use Clash Verge. This helps browsers and some desktop tools, but it does not guarantee that every terminal process will follow the setting.
5. Use TUN mode only when needed: If the shell, Git, or another native application ignores explicit proxy variables, enable Mihomo TUN mode and approve the required administrator permissions. Keep an eye on local-network access and exclude local development ranges if your profile provides that option.
6. Check the connection view: Leave the live connections panel visible while you run a small test. Verify that the request is captured by the expected rule and group, rather than merely seeing that Clash Verge has a running status icon.

On Windows, the system proxy toggle normally affects WinHTTP or browser-style applications inconsistently, so environment variables are often the clearest solution for a terminal. On macOS and Linux, the same principle applies even though shell startup files and GUI permission prompts differ. The important point is to configure the shell that actually launches Claude Code. A proxy variable set in one graphical terminal does not automatically appear in a newly opened integrated terminal inside an editor.

For an HTTP-compatible Clash listener, a temporary shell test can look like this:

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

On PowerShell, use the equivalent session variables:

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

Replace the port with the actual Clash Verge mixed port. These values affect only the current shell session, which is useful for diagnosis. Once the route works, you can place the appropriate exports in a shell profile such as ~/.zshrc, ~/.bashrc, or a PowerShell profile. Avoid permanently exporting a proxy on a laptop that frequently moves between networks unless you also know how to disable it; otherwise ordinary commands may fail when Clash Verge is closed.

Install and Authenticate Claude Code Through the Terminal

With the proxy path prepared, install Claude Code using the package method recommended by Anthropic for your account and platform. Do not copy a command from an unverified blog if the official package name or installation method has changed. The useful diagnostic habit is to watch Clash Verge while running the install: record which hosts appear during metadata lookup, archive download, and any post-install check.

1. Open a fresh terminal: Start the terminal after setting the proxy variables, or reload the shell profile. Run env | grep -i proxy on macOS or Linux, or inspect $env:HTTPS_PROXY in PowerShell, to confirm that the intended process can see the values.
2. Install the CLI: Run the current official Claude Code installation command. If npm is involved, verify the npm registry and the tarball download separately in the Clash Verge log rather than treating one successful line as proof that all traffic worked.
3. Verify the executable: Use the documented version command and check the resolved path with which claude or Get-Command claude. Multiple global installations can cause an old binary to run even after a successful update.
4. Start authentication: Launch the documented login or first-run command. Allow the browser window to open, complete the account approval, and return to the terminal without closing the waiting process.
5. Watch both sides: The browser may show success before the CLI finishes. In Clash Verge, confirm that the terminal-generated authentication and token requests are captured by the intended rule, while the local callback remains reachable through 127.0.0.1 or localhost.
6. Run a small verification: Open a test project, ask Claude Code for a read-only explanation of one file, and watch whether the response streams continuously. Do not begin with a large refactor while the route is still unproven.

If authentication opens no browser, first check whether the shell can launch the system browser and whether a corporate security tool blocks the callback. If the browser opens but the CLI waits forever, compare the browser and terminal connection paths. A common fix is to preserve the system proxy for the browser, explicitly set HTTPS_PROXY for the terminal, and add local callback addresses to NO_PROXY. If the CLI reports an invalid or expired session after a previously successful login, sign out through the supported command, remove only the relevant local credential cache, and authenticate again rather than deleting unrelated configuration files.

Do not put an API key directly into a command copied into shell history. If your workflow uses an API key instead of an account-based login, prefer the environment-variable mechanism documented by Anthropic and load it from a protected secret store. Check file permissions on local environment files, add them to .gitignore, and ensure that Claude Code cannot accidentally read a directory containing unrelated production credentials.

Debug Streaming, Git, and Local Project Tools

A successful login does not prove that an interactive coding session is healthy. Claude Code may keep an HTTPS connection open while it sends prompts, receives streamed output, and waits for tool results. A node that passes a short request can still reset long-lived connections. Test a small prompt first, then a request that reads a modest file, and only afterward allow commands that touch a larger repository.

When a request stalls, keep the terminal error and the Clash Verge connection record together. Note the timestamp, hostname, matched rule, selected group, and whether the connection was closed locally or remotely. Avoid repeatedly changing five variables at once. Switch to a known stable node, retry the same prompt, and then compare the result. If the same node works for browser traffic but fails for Claude Code, inspect whether the CLI is using the proxy variables you expected. If every node fails, examine DNS resolution, the profile rules, and the client runtime before assuming an Anthropic service outage.

• Install succeeds but the first prompt fails: The package lane is healthy, but API traffic is bypassing Clash, matching DIRECT, or using an unstable group.
• Browser approval succeeds but login times out: The terminal-side token exchange is probably not captured, or local callback traffic is being routed incorrectly.
• Responses stop halfway through: Test a stable manual node, disable rapid group switching, and inspect whether the proxy or firewall closes idle or long-lived TLS sessions.
• Git works in the browser but fails in Claude Code: Git has its own proxy configuration and may not inherit the shell variables. Check git config --global --get http.proxy before adding another setting.
• Local tools stop responding: Add only the necessary local addresses to NO_PROXY or use TUN exclusions for loopback, private subnets, Docker bridges, and development ports.

GitHub and package registries should not automatically share the same policy as Anthropic API traffic. Some teams need GitHub through a proxy but keep an internal GitLab instance direct. Others need npm metadata through a proxy while their private registry is reachable only on a company VPN. Use domain-specific rules and confirm the result in the live log. A broad rule such as “all foreign traffic through proxy” can break SSH remotes, internal dashboards, container registries, or license servers that are expected to stay on a corporate route.

DNS handling can change the result as well. If Clash Verge uses fake-IP or another enhanced DNS mode, ensure that the selected rule engine and TUN settings are compatible. A hostname that resolves outside Mihomo may be classified before the intended domain rule applies, while a local service may become unreachable if its synthetic address is not excluded. Do not change DNS mode merely because a command timed out; record the resolved address and matched rule first, then make one controlled change at a time.

Keep the Setup Maintainable

Save a short note containing the Clash Verge mixed port, the proxy variables used by your shell, the local addresses excluded from proxying, and the date you last tested authentication. Do not save secrets in that note. When you update Claude Code, Mihomo, or your subscription profile, retest installation, login, and one streaming prompt separately. This turns a future failure into a small comparison rather than a complete rebuild.

For shared machines, consider a project-specific wrapper that sets proxy variables only when Claude Code is launched. This avoids surprising other commands and makes the intended network path visible to teammates. For personal machines, a shell alias can be convenient, but document how to unset it when travelling or connecting to a network that blocks the configured proxy. A good terminal proxy setup is reversible, observable, and narrow enough that it does not hide ordinary connectivity problems.

Compared with browser-only AI tools, terminal assistants expose more moving parts: npm may use one host, authentication another, Git a separate proxy setting, and local development services must remain reachable without interception. Generic proxy GUIs often make those boundaries difficult to see, while fragmented client forks may provide inconsistent TUN permissions or limited documentation for current Mihomo profiles. Clash Official Site is useful here because its Clash-focused guidance keeps the setup practical: it explains listener variables, rule selection, terminal capture, and safe local exclusions in one workflow instead of treating “proxy enabled” as the end of the story. If you want a clear starting point for this Claude Code setup, download Clash Official Site and follow the relevant Clash Verge configuration steps on your machine.