Why Gemini CLI Stops Working With Clash
Gemini CLI is designed to communicate with Google services from a terminal, so a failure may look different from a normal browser error. The command can appear to hang after you submit a prompt, return a connection timeout, fail during authentication, or repeatedly ask you to sign in again. When Clash is enabled, these symptoms are often caused by traffic being sent through the wrong policy group, DNS requests being resolved outside the tunnel, or a proxy node that cannot maintain long-lived HTTPS connections.
The important point is that Gemini CLI does not use only one simple website address. Authentication, API requests, telemetry, package downloads, and model endpoints may involve different Google domains. A browser test against one page can therefore succeed while the CLI still fails. Clash may send one request through a proxy and another request DIRECT, or a rule may match an unexpected domain before your intended rule is reached.
This guide presents a practical troubleshooting sequence for Windows, macOS, and Linux users running a Clash client with a Mihomo or compatible core. It focuses on diagnosis rather than blindly switching to Global Mode. You will first identify the failure layer, then verify the active mode, DNS behavior, rules, node quality, and terminal environment.
Target Result
Gemini CLI should complete authentication, reach the selected model endpoint, and return a response without repeated timeouts or unexplained connection resets.
1Identify Whether the Problem Is Proxy, DNS, or Authentication
Start by recording the exact command and error message instead of changing several settings at once. A timeout usually indicates that the request cannot establish or maintain a connection. An authentication error may mean that the browser callback was interrupted, the account session expired, or the CLI is reaching a service through an IP address that is challenged or blocked. A certificate error points more strongly toward TLS interception, incorrect system time, or a network security product.
Run a basic connectivity test with the same terminal environment that launches Gemini CLI. For example, use curl to inspect headers from a Google endpoint:
A response such as 200, 301, or 302 confirms that the endpoint is reachable, although it does not prove that the API request will succeed. A timeout from both commands suggests a general proxy or DNS issue. If accounts.google.com works but generativelanguage.googleapis.com fails, inspect domain rules, node access, and API-specific filtering.
Also check whether the terminal is using the proxy that Clash exposes. GUI applications and command-line programs do not always share the same settings. A browser may use the system proxy automatically, while a terminal process may ignore it completely. Depending on your client, verify the HTTP and SOCKS mixed-port values, then temporarily set the standard environment variables:
On Windows PowerShell, the equivalent test is:
Diagnostic Principle
Change one layer at a time. First prove that the terminal reaches Google, then test authentication, and only afterward adjust model or account settings.
2Correct Clash Mode and Google Service Rules
Clash can operate in Rule, Global, or Direct mode, depending on the client. Rule mode is usually the best permanent choice because it lets ordinary local traffic remain DIRECT while sending selected services through a proxy. However, a missing or incorrectly ordered rule can send Gemini CLI traffic directly to an unreachable route. Global Mode is useful as a short diagnostic test, but it is not automatically the best final configuration.
In your active profile, confirm that the policy group selected for Google traffic contains a working node. Do not assume that a group name such as Proxy, AI, or Foreign points to a healthy server. Open the connection or proxy page, test several nodes, and select one with acceptable latency and stable HTTPS access.
Rules are evaluated from top to bottom. Place specific domain rules before broad rules such as GEOIP, GEOSITE, or a final MATCH. A practical starting point for a Mihomo-compatible profile may look like this:
Replace AI with the actual proxy group name in your profile. The exact domain list can vary as Gemini CLI changes its authentication and API implementation, so inspect the Clash connection log while starting the command. If a Google request appears with a DIRECT policy when it should be proxied, add a narrowly scoped rule. If a request is repeatedly rejected by an overly broad reject rule, move the Google rule above it.
After editing a profile, reload the configuration and confirm that the new profile is active. Many desktop clients keep an edited copy separate from the subscribed profile. If you update the wrong file, the interface may show your changes briefly but overwrite them at the next subscription refresh.
| Test mode | What it tells you | Recommended use |
|---|---|---|
| Direct | Whether the local network can reach Gemini services without Clash routing | Short baseline test only |
| Global | Whether a selected node can carry most traffic successfully | Temporary diagnosis |
| Rule | Whether domain matching and policy order are correct | Preferred long-term mode |
3Hands-On Fix: Test the Active Route Step by Step
Use the following controlled procedure when Gemini CLI hangs or reports a timeout. The goal is to create a small amount of evidence at every step. Keep the Clash connection log visible so that you can compare the terminal command with the domains and policies recorded by the core.
- Exit Gemini CLI completely. If a previous process is still running, terminate it so that an old authentication or network session does not remain in memory.
- Open Clash and select a known working node. Avoid a node marked unavailable, overloaded, or associated with repeated packet loss.
- Switch temporarily to Global Mode and run the two
curlcommands from the previous section. Watch the connection log and confirm that the requests use the expected proxy group. - If both endpoints respond, switch back to Rule Mode and repeat the tests. Compare the log entries. A difference between Global and Rule Mode usually indicates a rule-order or domain-matching problem.
- Set the terminal proxy variables, start Gemini CLI again, and complete authentication in the same user account and terminal session. Do not mix a browser running DIRECT with a CLI process using a different exit IP during the callback.
When the command still waits indefinitely, reduce the test to one endpoint and one node. Try two or three nodes from different regions. If one node works consistently while others fail, the profile is probably valid and the problem is node quality, IP reputation, upstream filtering, or congestion. If every node fails only in Rule Mode, focus on rules and DNS rather than replacing the entire subscription.
Do Not Keep Global Mode as a Blind Fix
Global Mode can conceal an unmatched rule by forcing unrelated traffic through the proxy. Use it to isolate the cause, then create a precise Rule Mode solution that is easier to maintain and less likely to disrupt local services.
4Resolve DNS, IPv6, and TLS Problems
DNS is a frequent reason for an apparent Gemini CLI timeout. Clash may proxy the HTTPS connection while the operating system resolves the hostname through a local DNS server. The returned address can be incorrect, regionally filtered, unreachable over IPv6, or inconsistent with the route selected by Clash. A clean browser result does not eliminate this possibility because browsers may use their own secure DNS implementation.
For testing, ensure that the active profile enables Clash DNS and uses a predictable mode. A typical Mihomo configuration is:
This is a diagnostic baseline, not a universal profile. Some networks block DNS-over-HTTPS, some clients use different field names, and some subscriptions overwrite DNS settings. If encrypted DNS fails completely, test with a normal resolver that your network can reach, then return to a secure resolver after identifying the restriction.
Fake-IP mode can improve consistency because Clash intercepts hostname resolution and maps domains to an internal address. However, applications that require real IP responses may need entries in fake-ip-filter. If Gemini CLI behaves worse after enabling Fake-IP, inspect the connection log and test Redir-Host mode. Clear the client DNS cache and restart the CLI after switching modes.
IPv6 is another useful isolation step. If your ISP provides broken IPv6 connectivity, the CLI may prefer an IPv6 address and wait until the connection times out before falling back. Temporarily setting ipv6: false in Clash and disabling IPv6 in the operating system can confirm whether this is the cause. Also check that your computer clock is correct; substantial time drift can produce TLS certificate failures that appear as authentication problems.
5Choose a Stable Node for Long-Lived API Sessions
Gemini CLI needs more than a fast speed-test result. AI requests can keep an HTTPS connection open while the service processes a response, and authentication may involve redirects or multiple sequential requests. A node with low average ping but frequent packet loss can therefore perform worse than a slightly slower node with stable TCP and TLS behavior.
When comparing nodes, check the following characteristics:
- Stable latency: Look for a consistent result rather than a single low ping. Large variation indicates congestion or an unstable route.
- Low packet loss: Even a small amount of loss can cause repeated retransmissions and make a CLI request appear frozen.
- Reliable HTTPS: Test Google endpoints, not only the provider's latency checker. A node may respond to ICMP while HTTPS is filtered or overloaded.
- Reasonable IP reputation: Shared or abused addresses may trigger extra verification, rate limits, or temporary blocks.
- Correct region: Keep the exit region compatible with your account, service availability, and provider policy. Frequent region changes can invalidate sessions.
For a reliable setup, create a dedicated policy group for AI services instead of placing Gemini traffic in a group that is also used for video, downloads, and large file transfers. A dedicated group makes node changes visible and prevents bandwidth-heavy applications from interrupting an interactive CLI session.
Pro Tip: Test Persistence, Not Just Speed
Run several small requests over five to ten minutes. A node that succeeds once but fails during the second or third request is not a stable solution for Gemini CLI.
6Repair Authentication and Terminal Environment Issues
If API connectivity works but sign-in fails, inspect the authentication flow separately. Gemini CLI may open a browser for authorization and then wait for a local callback. A firewall, port conflict, restrictive browser extension, or mismatch between the browser's network route and the terminal's route can interrupt that callback. Temporarily disable extensions that block redirects, allow the CLI through the local firewall, and ensure that the browser and terminal use the same Clash policy when authentication begins.
Do not expose access tokens in screenshots, shell history, support tickets, or Clash logs. If you believe a token has been copied or leaked, revoke it through the relevant account or developer console and authenticate again. Avoid placing long-lived credentials directly in a shared YAML profile.
Check the runtime environment as well. An outdated Node.js installation, broken certificate store, or incompatible package version can produce errors that look like network failures. Confirm the executable being used:
On Windows PowerShell, use Get-Command gemini to verify the path. If multiple installations exist, the shell may launch an old version with different proxy behavior. Update the CLI through its documented package manager, restart the terminal, and repeat the connectivity test after the update.
Finally, remove temporary proxy variables if they point to an old port or a stopped Clash process. A stale HTTP_PROXY value can override the current system setting and make every new test misleading. Confirm the active values before each run and keep only one deliberate proxy method enabled while diagnosing.
7Final Verification Checklist
Once Gemini CLI returns a response, perform a second verification rather than assuming the issue is permanently solved. Reload the profile, restart Clash, and run the command again. This catches configurations that worked only because of a temporary node selection or an in-memory DNS cache.
- The Clash core is running and the selected profile is active.
- The terminal uses the intended HTTP, SOCKS, or mixed port.
- Google authentication and API domains match the expected proxy rules.
- Specific rules appear above broad fallback rules.
- Clash DNS is enabled, and unwanted local DNS or IPv6 paths are excluded.
- The selected node maintains stable HTTPS connections and is not overloaded.
- The browser callback and terminal request use a compatible route and exit IP.
- No credentials or access tokens have been written into public logs or shared profiles.
Most Gemini CLI failures behind Clash are not caused by the command itself. They result from a mismatch between the application, terminal proxy variables, Clash rules, DNS mode, and node behavior. By testing each layer independently, you can replace guesswork with a repeatable fix. Keep the final configuration narrow, document the working policy group and port, and retest after subscription updates or core upgrades.