Gemini CLI With Clash Verge: Setup Guide For Reliable Access

Gemini CLI is becoming a popular way to bring AI assistance into the terminal, but access and API requests may fail on restricted networks. Learn how to pair it with Clash Verge, configure routing, choose a suitable node, and fix the most common connection issues.

Understand the connection path before changing settings

Gemini CLI runs in a terminal, but its network behavior is not necessarily the same as a web browser. A browser may read the operating system proxy, use a browser extension, or apply an application-specific proxy setting. A command-line tool may instead open a direct HTTPS connection, read proxy-related environment variables, use a runtime-specific agent, or rely on a system-level tunnel. This difference explains why Gemini CLI can fail while ordinary websites continue to load normally.

Clash Verge is a graphical client. It provides the interface for importing configurations, selecting proxy groups, enabling the system proxy, viewing connections, and activating TUN mode. The actual connection processing is performed by the proxy core bundled with or selected by the client. In current Clash-compatible setups, that core is often Mihomo. The client and the core are related, but they are not the same component.

A successful setup has several separate links. Clash Verge must be running, the core must have loaded a valid configuration, a local HTTP or mixed port must be listening, the selected proxy group must contain a usable node, and Gemini CLI must send its requests through a path that reaches that local proxy. Authentication is another independent layer: Gemini CLI may need Google account authorization or an API key, depending on how it was installed and configured.

Layer What it controls Typical failure symptom
Clash Verge GUI controls, profiles, system proxy, TUN, logs The switch appears enabled, but no core is running
Mihomo or another core Ports, DNS, rules, proxy connections, routing The profile fails to load or nodes cannot connect
Terminal runtime How Gemini CLI creates outbound HTTPS requests Browser works, but Gemini CLI times out
Google authentication Account login, API key, project and quota checks Network works, but authorization is rejected

Prepare Clash Verge and select the right profile

Install a current Clash-compatible desktop client and open Clash Verge before testing Gemini CLI. The exact names of menus may differ between Clash Verge and Clash Verge Rev, but the required checks are similar: the client should show an active profile, a running core, a local listener, and a proxy group with available nodes.

Import your subscription or local YAML configuration through the client’s profile management page. If the profile comes from a subscription, allow the client to complete the update before switching modes. A partially downloaded profile can contain no usable proxies, outdated provider references, or rules that point to groups that no longer exist. If you maintain YAML manually, verify indentation and confirm that the names referenced by proxy-groups and rules are present.

Start with Rule mode rather than Global mode. Rule mode lets ordinary domestic or local traffic remain direct while selected destinations use a proxy group. This is easier to diagnose because the connection log shows which rule matched the request. Global mode can be useful as a temporary test, but it changes the behavior of every application and can hide a rule-order problem.

Check the local port in Clash Verge instead of assuming it is 7890. Common configurations use an HTTP port, a SOCKS port, or a mixed port. A mixed port accepts both HTTP and SOCKS5 connections and is convenient for command-line testing, although the exact protocol still matters when a tool is configured explicitly.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

This is only a structural example, not a complete Gemini configuration. Keep allow-lan: false when the proxy is needed only on the same computer. Enabling LAN access exposes the listener to other devices on the network and should be accompanied by an appropriate bind address, firewall policy, and authentication strategy. Do not expose a local proxy port to an untrusted network merely to solve a terminal connection problem.

Verify the running core and local listener

Look at the dashboard or log panel and confirm that the core has started without YAML parsing errors. A profile may be visible in the interface while the runtime configuration is still invalid. Pay attention to messages about an occupied port, missing rule providers, unavailable external resources, unsupported fields, or failed DNS initialization.

You can also test the port from the operating system. On Windows, PowerShell can check whether a local TCP port is accepting connections:

Test-NetConnection 127.0.0.1 -Port 7890

On macOS or Linux, a similar check can be made with:

curl -I -x http://127.0.0.1:7890 https://example.com

Replace the port with the value shown by Clash Verge. The purpose of this command is to verify the local proxy path, not to prove that Gemini authentication is configured. If the command cannot connect to the local port, changing Gemini credentials will not help; repair the Clash runtime first.

Configure routing for Gemini and Google endpoints

Gemini CLI may contact more than one Google-related endpoint. Depending on the authentication method and product version, requests can involve the Gemini API, Google identity services, account authorization pages, project or quota services, and supporting Google domains. Therefore, routing only one guessed hostname is fragile. A rule that allows the login page but sends API requests direct can produce a confusing setup in which authentication succeeds and model requests fail.

