Fix Gemini CLI Connection Timeouts With Clash: 2026 Guide

Why Gemini CLI Timeouts Happen

Gemini CLI is a terminal application, but its network behavior is not identical to a browser. A browser usually follows the operating system's HTTP proxy setting, while a command-line program may rely on environment variables, its own HTTP library, or a system-level tunnel. This is why opening Google in a browser can work perfectly while a Gemini CLI request waits until it fails with a timeout.

The request normally travels through several stages. Gemini CLI first creates an HTTPS connection to a Google API endpoint, the operating system resolves the endpoint's hostname, the connection is handed to the proxy layer if one is configured, and Clash then applies a rule to the destination. A failure at any stage can look like the same generic error. The client may report a timeout even though the real cause is a stale proxy port, a direct DNS lookup, an unsuitable routing rule, an unreachable IPv6 address, or a node that cannot establish a stable TLS connection.

There are also two different timeout patterns worth separating. If the command fails immediately with “connection refused,” the local Clash port is probably wrong or Clash is not listening. If it waits for tens of seconds and then reports a timeout, the local port may be reachable but the request is not completing beyond Clash. If the request reaches the API and returns an HTTP error such as 401, 403, or 429, proxy connectivity is working and the problem is authentication, quota, or account policy rather than routing.

Classify the Error Before Changing Settings

Start with one reproducible command and record the exact output. Avoid changing the profile, node, DNS mode, and terminal variables all at once because that makes it impossible to identify which change helped. Close any previous Gemini CLI process, open a new terminal, and run the request again while watching the Clash dashboard.

• Connection refused: Check the local proxy address and port. The terminal may be using port 7890 while your client is configured to listen on another port.
• Operation timed out: Check whether the request is being routed through a usable proxy node, whether DNS resolves correctly, and whether IPv6 is failing before IPv4 is attempted.
• TLS or certificate errors: Do not immediately disable certificate verification. Check system time, antivirus HTTPS inspection, and whether a corporate network is intercepting TLS.
• HTTP authentication or quota errors: The network path is probably functional. Verify the API key, project configuration, account permissions, and usage limits.

Verify Clash Before Troubleshooting Gemini CLI

Before editing shell configuration, confirm that Clash itself can reach a known HTTPS destination. Open Clash Verge Rev or another Mihomo-based client and check that a profile is active. Select a node that passes the built-in latency test, then confirm that the proxy group used by your rules is not empty. A profile can appear imported while its primary proxy group still points to a deleted or unavailable node.

Next, check the local listeners in the Clash settings. Common defaults are HTTP on 127.0.0.1:7890 and SOCKS5 on 127.0.0.1:7891, but these values are not universal. Some clients use mixed ports such as 7893, and some installations bind only to an IPv6 loopback address. Always use the values shown in your client rather than assuming the defaults.

# Test the HTTP proxy listener
curl -v -x http://127.0.0.1:7890 https://www.gstatic.com/generate_204

# Test the SOCKS5 listener
curl -v --socks5-hostname 127.0.0.1:7891 https://www.gstatic.com/generate_204

A successful connectivity test normally returns a small response, often with an HTTP 204 status. The important part is not the exact status code but whether the TLS connection completes through the selected node. If both tests fail, fix Clash or the active node first. If the tests work but Gemini CLI still times out, focus on the terminal environment and the specific Google API domains.

Check the Listening Port from the Operating System

When you suspect that no process is listening on the configured port, use the operating system's socket tools. On Windows, PowerShell can show the process associated with a port. On macOS and Linux, lsof or ss is useful. Replace the port number with the one shown in Clash.

# Windows PowerShell
Get-NetTCPConnection -LocalPort 7890 -ErrorAction SilentlyContinue

# macOS or Linux
lsof -nP -iTCP:7890 -sTCP:LISTEN
ss -ltnp | grep 7890

If no listener is found, enable the HTTP or mixed port in Clash and retry. If another application owns the port, choose a free port in Clash and update the terminal variables accordingly. A port that works in one terminal but not another often indicates that one shell has old environment variables loaded from a previous configuration.

Configure Proxy Variables Correctly

Most terminal applications recognize one or more of HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, and their lowercase equivalents. Different Node.js, Python, Go, and Rust libraries do not always interpret these names identically, so setting the conventional uppercase and lowercase forms is a practical compatibility measure.

For an HTTP or mixed Clash port, use an HTTP proxy URL for both HTTP and HTTPS requests. The word “HTTPS” in HTTPS_PROXY describes the destination protocol; it does not mean that the local proxy listener must itself use HTTPS.

