Gemini CLI Timeout in Clash? Fix Access and Proxy Issues

When Gemini CLI reports a timeout while Clash is running, the subscription is not automatically the problem. In many cases, the request is reaching the wrong proxy group, matching a direct or reject rule, resolving through an unreliable DNS path, or bypassing Clash entirely because the terminal is not using the expected proxy environment variables. Gemini CLI can also behave differently from a browser: a browser may use the system proxy or Clash's TUN interface, while a command-line process may connect directly. This guide explains how to diagnose a Gemini CLI timeout in Clash methodically, test the real access path, correct proxy and TUN settings, and verify the final configuration before replacing your subscription.

Understand What a Gemini CLI Timeout Means

A timeout is a symptom, not a single diagnosis. Gemini CLI may need to contact several Google or Google Cloud endpoints for authentication, API requests, telemetry, package access, and service discovery. If only one of those domains is blocked or routed incorrectly, the command can appear to hang even though the selected proxy node passes a basic latency test.

The first useful distinction is between a connection timeout, a TLS or certificate error, an authentication failure, and an API response error. A connection timeout usually means that the TCP connection or TLS handshake never completed. A certificate error indicates that the connection reached a server but the TLS path was altered, intercepted, or configured incorrectly. A response such as 401, 403, or a quota message means that networking is probably working and the problem has moved to credentials or account access.

Immediate timeout: commonly caused by an unreachable node, incorrect proxy port, blocked destination, or a process that is not using Clash.
Long pause followed by an error: often points to DNS fallback, an IPv6 route that cannot connect, or a proxy group retrying several unhealthy nodes.
Browser works but Gemini CLI fails: usually indicates different proxy inheritance, missing environment variables, or a TUN mode issue.
Login opens but API calls fail: check the exact service domain, rule matching, account permissions, and whether the CLI uses a different endpoint after authentication.
Only one node fails: do not immediately edit DNS or rules; first compare the same request through another node.

Start with one controlled test: keep the same Gemini CLI command, the same Clash profile, and the same terminal session while changing only the proxy node. Changing multiple variables at once makes it difficult to identify the actual cause.

Test the Clash Node and Endpoint Separately

Before changing routing rules, confirm that Clash itself can establish a usable connection. A green proxy status or a successful latency check does not prove that every destination works. Latency tests often use a lightweight URL, while Gemini CLI may connect to a different domain and require a complete HTTPS handshake.

Open the Clash dashboard and inspect the active proxy group. Select a known-good node manually instead of leaving the group on an automatic selector during the first diagnosis. Then test the node with the dashboard's delay function or a reliable HTTPS test URL. If every node fails, focus on the local listener, system network, DNS, or subscription validity. If only some nodes fail, the issue is more likely regional reachability, server congestion, or protocol compatibility.

You can also test the local HTTP proxy from a terminal. Replace 7890 with the HTTP mixed-port configured by your Clash client:

Test an HTTPS Request Through Clash

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

The verbose output is useful because it shows whether the request connects to 127.0.0.1:7890, whether Clash creates a tunnel with the CONNECT method, and whether the TLS handshake completes. A 401 or 404 response can still be a positive networking result: it proves that the endpoint answered. A connection refusal means that the local port is wrong or Clash is not listening. A timeout after the local proxy accepts the connection points more strongly to the selected node, routing, DNS, or remote access path.

To test DNS independently, query the hostname through a resolver that you trust and compare it with the result obtained while Clash DNS is enabled. Do not treat a successful ping as proof of HTTPS access. ICMP may be blocked, and many cloud services do not respond to ping at all. The more meaningful test is a proxied HTTPS request to the actual service domain.

Clash's connection log is equally important. Start the Gemini CLI command, then search the log for domains that appear at the time of the timeout. Record the following details:

The destination hostname, including any Google or Google Cloud subdomain.
The rule that matched the request, such as DIRECT, REJECT, or a named proxy group.
The final node selected by the proxy group.
Whether the request was classified as TCP, UDP, or a DNS query.
Whether the connection repeatedly retries or fails only once.

Verify That Gemini CLI Uses the Proxy

The most common mistake in command-line troubleshooting is assuming that a system proxy automatically applies to every process. Some desktop applications read operating-system proxy settings, but many terminal programs use the environment variables HTTP_PROXY, HTTPS_PROXY, and ALL_PROXY. Gemini CLI may also inherit settings from the shell, its package manager, or a separate runtime configuration.

For an HTTP or mixed Clash port, set the proxy variables for the current shell and then launch Gemini CLI from that same shell:

Linux and macOS Shell Proxy Variables

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=http://127.0.0.1:7890

gemini

For PowerShell, use the following form:

Windows PowerShell Proxy Variables

$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:ALL_PROXY="http://127.0.0.1:7890"

gemini

