Why Gemini CLI behaves differently behind Clash
Gemini CLI can look like a single command, but its first-run workflow usually involves several independent network conversations. The package manager may contact registry.npmjs.org and CDN endpoints before the command starts. The login flow can open a browser, communicate with Google identity services, wait for a local callback, and then exchange authorization data with account or token endpoints. Once authentication succeeds, model requests may use different Google API hostnames, regional front doors, streaming connections, telemetry services, or project metadata endpoints. A browser tab that loads Google AI successfully therefore does not prove that every connection required by Gemini CLI follows the same route.
Clash evaluates outbound connections according to hostname rules, resolver results, process behavior, and the active proxy mode. A rule that sends one Google suffix to a proxy group does not automatically cover every related service, and a rule that works for ordinary HTTPS requests may still fail for a long-lived streaming connection. If npm uses one path, the browser uses another, and the CLI uses a third because its runtime ignores system proxy settings, the visible symptom may simply be “timeout,” “network error,” or an authentication spinner that never completes.
The most useful troubleshooting habit is to stop treating Gemini CLI as one indivisible application. Separate the incident into package installation, name resolution, browser authentication, token exchange, API access, and streaming behavior. Test each layer with a controlled configuration, record which Clash policy group handled it, and change only one variable at a time. This approach is slower than switching random nodes, but it turns an ambiguous timeout into a transport problem that can be reproduced and fixed.
Identify the exact stage that fails
Begin with a clean terminal session and note the precise command, elapsed time, and error text. A failure during npm install belongs to the package-download stage; a failure after a browser window opens belongs to the authentication stage; a request that starts but stops while generating output points toward API routing, idle timeouts, or streaming transport. These distinctions matter because applying a DNS change to an OAuth callback problem will not improve the result, while replacing a node cannot repair a CLI process that never uses the proxy.
If installation fails, inspect whether the registry hostname resolves and whether Clash records a connection attempt. A command such as npm config get registry confirms which registry npm is using, while the verbose output from npm install --verbose can reveal whether the delay occurs during metadata retrieval, tarball download, or certificate negotiation. Do not assume that a successful browser visit to the npm website validates the registry API. The browser may use cached data, a different resolver, or a different policy group.
If login fails, watch the sequence rather than focusing only on the first browser page. The browser may display a successful consent screen while the CLI waits for a callback on localhost, or the callback may arrive but the subsequent token exchange may stall. Confirm that no second VPN, endpoint security product, browser isolation layer, or stale proxy variable is intercepting the loopback step. A local callback should normally remain local; sending it through a remote proxy can create confusing redirects and rejected state parameters.
For model requests, distinguish a connection timeout from a read timeout. A connection timeout means that the TCP or TLS session could not be established. A read timeout means that the session opened but no expected response arrived within the client’s waiting period. A streaming request may produce headers quickly and then pause while the client waits for the next event. Clash logs, request duration, and the selected policy group are more valuable here than the generic phrase “Gemini is offline.”
- Install timeout: check npm registry routing, package mirrors, and terminal proxy inheritance.
- Sign-in loop: check browser routing, callback handling, system clock, and identity-service access.
- API timeout: check Google API rules, node health, TLS negotiation, and project configuration.
- Streaming stall: check long-lived connections, idle timers, unstable nodes, and competing tunnels.
Check Clash mode, listeners, and rule ordering
Confirm the active Clash mode before editing YAML. In Rule mode, Gemini traffic depends on the rule graph and the final MATCH behavior. In Global mode, the selected proxy group becomes a useful baseline because it removes most domain-specific ambiguity. In Direct mode, the result tells you whether the local network can reach the service without a proxy, but it should not be mistaken for proof that the CLI is correctly integrated with Clash.
For a first comparison, select one known-working node or a small selector group rather than an automated group containing dozens of uncertain endpoints. Automated url-test and fallback groups are useful after the baseline works, but they can make diagnosis noisy when probes succeed while Google API streaming fails. A node that answers a short latency probe is not necessarily suitable for authentication redirects or a long-running response. Keep the test path stable long enough to observe a complete login or model request.
Examine the rule decision for every hostname shown in the Clash connection panel. Do not rely on a single broad rule such as DOMAIN-SUFFIX,googleapis.com,PROXY without checking whether the actual request uses another Google-owned suffix, an identity provider, a regional endpoint, or a package CDN. At the same time, avoid adding a huge list of guessed domains. Overbroad rules can route unrelated services through an unsuitable group and make future failures harder to interpret.
Rule order is decisive. A narrow vendor rule must appear above a general Google, country, or catch-all rule if you intend it to use a specific policy. A remote rule provider can also change behavior after an update, so record the provider version and inspect the matched rule during an incident. If a connection is marked DIRECT unexpectedly, test the exact domain in the Clash dashboard and then review suffix, keyword, geosite, and final-match interactions rather than repeatedly refreshing the profile.
Verify the local listener as well. A typical mixed port accepts both HTTP and SOCKS-style traffic, but the actual port depends on your profile. Check that no other application has claimed it, that the listener binds to the address your terminal can reach, and that authentication settings are consistent. A browser extension may use one port while Gemini CLI uses another. If the dashboard shows no request when the command is running, investigate process proxy configuration before changing rules or nodes.
Troubleshoot DNS, fake-IP behavior, and TLS
DNS problems often masquerade as proxy failures. If the terminal resolves a hostname through the operating system while Clash resolves it through a different resolver, the two tests may reach different addresses or different policy decisions. This is especially confusing when a browser uses secure DNS, the CLI uses libc resolution, and Clash operates in a fake-IP or redirection mode. Capture the hostname, resolved address or fake-IP mapping, and matched rule for the same request whenever possible.
As a controlled test, compare normal DNS mode with fake-IP mode without changing several unrelated settings at once. If ordinary DNS works while fake-IP fails, inspect the fake-IP filter, reserved ranges, excluded domains, and applications that do not handle synthetic addresses correctly. If fake-IP works while ordinary DNS fails, check whether the local resolver, captive portal, ISP response, or security software is interfering. The goal is not to declare one mode universally superior; it is to identify which resolver path Gemini CLI can use consistently.
Flush stale caches only after recording the current behavior. On Windows, a system DNS cache may survive profile changes; on macOS, resolver state can also be influenced by active interfaces and VPN extensions. Restarting the terminal alone does not always clear every layer. A clean test should include a new Clash connection, a newly opened shell, and a direct observation of the request in the dashboard. If a hostname repeatedly maps to an old address, inspect both the local cache and Clash’s internal host or fake-IP database.
TLS errors require a different line of inquiry. Verify that the system date and time are accurate, because expired or not-yet-valid certificates can cause immediate failures. Check whether an enterprise proxy or antivirus product is performing HTTPS inspection, and confirm that its trust certificate is installed only where your organization authorizes it. Do not disable certificate verification as a shortcut. A command that succeeds after verification is disabled has not demonstrated a healthy connection; it has only hidden a trust problem.
Also test whether the selected node supports the connection pattern Gemini CLI needs. Some exits handle short HTTPS requests but reset long-lived sessions, reject certain TLS fingerprints, or become unstable when several streams share the same route. Compare two or three reputable nodes using the same Clash group and the same command. Record connection duration, response behavior, and reset timing. “Fast” should mean stable enough to complete the workflow, not merely a low probe number.
Configure terminal variables and verify process inheritance
A common mistake is assuming that enabling Clash’s system proxy automatically configures every command-line program. Many terminals, package managers, Node processes, and native helpers use their own settings. Inspect the variables visible to the actual shell that launches Gemini CLI. Depending on the client and operating system, relevant names may include HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, and their lowercase equivalents. A SOCKS listener and an HTTP mixed listener are not interchangeable unless the application supports the selected protocol.
Use a harmless test request before launching the full CLI. For example, send a request through the intended HTTP listener with a tool that clearly reports the proxy connection, then compare it with a request made without proxy variables. The Clash dashboard should show the test hostname and the expected policy group. If the command succeeds but the dashboard remains empty, the request probably bypassed Clash or used a different network layer. If the dashboard records the request but the CLI still fails, move on to rules, DNS, TLS, or application-specific behavior.
Be careful with variable syntax and shell scope. A variable exported in one terminal tab may not exist in a new tab, a graphical launcher, an IDE-integrated terminal, or a subprocess started by a package manager. On Windows, user and system environment variables can disagree, while PowerShell and older command shells may display or persist them differently. On Unix-like systems, shell startup files can overwrite values during login. Print the effective values immediately before testing, and remove obsolete proxy variables that point to a closed port.
Some runtimes honor only a subset of conventional variables, and some libraries require explicit proxy-agent support. Gemini CLI may also launch a browser or helper process whose network settings are separate from the parent process. Therefore, test the terminal request, the browser login, and the final model request as three related but independent clients. If the CLI’s traffic never appears in Clash while a manual request does, consult the CLI’s documented proxy options and runtime requirements instead of forcing unrelated environment variables.
# Example diagnostic sequence; replace the port with your active Clash listener
echo $HTTPS_PROXY
echo $ALL_PROXY
npm config get proxy
npm config get https-proxy
curl -I --proxy http://127.0.0.1:7890 https://example.com
Treat commands like these as diagnostics, not universal configuration instructions. Keep secrets, access tokens, and subscription URLs out of copied logs. After testing, clear temporary variables when working on a shared machine, especially if they contain credentials or route sensitive traffic through a personal proxy. A reliable configuration is one you can explain, reproduce, and remove safely.
Use TUN mode only when application proxying is insufficient
TUN mode captures traffic at the virtual network interface layer, which can help when Gemini CLI or one of its helper processes ignores HTTP and SOCKS environment variables. It may also cover libraries that open sockets directly rather than using a high-level proxy-aware client. However, TUN introduces additional variables: virtual adapter permissions, route priority, DNS hijacking, IPv6 behavior, exclusions, and conflicts with other VPN software. Enabling it should be a deliberate experiment, not the first response to every timeout.
Before enabling TUN, establish a working baseline through the local listener if possible. Note the active node, rule mode, DNS mode, and command result. Then enable TUN with the smallest practical scope, confirm that the virtual adapter is running, and repeat the same command. If the result changes, inspect whether the Gemini process now appears in Clash and whether DNS requests are handled by the intended resolver. If nothing changes and no connection appears, the issue may be outside routing, such as an invalid project, expired login state, or a local callback problem.
TUN can also expose problems that ordinary proxy mode hides. A broad route may capture local services, development containers, package registries, or corporate endpoints that should remain direct. DNS hijacking may cause a browser and a terminal to receive different answers. IPv6 may choose a path that your selected node or local network cannot complete. Temporarily constrain the test, disable competing tunnels, and preserve a rollback path. If the command works only with an aggressive TUN configuration, refine exclusions rather than leaving a fragile global tunnel in place.
Test nodes methodically. Start with a fixed selector and one node, then run the same authentication or model command twice. Switch only the node and repeat. Compare the dashboard’s matched rules, DNS result, handshake timing, and whether the stream remains open. If every node fails at the same hostname, suspect routing, credentials, DNS, or application behavior. If only one node fails, classify it as an exit-quality problem and remove it from the normal group rather than rewriting the entire rule set.
Frequently asked questions
Why does Gemini work in my browser but Gemini CLI times out?
The browser may use a system proxy, a secure DNS provider, cached authentication, or an extension that the terminal does not share. Gemini CLI may also use different API hosts and may ignore the browser’s proxy configuration entirely. Compare the browser’s Clash connection entries with the CLI’s entries, then test the CLI through the intended listener or TUN mode. A successful browser login proves only that the browser completed its own network path.
Is enabling Clash system proxy enough for Gemini CLI?
Not always. Some command-line runtimes honor system proxy settings, while others require environment variables or an application-specific proxy option. Check whether the process generates a Clash connection. If it does not, configure the supported proxy mechanism for that CLI and verify the effective values in the same terminal that launches it. Avoid assuming that an IDE terminal, a graphical launcher, and a normal shell inherit identical settings.
Should I use fake-IP or redir-host for Gemini CLI?
Neither mode is universally correct. Fake-IP can provide consistent policy handling when applications cooperate with Clash’s DNS design, while redir-host can be easier to reason about during some DNS and certificate investigations. Test one mode at a time, inspect the actual resolution path, and keep the mode that completes installation, login, and model requests consistently. If changing DNS mode alters the result, investigate filters and resolver differences instead of treating the change as a random fix.
When should I increase the CLI timeout?
Increase a timeout only after confirming that the request reaches the intended policy group and that the node remains stable. A longer timeout can help with a slow but healthy route, but it cannot repair a blocked hostname, failed DNS lookup, invalid certificate, or process that bypasses Clash. Capture connection and read timing first, then adjust the smallest relevant setting while keeping the same node and rule set for comparison.
Compared with browser-only proxy extensions, which may leave terminal processes untouched, and generic VPN clients, which often provide less visibility into matched domains and policy decisions, Clash V.CORE gives Gemini CLI troubleshooting a clearer control surface: explicit rule ordering, observable connections, selectable nodes, flexible DNS modes, and optional TUN capture when environment variables are not enough. Once you have identified the failing stage, those controls are more useful than repeatedly reinstalling Gemini CLI or rotating credentials. If you want a maintained client with this level of routing and diagnostic visibility, visit the Clash V.CORE download page and choose the package appropriate for your system.