# macOS and Linux: current shell session
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
export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export all_proxy="$ALL_PROXY"

# Optional: bypass local addresses
export NO_PROXY=localhost,127.0.0.1,::1

On Windows PowerShell, the equivalent temporary settings are:

$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"
$env:http_proxy = $env:HTTP_PROXY
$env:https_proxy = $env:HTTPS_PROXY
$env:all_proxy = $env:ALL_PROXY
$env:NO_PROXY = "localhost,127.0.0.1,::1"

These commands affect only the current shell process and programs launched from it. That makes them ideal for testing. If Gemini CLI begins working, place the settings in the correct startup file only after you understand the result: ~/.zshrc or ~/.bashrc on macOS and Linux, and your PowerShell profile on Windows. Restart the terminal after editing the file.

Remove Stale or Conflicting Variables

A common cause of intermittent behavior is a stale variable pointing to an old port, a removed VPN adapter, or a proxy that requires credentials. Inspect the current environment before testing:

# macOS and Linux
env | grep -i proxy

# Windows PowerShell
Get-ChildItem Env:*proxy*

Look for values such as http://localhost:8080, an old remote address, or a URL with an incorrect scheme. If you need a clean comparison, temporarily clear all proxy variables and test again. In PowerShell, use Remove-Item Env:HTTP_PROXY and the corresponding commands for the other names. In a POSIX shell, use unset HTTP_PROXY HTTPS_PROXY ALL_PROXY http_proxy https_proxy all_proxy.

Test the Google API Path Independently

Testing a general website is useful, but Gemini CLI does not necessarily use the same hostname. Google services may involve API endpoints, authentication hosts, certificate services, and regional infrastructure. A general website can pass while the domain used by the CLI is matched by a different Clash rule.

Use curl with verbose output to inspect DNS, connection establishment, and TLS negotiation. The exact endpoint can vary by Gemini CLI release, so use a hostname visible in the Clash connection log or the CLI's debug output. The following examples are connectivity checks, not API calls:

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

An HTTP response from the server, even a page saying that authentication is required, is evidence that the network path completed. A DNS failure, connection timeout, or TLS handshake timeout points to a lower-level problem. Repeat the same command with and without the proxy only as a diagnostic comparison; a direct failure does not prove that the proxy is correctly configured, and a direct success may simply mean that the endpoint is reachable from your current network.

Read the Clash Connection Log

Open the Connections or Logs view in your Clash client and start Gemini CLI after clearing old entries. Check the domain, process name if available, destination port, matched rule, and final policy. You want to see the Google API traffic assigned to the intended proxy group rather than DIRECT or REJECT.

If the connection appears as DIRECT, your rule set is bypassing the proxy. If it appears as REJECT, an ad-blocking or security rule may be too broad. If the connection is assigned to a proxy group but remains in a connecting state, test another node and inspect whether the node itself can reach Google services. A node that is fast for ordinary websites may still have trouble with long-lived HTTPS requests or specific Google infrastructure.

The correct diagnostic question is not “Is Clash enabled?” but “Did this exact Gemini CLI connection enter Clash, match the intended rule, and complete through a working node?”

Fix Clash Routing Rules

Clash evaluates rules from top to bottom. The first matching rule wins, so a broad rule placed above a specific Google rule can produce an unexpected result. Review both manually written rules and imported rule providers. A provider may classify a domain as direct, reject, or a special service category before your custom rule is reached.

For a temporary test, add specific domain suffix rules near the beginning of the rule list and route them to a known working proxy group. The policy name must exactly match a group in your configuration.

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

Do not copy this example permanently without considering your own routing goals. A broad google.com rule can route many unrelated services through the proxy and may be unnecessary. Once the connection works, narrow the rules to the domains shown in your logs. Also check that the group name PROXY actually exists; some subscriptions use names such as Proxy, 🚀 Proxy, or Auto.

Check Rule Order and Rule Providers

Rule providers make configuration convenient, but they can hide the effective order of matching. A reject provider placed first may match a Google hostname containing a keyword that was intended for advertising domains. A geographic direct rule may also send traffic to an address range that your network cannot reach. Temporarily disable one provider at a time, reload the configuration, and reproduce the request.

After every rule change, use Clash's configuration validation feature if available. YAML indentation errors, duplicated policy names, and invalid provider formats can prevent the profile from loading or cause the client to fall back to an older configuration. Confirm the active profile's update time before assuming that the edited file is being used.

