Gemini CLI With Clash Verge: Setup Guide For Stable Access

How Gemini CLI and Clash Verge share the connection path

Gemini CLI runs inside a terminal, but it still depends on ordinary network components: a package registry for installation, an authentication endpoint for sign-in, and Google services for model requests. A browser may open successfully while the command line fails because these applications do not necessarily use the same proxy settings. The browser can follow the operating system proxy, while Node.js, npm, a terminal process, or a background helper may read environment variables instead.

Clash Verge acts as the local control panel for the Clash Meta or mihomo core. After a valid profile is loaded, the core listens on local ports such as an HTTP proxy port, a SOCKS port, or a mixed port. The exact values depend on the profile and client settings, so they should be read from Clash Verge rather than copied from an unrelated guide. Gemini CLI can then use one of two broad connection paths.

• Application proxy: the terminal or Node.js process is given an HTTP or HTTPS proxy address. Only applications that understand the setting use it.
• System proxy: Clash Verge writes the local proxy address into the operating system settings. Applications that honor system proxy configuration can use it automatically.
• TUN mode: mihomo creates a virtual network interface and captures a wider range of traffic, including programs that do not understand HTTP proxy variables.

The most reliable setup is not always the most aggressive one. Start with a normal system proxy or explicit terminal variables. Move to TUN mode only when a required process ignores those settings or when DNS and routing behavior need to be handled consistently across several applications.

Prepare Clash Verge before installing Gemini CLI

Install a current Clash Verge build that matches the operating system and architecture. Clash Verge is a graphical client, not a proxy subscription provider, so it needs a usable profile before it can route traffic. Use a subscription URL supplied by a service you are authorized to use, and avoid pasting private subscription links into public issue trackers, screenshots, or shell history.

1. Open Clash Verge and locate the Profiles or Subscriptions section.
2. Add the subscription URL, refresh it, and wait for the YAML profile to download.
3. Select the newly imported profile and confirm that it loads without a YAML parsing error.
4. Open the Proxies page and choose a working proxy group or node.
5. Run a URL test if the client provides one, then select a node that responds consistently rather than choosing only the smallest displayed number.
6. Enable System Proxy and verify that the operating system proxy switch is actually on.

A profile can import correctly and still be unsuitable for command-line work. Check that the selected group has an available node, that the profile mode is normally Rule, and that the local proxy port shown in Clash Verge is listening. A profile configured for Global mode sends nearly everything through the selected proxy, while Rule mode depends on its rule set. For troubleshooting, Global mode can be a temporary diagnostic; Rule mode is usually easier to keep for daily use.

Do not edit a provider-managed profile directly unless you know how the client handles updates. A refresh may replace manual changes. If Clash Verge supports local overrides, use an override file for stable additions such as command-line domains, and keep provider content separate. This also makes it easier to identify whether a failure comes from the subscription or from a local rule.

Install Gemini CLI and complete authentication

Gemini CLI is commonly installed through npm. First check that Node.js and npm are available in the same terminal where the tool will be used. Version requirements can change between releases, so consult the current Gemini CLI documentation if the installer reports an unsupported runtime. The basic checks are:

node --version
npm --version

If both commands return versions, install the package using the package name and method documented for the current release. A typical npm-based installation looks like this:

npm install --global @google/gemini-cli

After installation, confirm that the executable is visible:

gemini --version
gemini

The first launch may offer an interactive Google sign-in flow or an API-key-based option, depending on the release and account environment. Follow the prompt shown by the installed version. Authentication is separate from proxy selection: a browser window can complete sign-in while the CLI later fails to reach the model service, or the opposite can happen. Treat installation, authentication, and an actual model request as three separate tests.

On Windows, npm may install global binaries into a directory that is not present in the current PATH. If the installation succeeds but gemini is not recognized, run npm prefix --global, inspect the corresponding binary directory, and add it to the user PATH if necessary. Open a new terminal after changing PATH. On macOS and Linux, a permission error during global installation often indicates an npm directory ownership problem; changing the package manager layout is safer than repeatedly using elevated privileges.