Use the exact port shown in Clash. A common configuration has a dedicated HTTP port, a SOCKS port, and a mixed port. An HTTP proxy URL cannot be substituted blindly for a SOCKS listener. If your Clash client exposes a SOCKS5 port, use a SOCKS-compatible URL such as socks5://127.0.0.1:7891, but verify that the specific CLI runtime supports SOCKS proxy variables. The mixed port is often the simplest option because it accepts both HTTP proxy requests and SOCKS5 connections.

Check that the variables are actually present:

Confirm the Active Proxy Environment

echo $HTTP_PROXY
echo $HTTPS_PROXY
echo $ALL_PROXY

# PowerShell
Get-ChildItem Env:HTTP_PROXY,Env:HTTPS_PROXY,Env:ALL_PROXY

Some applications honor lowercase names while others inspect uppercase names. For maximum compatibility on Unix-like systems, you can define both forms:

Set Uppercase and Lowercase Variables

export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export all_proxy=http://127.0.0.1:7890

Do not mix proxy schemes casually: if the shell points to a SOCKS port but the program expects an HTTP proxy, the command may fail with a timeout that looks like a remote node problem. Confirm the listener type and test it with curl before debugging Gemini CLI itself.

Fix Routing Rules and Proxy Groups

Once you know that Gemini CLI is reaching Clash, inspect the rule decision. A broad GEOIP,CN,DIRECT rule, an overly aggressive direct rule, or a provider list that contains Google-related domains can send the request outside the intended proxy. Conversely, a global reject rule can silently block a hostname and produce a client-side timeout.

Use the dashboard connection view while running the command. If the destination is shown as DIRECT, temporarily select a global proxy mode or add a narrow test rule. A short-term test rule is safer than rewriting the whole configuration:

Temporary Domain Routing Test

rules:
  - DOMAIN-SUFFIX,googleapis.com,PROXY
  - DOMAIN-SUFFIX,google.com,PROXY
  - DOMAIN-SUFFIX,generativelanguage.googleapis.com,PROXY
  - MATCH,DIRECT

The group name must match a real proxy group in your configuration. If your group is called Auto, 🚀 Proxy, or Gemini, replace PROXY with that exact name. YAML values containing special characters should be quoted when necessary.

Do not assume that one visible hostname represents the entire request flow. Authentication redirects, API endpoints, certificate checks, and supporting services can use different domains. Watch the connection log during login and during an actual prompt submission. If the first request succeeds but the second request is direct or rejected, create rules for the missing domain rather than only the initial login hostname.

For a more stable long-term configuration, put service-specific rules above broad geographic or catch-all rules. Rule order matters: Clash normally uses the first matching rule. A provider rule placed before your explicit Gemini rules may capture the domain unexpectedly. When troubleshooting, simplify the rule chain temporarily, confirm the result, and then restore provider-based rules one section at a time.

Configure DNS and TUN Mode Carefully

DNS problems can make a healthy proxy appear broken. If the operating system resolves a service hostname through an unreliable local resolver, Clash may receive an incorrect address or may route the connection according to an IP rule instead of the original domain. This is especially noticeable when a browser works through a browser extension but a command-line tool fails through a different DNS path.

For modern Clash-compatible cores such as Mihomo, fake-ip is often a practical choice when TUN mode is enabled. It allows Clash to preserve the original domain and apply domain rules before relying on a real destination IP. A conservative example is:

DNS and TUN Baseline

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - https://1.1.1.1/dns-query
    - https://dns.google/dns-query
  fallback:
    - https://1.0.0.1/dns-query
    - https://8.8.8.8/dns-query
  fallback-filter:
    geoip: true

tun:
  enable: true
  stack: system
  auto-route: true
  auto-detect-interface: true

Exact fields differ between Clash variants and clients, so treat this as a baseline rather than a universal drop-in configuration. If the core rejects a field, check its documentation and version. A configuration intended for Mihomo may not be accepted by an older Clash build.

TUN mode is useful when Gemini CLI does not honor proxy environment variables. It captures system traffic at the network layer and can route applications that have no proxy support. However, TUN introduces its own failure modes: missing administrator permission, an incompatible network stack, incorrect auto-route behavior, VPN conflicts, or a DNS mode that the operating system cannot use correctly.

Use one method at a time while testing. First test explicit proxy variables with TUN disabled. Then test TUN with the variables removed. If both work individually but fail together, you may have a loop or conflicting route. Also check whether another VPN, corporate security agent, virtual machine adapter, or endpoint firewall is intercepting traffic before it reaches Clash.

Practical TUN rule: enable TUN when the application cannot be configured with a proxy, not merely because it is available. For a CLI that works reliably with HTTPS_PROXY, explicit proxying is easier to inspect and less likely to create routing conflicts.

Check IPv6, TLS, and Local Network Conflicts