Resolve DNS and IPv6 Problems

DNS is frequently overlooked because terminal tools may resolve names differently from browsers. In normal system-proxy mode, the operating system can resolve the destination before the request reaches Clash. That resolution may use a local DNS server that returns an unreachable address, exposes the queried domain, or returns IPv6 first even though the selected proxy path works only with IPv4.

Mihomo-based Clash clients provide DNS settings that can send queries through a controlled resolver. For troubleshooting, enable a suitable fake-IP or redir-host strategy according to your client and profile, and make sure DNS hijacking is enabled when using TUN mode. Do not change multiple DNS options without recording the original configuration; some providers depend on a particular behavior for local domains.

To compare resolution results, run the following commands:

# Check ordinary system resolution
nslookup generativelanguage.googleapis.com

# Check address records
dig A generativelanguage.googleapis.com
dig AAAA generativelanguage.googleapis.com

# Force curl to use IPv4 for comparison
curl -4 -v -x http://127.0.0.1:7890 https://generativelanguage.googleapis.com/

# Force curl to use IPv6 for comparison
curl -6 -v -x http://127.0.0.1:7890 https://generativelanguage.googleapis.com/

If IPv4 works and IPv6 consistently hangs, temporarily disable IPv6 in the Clash profile or operating system as a diagnostic step. A better long-term solution is to configure the client and node so that IPv6 is handled correctly. Disabling IPv6 is not always necessary and can break local networks, so treat it as a test rather than a universal fix.

When to Enable TUN Mode

Environment variables are usually the simplest solution, but not every CLI release or dependency honors them. Some applications use a custom network stack, launch a helper process with a cleaned environment, or perform DNS and socket operations outside the proxy-aware library. In these cases, TUN mode can provide a more complete system-level path.

Mihomo TUN mode creates a virtual network interface and captures traffic below the application layer. This means Gemini CLI does not need to understand HTTP proxy variables. TUN can also capture DNS requests and traffic from child processes, making it useful when the main command works but an authentication helper or update process bypasses the proxy.

TUN mode is not automatically better for every computer. It adds a virtual interface, requires elevated privileges, and can interfere with VPN software, corporate security agents, Docker networks, or local development services. If environment variables provide a stable and transparent route, keep the simpler setup. Use TUN when the application genuinely bypasses the normal proxy layer or when you need consistent coverage for multiple tools.

Check Node Quality and TLS Behavior

A working Clash configuration does not guarantee that every node is suitable for Gemini CLI. Test at least two or three nodes from different regions or transport types. Choose a node with stable latency rather than relying only on the lowest single test result. Long API requests need consistent connectivity; a node that briefly reports excellent latency but drops idle or sustained TLS sessions can still cause timeouts.

Pay attention to whether the timeout happens during TCP connection, TLS negotiation, or response transfer. Verbose curl output can show where the process stops. A failure before “Connected to” suggests a route or node problem. A failure during TLS can indicate interception, an incompatible node, incorrect system time, or a middlebox. A connection that establishes but stalls while waiting for response data is more likely to involve the remote service, congestion, or a broken long-lived connection.

Keep the system clock accurate. OAuth flows and TLS certificates depend on correct time, and a clock that is several minutes off can cause authentication failures that look unrelated to proxying. Also check antivirus software and enterprise security products that inspect HTTPS traffic. If such software is installed, test on a trusted network or temporarily use its documented exclusion mechanism rather than disabling security features permanently.

Platform-Specific Checks

Windows

On Windows, confirm whether Gemini CLI is running in PowerShell, Command Prompt, Git Bash, WSL, or a terminal embedded in an editor. Each environment can have a different set of variables and network behavior. A variable configured in PowerShell is not automatically available inside a separate WSL distribution. If the CLI is installed through a package manager, verify which executable is being launched with where gemini and check that the process is not an older global installation.

Windows Defender Firewall or endpoint security may treat a newly installed runtime differently from your browser. If Clash is listening only on loopback, a local firewall rule should normally permit local access, but security software can still block a runtime such as Node.js. Review the security event log and allow the application through the documented policy when necessary.

macOS

On macOS, shells launched by a graphical terminal and shells launched by an editor may load different startup files. Put test variables in the active shell first, then make persistent changes only after confirming the correct file. macOS privacy and network-extension permissions can also affect TUN mode. Approve the requested extension in System Settings and restart the client if the virtual interface does not appear.

Apple Silicon and Intel systems may use different runtime installations. Check that the CLI and Clash client are running natively or under the same architecture where possible. Architecture mismatches are not a normal cause of a network timeout, but they can lead to multiple installations and confusing configuration paths.