Configure the terminal proxy explicitly

If System Proxy is enabled but Gemini CLI still cannot install packages or authenticate, configure the terminal process directly. In Clash Verge, open the settings or dashboard area that lists the HTTP, HTTPS, SOCKS, or mixed listener. Record the host and port shown there. The host is commonly a loopback address, but do not assume a fixed port because profiles and clients may differ.

For a temporary test, set proxy variables only in the current shell. Replace the example port with the HTTP-compatible listener displayed by Clash Verge:

# macOS, Linux, or a compatible POSIX shell
export HTTP_PROXY=http://127.0.0.1:PORT
export HTTPS_PROXY=http://127.0.0.1:PORT
export ALL_PROXY=http://127.0.0.1:PORT

# Windows PowerShell
$env:HTTP_PROXY="http://127.0.0.1:PORT"
$env:HTTPS_PROXY="http://127.0.0.1:PORT"
$env:ALL_PROXY="http://127.0.0.1:PORT"

Some tools treat uppercase and lowercase variable names differently. If a command ignores the first form, define both forms for the test:

export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export all_proxy="$ALL_PROXY"

Run npm with the proxy variables present and observe whether the behavior changes:

npm config get proxy
npm config get https-proxy
npm view @google/gemini-cli version

Environment variables and npm's own configuration are not identical. A stale npm setting can point to an old port even after Clash Verge changes its listener. If npm reports a proxy connection refusal, inspect and remove obsolete values rather than adding more layers of configuration:

npm config delete proxy
npm config delete https-proxy

Then retry with the temporary environment variables. If the command succeeds only when variables are present, the issue is probably application-level proxy discovery rather than Clash routing. If it fails in both cases, check the selected node, DNS behavior, system clock, certificate errors, and the exact destination named in the error message.

Choose System Proxy, TUN, or a mixed approach

System Proxy is the least invasive starting point. It works well for browsers, npm, and other tools that read HTTP proxy settings. It also makes the active state easy to understand: when the switch is off, applications normally connect directly; when it is on, supported applications use Clash's local listener. The limitation is that software may ignore system settings, use its own network stack, or launch with a clean environment that does not inherit the desktop configuration.

TUN mode operates at a lower layer. It is useful when a command-line helper, language package manager, or authentication component does not support a conventional proxy. It can also make DNS handling more consistent because mihomo can process captured traffic according to its configured DNS and routing policy. However, TUN mode requires elevated permissions and can interact with VPN software, security products, virtual machines, container networks, and corporate endpoint controls.

For a first diagnosis, turn on System Proxy, set the terminal variables, and test a single command. If that works, remove unnecessary variables and decide whether the system setting alone is sufficient. If the command still bypasses Clash, disable competing VPNs, inspect the terminal's inherited environment, and test TUN mode. When TUN is enabled, avoid running multiple tunnel clients at the same time unless their routing interaction is understood.

Add service-specific routing without proxying everything

Once basic access works, use rule-based routing to keep the configuration predictable. A Gemini CLI request may involve more than one hostname: package installation can use npm registry domains, authentication can redirect through account and identity services, and model requests can use Google API or Gemini-related endpoints. The exact hostnames can change by release, account type, region, and authentication method. Do not copy a broad domain list without checking the live connection log.

In Clash Verge, start the CLI action that fails, then open the Logs or Connections view. Look for rejected, timed-out, or direct connections and note the destination domain. A rule that matches the full domain is safer than a wide keyword rule. If several related subdomains are required, a suffix rule can be appropriate. In a local override, the conceptual order might look like this:

rules:
  - DOMAIN-SUFFIX,example-service.invalid,PROXY
  - DOMAIN,registry.npmjs.org,PROXY
  - MATCH,DIRECT