Some timeout cases are caused by a broken IPv6 path. The hostname resolves to both IPv4 and IPv6, the client prefers IPv6, and the selected node or local network cannot complete the IPv6 connection. A browser may quickly fall back to IPv4, while a command-line runtime may wait longer before retrying. As a diagnostic step, compare IPv4 and IPv6 requests:

Compare IPv4 and IPv6 Connectivity

curl -4 -v -x http://127.0.0.1:7890 https://generativelanguage.googleapis.com/
curl -6 -v -x http://127.0.0.1:7890 https://generativelanguage.googleapis.com/

If IPv4 succeeds and IPv6 consistently hangs, temporarily disable IPv6 preference in the Clash client or operating system for testing. Do not permanently disable a protocol without understanding the network environment; the important point is to confirm whether address-family selection is responsible.

TLS inspection can create a different class of error. Avoid installing random certificates or disabling certificate validation just to make Gemini CLI connect. A proxy should not require insecure TLS workarounds for an ordinary HTTPS request. Verify the system clock, update the CLI runtime, and check whether a corporate proxy is performing TLS interception. A clock that is several minutes off can cause certificate validation or authentication failures that resemble access problems.

Local security software may also block a newly installed CLI runtime while allowing browsers. Check firewall prompts and outbound application rules. If the process runs inside WSL, a container, or a remote SSH session, remember that 127.0.0.1 refers to that environment, not necessarily the host where Clash is running. In those cases, the CLI may need the host gateway address, and Clash may need to listen on a LAN-accessible address with appropriate firewall protection.

Final Diagnostic Checklist Before Replacing the Subscription

After making a change, restart only the component that needs restarting and repeat the same controlled test. Avoid importing a new subscription immediately, because a new profile can hide the original issue while introducing different rules, DNS settings, or ports. Work through this checklist:

Confirm Clash is running and note the actual HTTP, SOCKS, or mixed port.
Test a known HTTPS endpoint through the local proxy with curl -v.
Select one node manually and test the real Google or Google Cloud endpoint.
Check the Clash connection log for the exact hostname used by Gemini CLI.
Verify that the request is assigned to the intended proxy group rather than DIRECT or REJECT.
Set proxy environment variables in the same shell that launches Gemini CLI.
Test explicit proxying and TUN mode separately to avoid route loops.
Compare IPv4 and IPv6 behavior if the failure is slow or inconsistent.
Check system time, certificate errors, firewall permissions, and container or WSL networking.
Only after these tests fail across multiple healthy nodes should you investigate subscription expiry, server-side restrictions, or provider quality.

A useful result matrix can make the conclusion clear:

Test Result	Most Likely Cause	Next Action
Local proxy refuses connection	Wrong port or Clash stopped	Check listener settings and restart Clash
Browser works, CLI fails	Missing environment proxy or unsupported scheme	Set and verify proxy variables
All nodes fail for one domain	Rule, DNS, or destination access issue	Inspect logs and add a narrow proxy rule
One node fails, others work	Node congestion or regional reachability	Remove the node from the active group
IPv4 works, IPv6 hangs	Broken IPv6 path	Prefer IPv4 temporarily and retest
Endpoint returns an HTTP error	Networking succeeded; account or API issue	Review credentials, permissions, and quotas

FAQ: Gemini CLI and Clash Timeouts

Why does Gemini CLI fail when the browser works?

Browsers commonly inherit the operating-system proxy, a browser extension, or TUN routing. A terminal process may ignore all of those settings and connect directly. Set HTTP_PROXY, HTTPS_PROXY, and, when supported, ALL_PROXY in the same shell that starts Gemini CLI. Then confirm the path with curl and the Clash connection log.

Which Clash port should I use?

Use the HTTP listener for HTTP proxy variables, the SOCKS listener for SOCKS-compatible clients, or the mixed port when you want one endpoint that supports both common proxy styles. Do not guess from a standard port number. Open Clash's settings and copy the actual port, then verify it with a proxied curl request.

Should I enable TUN mode to fix the timeout?

Enable TUN when the CLI cannot use explicit proxy settings or when it must capture applications that do not support proxies. If Gemini CLI already works with environment variables, explicit proxying is usually easier to troubleshoot. Test TUN separately, because running it alongside another VPN or a conflicting route can create new failures.

When should I replace the subscription?

Consider replacing or contacting the provider only after the local proxy port, CLI proxy inheritance, rules, DNS, IPv4 or IPv6 behavior, and several nodes have been tested. If every node fails while unrelated HTTPS destinations work, the provider or destination compatibility may be responsible. If only Gemini CLI fails, the cause is more likely local configuration than subscription quality.

Once the request appears in Clash, matches the intended proxy rule, completes the TLS handshake, and returns an account-level response instead of timing out, the networking problem is solved. Keep the working node and rule selection documented, then re-enable automatic groups or broader rule providers gradually. This approach preserves a known-good baseline and prevents another Gemini CLI timeout from being mistaken for a failed subscription.