Linux

On Linux, shell variables do not automatically apply to systemd services, desktop launchers, or containers. If Gemini CLI is launched by an editor, inspect the editor's environment rather than assuming it inherits your interactive shell. For containerized workflows, pass the proxy variables into the container and ensure that host.docker.internal or the host gateway is reachable; 127.0.0.1 inside a container refers to the container itself, not the host running Clash.

Linux TUN mode may require capabilities, routes, and DNS configuration that vary by distribution. After enabling it, inspect the routing table and resolver status, but do not manually delete routes unless you understand the consequences. A reboot or controlled client restart is safer than repeatedly changing kernel networking state during an active troubleshooting session.

A Reliable Diagnostic Workflow

The following sequence minimizes guesswork and works across operating systems:

1. Confirm that Clash is running, a profile is active, and a selected node passes a basic HTTPS test.
2. Record the local HTTP, SOCKS5, or mixed port from the Clash settings.
3. Inspect and temporarily simplify all proxy environment variables in the terminal.
4. Run a proxied curl request to a known HTTPS endpoint.
5. Run a second test against a Google API hostname and watch the Clash log.
6. Check whether the request is marked DIRECT, REJECT, or assigned to the intended proxy group.
7. Review DNS and IPv6 behavior if the connection stalls before TLS completes.
8. Try another proxy node before changing advanced Clash options.
9. Enable TUN only if the CLI or a child process bypasses the proxy variables.
10. After the fix, remove unnecessary temporary rules and document the final working settings.

This order matters. It separates local listener problems from upstream node problems, and it separates routing mistakes from DNS mistakes. It also prevents a common troubleshooting trap: enabling TUN and changing the rule set at the same time, then assuming the last change caused the improvement.

Common Mistakes to Avoid

• Using the wrong port: The browser may work through the system proxy while the terminal points to an old port. Always test the exact listener used by the shell.
• Using a SOCKS URL as an HTTP URL: A client expecting HTTP proxy syntax may reject or mishandle socks5://. Use a compatible scheme or configure the application's SOCKS option explicitly.
• Testing only the browser: Browser success does not prove that Gemini CLI inherits the same route, DNS resolver, or credentials.
• Adding a catch-all Google rule too early: Broad rules can hide the real problem and unexpectedly proxy unrelated traffic. Begin with the exact domains in the log.
• Ignoring subscription updates: A profile may contain a proxy group that references removed nodes. Update the subscription and verify the active configuration.
• Leaving debug settings enabled permanently: Verbose logging can expose URLs, headers, or account-related information. Return to normal logging after diagnosis.
• Sharing API keys or subscription URLs: A timeout report should remove authentication tokens, subscription links, and personal paths before publication.

Final Recommendation: Use the Simplest Working Clash Path

Gemini CLI timeouts are usually not solved by randomly switching nodes or repeatedly reinstalling the CLI. The fastest approach is to identify where the request stops: before the local Clash listener, inside the routing engine, during DNS resolution, while connecting to the selected node, or after the remote API receives the request.

For most users, the recommended setup is a maintained Mihomo-based Clash client, a verified active profile, explicit terminal proxy variables, and a narrow rule for the Google API domains required by Gemini CLI. This arrangement is easy to inspect and does not capture unrelated traffic. If the CLI ignores those variables or launches helper processes that bypass them, TUN mode provides broader coverage and centralized DNS handling.

Compared with basic browser-only proxy extensions, Clash gives you visibility into individual connections, ordered rules, selectable nodes, DNS control, and optional system-wide interception. Those features make it easier to distinguish an application problem from a routing problem. Compared with an opaque full-device VPN, Clash also lets you keep local services direct and route only the domains that need a proxy.

• Use logs first: confirm whether Gemini CLI actually reaches Clash and which policy is applied.
• Use explicit variables for transparency: they are simple to test and easy to remove.
• Use targeted rules: avoid broad catch-all rules until the exact destination is known.
• Use controlled DNS and TUN mode when required: especially for proxy-unaware tools, child processes, IPv6 issues, or DNS leaks.
• Keep a known-good backup profile: it makes future subscription or rule changes much easier to diagnose.

If you need a maintained Clash client for testing these settings, visit the Clash downloads page. Install the version appropriate for your operating system, import your own subscription, and then apply the checks in this guide one at a time. This site provides client guidance only; proxy nodes, subscriptions, API credentials, and Gemini service access must come from their respective providers.