The domains above are placeholders except for the npm registry example; replace them with destinations actually observed in the connection log and with the proxy-group name used by the selected profile. A rule has no effect if its policy name does not exist in proxy-groups, and a rule placed below an earlier MATCH or broad rule will never be reached. Rule order is therefore as important as the domain itself.

Keep unrelated traffic on DIRECT when that is appropriate for the network. This reduces unnecessary load on the proxy and avoids breaking local services. Conversely, if a service uses several API hostnames and only one is proxied, authentication may appear to succeed while the actual model request times out. Review the entire connection sequence rather than testing only the first page that opens.

After changing an override, reload the profile in Clash Verge. Existing connections may keep their earlier route, so close and restart Gemini CLI before testing again. The connection log should show the selected rule and proxy group for the relevant request. If it continues to show DIRECT, verify that the override is loaded, the hostname is spelled correctly, and DNS is not replacing the domain with an IP before rule matching.

Diagnose installation, login, and request failures

Different stages produce different symptoms. Separate them instead of changing every setting at once. The following sequence narrows the fault quickly:

1. Confirm Clash Verge has a selected profile, a selected proxy group, and a running mihomo core.
2. Test the local listener from the same machine and confirm that the configured port is open.
3. Run npm view or another harmless package metadata request to test registry access.
4. Start Gemini CLI and complete authentication using the method offered by the installed release.
5. Run a small, non-sensitive prompt or command to test the model request separately from login.
6. Inspect Clash connections and mihomo logs for DNS errors, rejected rules, timeouts, or TLS failures.

A connection refused error normally means the terminal is pointing to a port where no listener is active, or Clash Verge is not running. A timeout suggests a bad node, unreachable destination, DNS trouble, or a rule that sent traffic to the wrong policy. An authentication redirect loop can indicate that the browser and CLI are using different routes, that a required identity domain is direct, or that the local callback was blocked. An npm certificate error should not be solved by disabling TLS verification; check the system clock, certificate store, intercepting security software, and proxy path instead.

If the browser opens the authentication page but Gemini CLI cannot complete the flow, compare the browser's route with the CLI's route. Explicit proxy variables can help the terminal, while TUN mode can capture a helper process that does not inherit those variables. If sign-in works but model requests fail, inspect the next connection entries after authentication; the required API hostname may be governed by a different rule.

When an update or profile refresh suddenly breaks a working setup, save the current profile name and compare the new rule order, proxy-group names, DNS mode, and listener port. Providers can change YAML structure or policy names. Re-importing the subscription may restore nodes but will not automatically restore a local override unless the client stores it separately. Keep a small written record of local settings so the setup can be rebuilt without exposing credentials.

Use a stable daily workflow

For regular coding work, keep the setup simple enough to explain. Start Clash Verge before opening the terminal, select a known working profile, and confirm the intended proxy group. Use System Proxy for tools that honor it and keep explicit environment variables limited to shells or scripts that need them. If TUN mode is required, enable it deliberately and check that local development services remain reachable.

Do not place subscription URLs, API keys, authentication tokens, or complete connection logs in project files. Shell commands can be recorded by terminal history, CI logs, or process inspection tools, so treat command-line credentials as sensitive. Use environment files that are excluded from version control only when the tool's authentication design supports that arrangement, and rotate exposed credentials promptly.

Before a long coding session, make a small test request and watch the first few connections in Clash Verge. This catches an expired subscription, a changed listener port, or a node that has become unreachable before a larger task is interrupted. When changing networks—from home Wi-Fi to a company network, a hotspot, or a VPN—repeat the test because DNS interception and firewall behavior can change.

Clash Verge does not guarantee that every Gemini CLI release will use the same endpoints or proxy behavior. Keep the client, mihomo core, Node.js runtime, and Gemini CLI package reasonably current, but update one component at a time when stability matters. Read the release notes for authentication and runtime changes, then verify the complete path: package registry, sign-in, model request, and local development traffic.