Why Gemini CLI Is a Terminal Problem, Not a Browser Tab

Gemini CLI—installed with npm install -g @google/gemini-cli—is Google’s agentic coding experience for the shell in 2026. It authenticates against Google accounts, validates API keys, streams model output from the Generative Language API, and may self-update through npm or GitHub-style distribution paths. None of that behaves like opening gemini.google.com in Chrome with system proxy enabled.

Clash only routes traffic that actually reaches its listeners. A browser tab might honor macOS or Windows proxy settings while your terminal opens direct TLS to generativelanguage.googleapis.com. The symptom cluster is familiar: Gemini CLI timeout on login, API key validation spinning forever, or the first prompt hanging—even though AI Studio in the browser feels fine. That is not proof your nodes are dead; it is proof your terminal AI proxy story is incomplete.

This article complements—not replaces—our Gemini and AI Studio split-rules guide, which focuses on browser consoles and studio UI hostnames. Here the lens is shell-first: npm install lanes, OAuth token exchange from a CLI process, and sustained API streaming under googleapis.com. If you also run enterprise agents on Google Cloud, see the separate Gemini Enterprise routing walkthrough; consumer CLI traffic rarely needs the full Cloud console surface.

Symptoms: Install Works, Auth and API Do Not

Developers searching for Gemini CLI Clash fixes usually describe one of these patterns:

• npm install -g @google/gemini-cli completes, but gemini auth login stalls at “Waiting for authentication” or times out after the browser tab opens.
• OAuth finishes in the browser while the CLI never receives the callback token exchange on oauth2.googleapis.com.
• gemini reports API key validation failures or generic network errors even when the key works from curl on another machine.
• The first model request hangs mid-stream while shorter health checks against unrelated sites succeed.
• Self-update or plugin fetch steps crawl because half the traffic hits DIRECT through an asymmetric path.

Each failure maps to a hostname class. Browser OAuth might only need accounts.google.com reachable through the browser’s proxy path, while the CLI continues to fail on token refresh because that socket never shared the same capture. Model calls may need generativelanguage.googleapis.com on a low-latency node, while npm metadata for updates rides registry.npmjs.org through a completely different rule hit. Your Clash split Google API policy should narrate what the connection log shows, not what a generic “Google proxy list” from 2024 claimed.

System Proxy, Environment Variables, or TUN for the Shell

Start with a decision tree before you edit YAML. If your terminal already exports working HTTP_PROXY, HTTPS_PROXY, and optionally ALL_PROXY pointed at Clash’s mixed or HTTP port—often 127.0.0.1:7890—Gemini CLI inherits them like any Node-based CLI. Your existing split rules should behave similarly to other proxied developer tools.

If the shell shows empty proxy variables, export them for the session or add them to your profile when policy allows. Some Google tooling respects NO_PROXY for localhost callbacks during OAuth; keep 127.0.0.1 and localhost in that list so the CLI can receive the loopback leg of auth while outbound Google API traffic still traverses Clash.

When the binary ignores explicit variables—which happens with certain updaters and native subprocesses—TUN mode becomes the honest fix because it captures IP traffic underneath application preferences. That trades convenience for breadth: every packet crosses Clash, so your DIRECT exceptions for LAN, captive portals, and domestic banking must be clean first. For stack-specific TUN notes, keep the TUN mode guide open while you test. The goal is not “TUN good, split bad”; it is matching capture depth to how stubborn the Gemini CLI process actually is.

Hostname Inventory: Google API, OAuth, and Install Dependencies

Google rotates edge configurations. Treat the list below as a baseline inventory you verify in your own log after one successful session, not as immutable gospel.

• Generative Language API: generativelanguage.googleapis.com is the marquee hostname for model inference and most programmatic Gemini CLI calls.
• Broader API surface: Some SDK paths touch additional *.googleapis.com subdomains. Log first, widen suffixes second.
• Google account OAuth: accounts.google.com, oauth2.googleapis.com, and sometimes www.googleapis.com participate in login and token refresh.
• Static and account assets: ssl.gstatic.com or other *.gstatic.com hosts may appear during auth pages opened in the browser leg of CLI login.
• Documentation fetches: ai.google.dev or related dev surfaces can show up when the CLI pulls help text or version metadata.
• npm install and updates: registry.npmjs.org, registry.npmmirror.com if you mirror domestically, and tarball CDN-style hosts documented in our npm routing article.