When a domain-specific rule is needed, use the domain names and rule providers supplied by your configuration service or maintain a carefully reviewed Google-related policy group. The exact destination list can change, and a broad rule may route more traffic than intended. A generic structure might look like this:

proxy-groups:
  - name: AI Services
    type: select
    proxies:
      - Fast Node
      - Auto Select
      - DIRECT

rules:
  - DOMAIN-SUFFIX,googleapis.com,AI Services
  - DOMAIN-SUFFIX,google.com,AI Services
  - MATCH,Final

Do not copy this example without reviewing your existing group names and the policy requirements of your network. The names Fast Node, Auto Select, and Final are placeholders. A rule referring to a nonexistent group can make the configuration fail or route traffic unexpectedly. If your subscription already defines a Google, AI, or international services group, use that existing group instead of creating duplicate policy chains.

Rule order is important. Clash evaluates rules from top to bottom and uses the first matching rule. A broad GEOIP, RULE-SET, or MATCH entry placed before a Google domain rule can capture the request first. During diagnosis, inspect the connection log for the requested hostname, matched rule, selected group, and final node. This is more reliable than judging the configuration from its visual appearance.

Perform a hands-on terminal test

Before launching a long Gemini CLI session, test the local proxy with a simple HTTPS request. This separates four questions: whether Clash is listening, whether the selected node can reach the destination, whether the terminal tool understands the proxy syntax, and whether Gemini authentication is valid.

First select a known working node or a latency-tested group in Clash Verge. Avoid judging a node only by latency to a generic website. A node can have low latency but still fail to establish stable TLS connections to the domains used by Google services. Watch the connection panel while running the test so that you can confirm the request enters Clash.

For an HTTP proxy or mixed port, try:

curl -I -x http://127.0.0.1:7890 https://generativelanguage.googleapis.com

If you are using a SOCKS port, use the SOCKS5 hostname form so that DNS resolution can also occur through the proxy:

curl -I --proxy socks5h://127.0.0.1:7891 https://generativelanguage.googleapis.com

A response such as 401, 403, or another application-level HTTP status can still be useful. It may prove that the request reached the remote service and that the remaining problem is credentials, permissions, quota, or the request format. In contrast, a connection timeout, refused local connection, or DNS failure points to the proxy path rather than the API key.

For tools that honor standard proxy environment variables, you can temporarily set them in the current terminal session:

# PowerShell
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:HTTP_PROXY="http://127.0.0.1:7890"

# macOS or Linux
export HTTPS_PROXY="http://127.0.0.1:7890"
export HTTP_PROXY="http://127.0.0.1:7890"

Environment variable support is application-dependent. Node.js programs do not all interpret HTTP_PROXY and HTTPS_PROXY in the same way, especially when they use the built-in fetch implementation or a custom HTTP agent. Treat these variables as a test, not a guarantee. If the variables have no effect, use Clash Verge TUN mode or the proxy mechanism documented by the installed Gemini CLI release. Do not invent an unsupported command-line flag.

After the basic request succeeds, run Gemini CLI and watch the Clash connection log. A genuine test should produce new entries while the command is starting, authenticating, or sending a prompt. If no entry appears, the CLI is bypassing the local proxy. If entries appear but fail at a Google hostname, inspect the matched rule and node. If entries succeed and the CLI still reports an error, move to authentication and application logs.

Choose a stable node and suitable operating mode

Interactive AI coding sessions are more sensitive to stability than a single webpage load. Gemini CLI may create several HTTPS requests during startup, authentication, model selection, prompt submission, and response streaming. A node that works for a brief page request may reset long-lived connections, suffer packet loss, or perform poorly during streamed output.

Test result Likely interpretation Recommended action
Local port refused Clash core is not listening or the port is wrong Check the active profile, port, and core log
Request enters Clash but times out Node, route, DNS, or remote connectivity problem Try another node and inspect the matched rule
HTTPS returns an HTTP error The remote service was reached Check credentials, quota, project, or API permissions
No Clash log entry Gemini CLI is bypassing Clash Use an explicit supported proxy method or TUN mode

Use a select group while troubleshooting because it gives you a fixed node for comparison. An automatic health-check group is convenient for daily use, but it can change nodes during testing and make results difficult to reproduce. Once a stable route is identified, return to automatic selection if its health-check interval and fallback behavior are suitable.

System proxy mode is lightweight and affects applications that follow the operating system’s proxy setting. TUN mode works at a lower network layer and can capture applications that ignore system proxy settings, but it may require administrator permission and can change DNS and routing behavior for the entire device. Enable TUN only after understanding its impact, and disable other VPN or tunnel software that may compete for the same traffic.

Keep authentication separate from proxy configuration

A working proxy does not automatically provide Gemini CLI access. The CLI still needs a valid authentication method supported by its current release. Depending on the installation and account type, that may involve an interactive Google sign-in, an API key such as GEMINI_API_KEY or GOOGLE_API_KEY, or a cloud project with the required service enabled. Follow the authentication instructions for the version you installed rather than combining variables from unrelated tutorials.

Check whether the variable is defined in the same terminal session where Gemini CLI runs. On PowerShell, use $env:GEMINI_API_KEY to inspect whether a value is present without printing it in a shared screen. On macOS or Linux, use printenv GEMINI_API_KEY. Avoid placing keys directly in shell history, public configuration files, screenshots, or project repositories. If a key has been exposed, revoke it and create a replacement through the appropriate Google management interface.

Authentication pages may open in a browser while the token exchange happens in the terminal. This creates another possible split path: the browser can reach the sign-in page through Clash, while the CLI cannot reach the token endpoint. Keep Clash’s connection log visible during the complete login flow. A successful browser redirect alone is not sufficient evidence that the CLI completed authorization.

When the error mentions invalid credentials, permission denied, a missing project, quota, or an unsupported model, first remove proxy changes from the investigation. Test the same credentials with the documented API workflow, confirm the selected model is available to the account, and verify that the system clock is accurate. Incorrect time can invalidate secure authentication tokens even when basic HTTPS connectivity works.

Troubleshoot the most common failures

The system proxy is enabled but Gemini CLI remains direct

This is the most common misunderstanding. The system proxy switch changes an operating-system setting; it does not force every process to use that setting. Confirm the behavior with the connection log. If the CLI creates no relevant entry, test an explicit proxy environment variable, check whether the installed CLI documents proxy support, or enable TUN mode. Close and restart the terminal after changing persistent environment variables so the process receives the new values.

The hostname cannot be resolved

DNS failures can occur before the request reaches the proxy. Check the DNS mode in Clash Verge, the active rule, and whether another VPN or security product is intercepting DNS. SOCKS5 tests should use socks5h when you want the proxy to resolve the hostname. With TUN mode, verify that the selected DNS enhanced mode and fake-IP or redirection settings are compatible with the rest of the configuration. Do not change several DNS options at once; record the original values and test one change at a time.

TLS errors, resets, and intermittent timeouts

First compare a direct request and a proxied request only when doing so is safe and appropriate for your network. Then change one node, not the entire configuration. Check the system clock, local security software, MTU-related issues, and whether the node supports stable long-lived HTTPS connections. Repeatedly switching between system proxy, TUN, and multiple VPN applications can leave stale routes behind, so restart the relevant client or network adapter after a controlled change.

The profile stops loading after an edit

Validate YAML indentation, duplicate keys, quoted special characters, and references to proxy groups or providers. A subscription-generated file may be overwritten during its next update, so persistent customization should use the client’s supported override or merge mechanism. Keep a backup of the last working profile and restore it before testing a new rule. This makes it possible to tell whether the failure came from the routing change or from an unrelated subscription update.

Build a repeatable daily setup

Once Gemini CLI works, write down the important values instead of relying on memory. Record the Clash Verge profile name, the local port, the selected policy group, whether system proxy or TUN is required, and the authentication method. Do not record secret keys in the same note. A short operational record makes future failures easier to classify after a profile refresh or client update.

Use a fixed diagnostic sequence whenever access breaks. Confirm that Clash Verge is running, verify that the core has loaded the intended profile, check the local port, select a known stable node, test a harmless HTTPS request, inspect the Clash connection log, and only then test Gemini CLI authentication. This sequence moves from local components to remote services and prevents credentials from being changed when the real problem is a closed port.

Keep routing rules narrow enough to understand and broad enough to cover the authentication and API paths required by your workflow. Review rule-provider updates before applying them to a production configuration. If a service changes its endpoints, an outdated domain rule may silently send traffic direct or to the wrong policy group. Logging is especially useful after a subscription update because it reveals the actual hostname, rule, and node rather than the name you expected to be used.

Finally, treat TUN mode and broad proxy rules as operational choices rather than permanent fixes. TUN can solve applications that ignore system proxy settings, but it also affects package managers, development tools, local services, and DNS behavior. If only Gemini CLI needs the route, an explicit supported proxy configuration may be cleaner. If several terminal applications need the same route and cannot be configured independently, TUN may provide the more consistent result.

For platform-specific client installation and the first configuration steps, use the site’s setup tutorial. When you are ready to obtain a compatible client, open the download page. The essential principle remains the same: verify the request path, verify the local listener, verify the selected route, and treat authentication as a separate layer.

Download Clash