Prefer explicit DOMAIN lines for generativelanguage.googleapis.com before a blunt DOMAIN-SUFFIX,googleapis.com if you also route unrelated Google Cloud APIs through different outbounds. Avoid lazy DOMAIN-KEYWORD,google patterns unless you enjoy debugging accidental matches on unrelated domains.

Proxy-Groups: One Lane or Split API versus Dependencies

The minimal pattern defines a single select or url-test group—call it GEMINI_CLI or reuse GEMINI from your AI Studio profile—and routes all confirmed Google AI suffixes there. That keeps CLI and browser traffic on the same node when you want consistent account behavior.

The finer pattern splits GEMINI_API for low-latency streaming calls from DEPS for npm and large artifact downloads so you can assign a stable node to chat while letting multi-megabyte updates ride a throughput-friendly path. Either approach is valid; the wrong approach is pretending generativelanguage.googleapis.com and registry.npmjs.org deserve identical failover when your nodes mix regions and resellers.

Whatever you choose, every name referenced in rules must exist in proxy-groups. Copy-pasting snippets that reference undefined group labels produces silent confusion until you read Clash validation output. Rename groups to match your working profile, then diff the file like code.

A Practical Rule Block (Conceptual YAML)

The excerpt below is illustrative. Place Gemini-specific lines above wide GEOIP or regional direct rules so first-match semantics work for you. Swap outbound labels to match your config.

# Conceptual excerpt — confirm hostnames in your connection log
proxy-groups:
  - name: GEMINI_API
    type: select
    proxies:
      - NODE-US-WEST
      - NODE-EU
      - DIRECT
  - name: DEPS
    type: select
    proxies:
      - NODE-EU
      - NODE-US-WEST
      - DIRECT

rules:
  - DOMAIN,generativelanguage.googleapis.com,GEMINI_API
  - DOMAIN-SUFFIX,accounts.google.com,GEMINI_API
  - DOMAIN-SUFFIX,oauth2.googleapis.com,GEMINI_API
  - DOMAIN-SUFFIX,ai.google.dev,GEMINI_API
  - DOMAIN-SUFFIX,npmjs.org,DEPS
  - DOMAIN-SUFFIX,npmjs.com,DEPS
  # Add googleapis.com suffix only if logs prove extra subdomains
  # ... GEOIP / MATCH follow ...

If you already maintain a GEMINI group for AI Studio, point the API and OAuth lines there instead of inventing parallel names—just confirm terminal traffic actually reaches Clash before you debug rule content.

OAuth Login versus API Key Validation

OAuth login is a two-legged story in the terminal. The CLI opens or instructs you to open a browser URL on Google account hosts; you sign in; Google redirects through OAuth endpoints; the CLI must complete token exchange over HTTPS paths that may differ from the browser tab’s visible hostname. If only the browser leg is proxied, you get the classic “browser succeeded, CLI still waiting” deadlock.

API key validation is simpler on the surface—usually a direct call to generativelanguage.googleapis.com—but still fails when DOMAIN rules never fire because DNS bypassed Clash or GEOIP sent the flow domestic. Test keys with the same shell and proxy posture you use for gemini, not from a browser extension or unrelated IDE terminal with different env vars.

Some teams mix OAuth for interactive use and API keys in CI. Keep both paths on the same GEMINI_API lane during debugging so you do not chase two different routing bugs at once.

Rule Order, GEOIP, and Shared Infrastructure Traps

The classic footgun is GEOIP,XX,DIRECT above vendor exceptions. Geolocation databases are helpful and imperfect; anycast addresses defeat intuition. When a broad domestic shortcut wins first, you rotate nodes while the CLI still times out. Move Google API lines up until the log shows the outbound you expect.

Shared CDN domains are the second trap. A rule for a huge cloud front door may drag unrelated tooling onto an expensive path—or bypass optimization you relied on elsewhere. When possible, tighten from suffix to exact DOMAIN entries after you read the failing hostname once in the dashboard.

Finally, watch for contradictory duplicates after merging community providers with personal overrides. Two sources quietly disagree; first match wins; you lose an afternoon. Scan for repeated googleapis.com suffixes whenever you integrate a new subscription fragment. If rule vocabulary feels new, read the rule split guide before you chase exotic protocols.

DNS, Fake-IP, and Why Resolver Bypass Breaks DOMAIN Rules

Clash observes names through the resolver path you gave it. Fake-ip modes synthesize short answers so the rule engine can recover domain intent from subsequent connections—until some other stack resolves the same name outside Clash. Operating-system DoH, browser-only DNS, corporate VPN DNS, or Node runtimes that inherit system resolvers inconsistently can desynchronize what you think your YAML says from what actually matches.

The failure looks like cryptographic success in packet captures yet bizarre GEOIP hits in your log. Fix resolver alignment before you rip out half your subscription. That often means turning down competing secure DNS on the OS, pointing tools at Clash’s DNS listener, and validating that TUN includes DNS capture when you rely on it.

Streaming model responses tolerate latency poorly. Long completions sit on warm HTTP connections; a marginal node manifests as “the model went quiet” rather than a neat TLS alert. If you run url-test groups for Gemini lanes, prefer conservative intervals—hyperactive failover that flaps on jitter is worse than a steady mediocre node for interactive coding.

Verification: Reproduce, Log, Then Tune

Use a repeatable micro-checklist after each change:

1. Open your Clash connection or debug pane and filter on googleapis, google.com, and npmjs substrings so noise drops away.
2. From the same shell you use for Gemini CLI, run curl -I https://generativelanguage.googleapis.com and confirm whether the flow lands on GEMINI_API or an unexpected outbound.
3. Run gemini auth login or validate your API key with a minimal prompt that previously failed, and read new log lines immediately.
4. If OAuth is involved, complete the browser step once and verify whether token exchange hostnames differ from the API host; append those suffixes deliberately.
5. Document the working trio: Gemini CLI version, DNS mode, and the exact group names you routed. Paste that note beside your YAML so the next upgrade does not erase tribal knowledge.

When install and auth both fail, bisect: fix npm lanes first, reload the profile, then retry OAuth. When auth succeeds but model calls fail, focus on generativelanguage.googleapis.com and node quality before you widen googleapis.com blindly.

Node Selection and What Routing Cannot Fix

Gemini availability varies by account, region, and product tier in ways no Clash rule file overrides. Your networking job is to make the exit path consistent: hopping between continents every few minutes can surface as quota or policy errors that resemble packet loss.

Routing also cannot invent capacity. Subscriptions expire, regions brown out, and Google-side rate limits still apply even when your YAML is perfect. Stability is honest outbound health, sane MATCH defaults, DNS that tells one consistent story, and expectations that match how streaming clients behave.

Compared with browser-only workarounds, keeping Gemini CLI traffic inside a maintained Mihomo-family profile means the agent rides the same observability and iteration loop as the rest of your network policy—where it belongs if terminal AI is daily work rather than a weekend experiment.

FAQ

The browser works, but Gemini CLI still times out. Why?

Browsers and shells rarely share identical networking stacks. The browser might use OS proxy settings or its own secure DNS, while the CLI opens direct sockets. Until you align proxy variables or enable TUN, Clash may never see those flows, which means your carefully written Clash split Google API rules never execute for Gemini CLI even when they work for Chrome.

Is listing only generativelanguage.googleapis.com sufficient?

Often it is the main piece for model traffic, but OAuth, token refresh, telemetry, and npm updates may introduce additional hosts. Let your log be the authority: reproduce once, read the host column, then add suffixes with comments that explain why they exist.

Can I reuse my AI Studio Clash rules unchanged?

Most Google OAuth and API suffixes overlap, which is a good starting point. The difference is capture: AI Studio in a browser may work under system proxy while Gemini CLI in the same machine’s terminal does not. Copy the domain block, then fix terminal proxy or TUN before you declare victory.

Should I switch to GLOBAL mode to just make it work?

Global modes and careless TUN can hide DNS bugs and break domestic services you still need. Prefer explicit Gemini API and dependency lanes first. Escalate capture breadth only when a specific process refuses respectful proxy settings and you have cleaned up exceptions for sensitive traffic.

Closing Thoughts

In 2026, Gemini CLI is a sharp reminder that free terminal AI agents migrated out of browser tabs and into shells developers live in all day. Clash shines when you stop treating that migration as a footnote. Put Google API traffic, OAuth neighbors, and npm install paths on policy lanes you can name, keep GEOIP shortcuts from stealing first-match wins, and align DNS with your fake-ip story so domain rules stay honest.

Many one-click helpers either tunnel everything—breaking domestic workflows—or ship stale hostname lists that rotted months ago. A maintained rule set with log-backed edits scales better for teams who depend on Gemini CLI during real deadlines.

Clash Official Site focuses on reproducible policy: clear split lanes, Mihomo-friendly examples, and guidance that still makes sense after the next Google endpoint rename. If you want a client build tuned for developer terminal workflows instead of hand-rolled YAML archaeology, you can download Clash Official Site for free and apply the same Gemini-oriented blocks without reinventing infrastructure from scratch.