Gemini CLI Clash Setup: Reliable Access Guide for China

Why Gemini CLI Needs a Carefully Configured Proxy

Gemini CLI is a terminal-based coding assistant. Unlike a normal web page, it is not just one browser tab making one request. A typical session may contact an authentication service, an API endpoint, a model service, a package registry, telemetry infrastructure, and a remote repository. If one of those requests cannot resolve or connect, the command may display a vague timeout even though another Google page opens successfully in your browser.

That is why a Gemini CLI Clash setup should begin with observability rather than random configuration changes. Clash Verge gives you a local HTTP or SOCKS listener, a rule engine, connection logs, and selectable proxy groups. The terminal then needs to be directed to that listener. These are separate layers: Clash can be running correctly while Gemini CLI is bypassing it, and the terminal can have correct proxy variables while Clash is using an unavailable node.

A second consideration is traffic scope. You may want Gemini requests, Google authentication, and selected developer services to use a proxy while local package mirrors, intranet domains, printers, and domestic websites remain direct. Using Global mode can be useful for a short diagnostic test, but a stable daily configuration is usually better in Rule mode. Selective routing reduces latency for local traffic and prevents unrelated programs from consuming proxy bandwidth.

This tutorial focuses on the desktop workflow with Clash Verge or a compatible Clash Meta client. Menu labels differ slightly between releases, but the concepts remain the same: import a profile, select a working node, identify the local port, test the proxy independently, export the proxy to your shell, and then verify the actual CLI request.

What You Need Before Starting

Clash itself does not provide proxy nodes. It is a client and routing engine, so you must obtain a subscription from a provider you trust. Treat subscription URLs like credentials: they can reveal account information, consume quota, and sometimes contain access tokens. Do not paste a private subscription URL into public issue trackers or send it to a troubleshooting service.

Before debugging Gemini CLI, update Clash Verge and refresh your profile. Older clients may lack support for a protocol used by your provider, while an outdated profile may point to expired nodes. You do not need to change every advanced setting at once. A simple working profile is more valuable than a complicated configuration that cannot be inspected.

Step 1: Install Clash Verge and Import a Profile

Download Clash Verge from a trusted distribution page and choose the package for your operating system. On Windows, this is commonly an installer or portable archive. On macOS, use the package appropriate for your CPU architecture. On Linux, verify that the binary matches your distribution and architecture. If you need a safe starting point, visit the Clash download page for platform-specific options.

After launching the client, open the Profiles, Subscriptions, or similarly named section. Paste the subscription URL into the URL field, give it a recognizable name, and start the update. A successful download should produce a profile that can be selected or activated. If the update fails, do not immediately blame Gemini CLI; test the subscription URL in a browser or with a separate command-line request first.

1. Open the profile management page in Clash Verge.
2. Paste the Clash-compatible subscription URL and save it.
3. Click the update or download action and wait for the profile to parse.
4. Select the newly downloaded profile as the active configuration.
5. Open the proxy group page and select a node with acceptable latency.

Latency is only a first filter. A node can respond to a short latency test and still fail during TLS negotiation or sustained API traffic. After selecting a node, use the connection view and a real HTTPS test. If the profile contains automatic proxy groups, make sure the group has a usable selected member rather than an empty fallback.

Step 2: Find the Correct Clash Local Port

Gemini CLI cannot connect to the Clash application window directly. It connects to a local listener, usually an HTTP, SOCKS, or mixed port bound to the loopback address. In Clash Verge, open Settings and locate the port section. You may see separate values such as an HTTP port and a SOCKS port, or one mixed-port that accepts both common proxy formats.

Never assume the port is 7890. That is a common default, not a guarantee. Another application may already use it, or your client may have selected a different value during installation. Record the actual port shown by Clash Verge. For the examples in this article, replace 7890 with your real local port if it differs.

Also check the bind address. For a terminal running on the same computer, 127.0.0.1 or localhost is normally appropriate. Enabling LAN access is not required for local Gemini CLI use and exposes the listener to other devices if the firewall permits it. Only enable LAN access when you understand why another device needs the proxy, and restrict the firewall accordingly.

Listener type	Typical variable	Example value
HTTP or mixed port	HTTP_PROXY / HTTPS_PROXY	http://127.0.0.1:7890
SOCKS5 port	ALL_PROXY	socks5://127.0.0.1:7891
System proxy toggle	Operating-system applications	Enabled for browser testing

When both HTTP and SOCKS ports are available, use the mixed or HTTP port for the first Gemini CLI test. Many Node.js tools, package managers, and authentication libraries understand HTTP proxy variables more consistently than SOCKS variables. You can test SOCKS later if your client or wrapper specifically supports it.

Step 3: Test the Active Proxy Before Running Gemini CLI

Testing the local listener independently prevents misleading conclusions. First confirm that Clash is listening. Then confirm that an HTTPS request is being routed through the expected policy. Finally inspect the Clash connection log to see whether the request was assigned to the intended proxy group.

On macOS or Linux, open Bash or Zsh and run a request through the local HTTP listener:

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

On Windows, the same command usually works in PowerShell if curl is available. If your build maps curl to a different command, use the executable version or run the request from Git for Windows. A response such as 200, 401, or 404 can still prove that the server was reached; an authentication response is different from a network timeout.

Now test without the proxy option:

curl -I https://generativelanguage.googleapis.com

The direct request may fail, return a different response, or resolve through a different network path. That comparison is useful, but do not treat a successful direct response as proof that Gemini CLI will work. The CLI may use another endpoint, may require authentication, or may honor different environment variables.

If curl cannot connect to 127.0.0.1:7890, fix the local listener before changing Gemini settings. A refused connection usually means the port is wrong, Clash is not running, or the listener is disabled. A timeout after the request appears in Clash generally points toward DNS, routing, TLS, or node quality.

Step 4: Configure Proxy Variables for Your Terminal

Many command-line applications do not automatically inherit the system proxy toggle. They inspect environment variables when the process starts. Set the variables in the same terminal session that will launch Gemini CLI, or add them to the appropriate shell profile if you want them to persist.

For Bash or Zsh, use an HTTP-style URL for both HTTP and HTTPS 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"

Some libraries recognize lowercase names while others prefer uppercase names. To maximize compatibility, you can define both forms:

export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export all_proxy="$ALL_PROXY"

In PowerShell, variables are set with the $env: prefix:

$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"

In Command Prompt, use set instead:

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

These settings affect processes launched from that shell. If you open a new terminal tab, start an IDE-integrated terminal, or use a task runner, the variables may not be present there. This is one of the most common reasons a manual curl test succeeds while Gemini CLI still reports a connection error.

Verify that the variables exist before launching Gemini CLI:

echo "$HTTPS_PROXY"

In PowerShell, use $env:HTTPS_PROXY. If the output is empty, you are in a different shell or the assignment was not executed. If the output contains a stale port, update it to match Clash Verge.

Step 5: Run a Minimal Gemini CLI Test

Once the shell variables are set, begin with the smallest possible request. Do not combine proxy changes, account changes, model changes, and project configuration in one test. A minimal prompt makes the error easier to classify and produces fewer unrelated log entries.

Launch the CLI from the same terminal where you set the variables. The exact command may change with the Gemini CLI release, so use the command documented by your installed package. Ask for a short response such as an explanation of one line of code. If authentication is required, complete the supported sign-in flow rather than placing a token in a command copied into a shared script.

1. Confirm that Clash Verge is running and a usable profile is active.
2. Confirm the shell displays the expected proxy variable.
3. Start Gemini CLI from that shell, not from a shortcut that may use another environment.
4. Watch the Clash connection log while the CLI initializes.
5. Record the exact error text and the first failing hostname if the request fails.

If the CLI opens an authentication URL in a browser, remember that browser success does not prove that the CLI process is proxied. The browser and terminal can use different routes. After authentication, return to the same terminal and run the smallest CLI request again.

Some Node.js tools do not honor every proxy variable in every release. If the request still bypasses Clash, check the tool's documentation for proxy support, certificate configuration, or a supported command-line option. Avoid forcing undocumented variables indefinitely; a wrapper that works for one package version may break after an update.

Step 6: Use Rule Mode for Selective Google Routing

Global mode is useful for isolating a problem. If Gemini CLI works only in Global mode, the proxy itself is probably functional and the next task is rule design. In normal use, select Rule mode and ensure the domains required by your workflow are assigned to a proxy policy.

The exact endpoint list changes as Google services and the CLI evolve. Avoid copying a huge third-party ruleset without understanding it. Start with the hostnames visible in Clash logs during a successful or failed CLI launch. Then add narrow domain rules where appropriate. A domain suffix rule can cover a service family, but broad rules may proxy unrelated traffic and make troubleshooting harder.

rules:
  - DOMAIN-SUFFIX,googleapis.com,Gemini
  - DOMAIN-SUFFIX,google.com,Gemini
  - DOMAIN-SUFFIX,generativelanguage.googleapis.com,Gemini
  - DOMAIN-SUFFIX,googleusercontent.com,Gemini
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

The example is illustrative, not a universal production configuration. The policy group name must match a group in your active profile, and rule providers may insert rules above or below your custom entries. Clash evaluates rules from top to bottom, so a broad DIRECT rule placed before a specific Google rule can prevent the request from reaching the proxy group.

Keep local traffic usable. Add explicit direct rules for private networks, local development hosts, and internal services if your broader rules might capture them. If you use a package registry or corporate Git server, decide whether those domains should remain direct or use a dedicated policy. The best configuration reflects your actual workflow rather than trying to proxy everything.

DNS, TLS, and Certificate Issues

When a request appears in Clash but fails before receiving an HTTP response, investigate DNS and TLS separately. DNS problems can prevent the hostname from resolving, while TLS problems can occur after the address is known but before an encrypted session is established. A browser may hide these details behind a friendly error page; command-line logs often expose them.

Clash DNS settings vary by core and profile. A fake-ip configuration can improve rule matching, but incompatible applications may expect conventional addresses. A redir-host configuration can be easier to reason about during a basic test. Do not switch modes repeatedly without clearing stale caches and restarting the relevant applications.

Certificate errors can be caused by an incorrect system clock, an intercepting corporate proxy, an outdated certificate store, or a proxy node that closes the connection unexpectedly. Do not solve certificate failures by permanently disabling verification. That can hide an interception problem and expose credentials. First check the clock, update the operating system and runtime, and compare the behavior using a trusted node.

• DNS failure: the hostname cannot be resolved or the request stalls before connection.
• Connection refusal: the local port, remote node, or selected policy is unavailable.
• TLS failure: the connection starts but certificate negotiation fails.
• HTTP authentication error: the service was reached, but account or API authorization is incomplete.
• Rate limit: the route works, but the account, project, or endpoint has reached a usage limit.

Common Gemini CLI and Clash Failures

The browser works, but Gemini CLI fails

Check the terminal variables first. Then run curl with the explicit -x option. If curl works but the CLI does not, the CLI or its runtime may not honor the variables you selected. Check whether the process is launched by an IDE, a package manager, a shell script, or a system service. Each launch path can have a different environment.

Connection refused on the local proxy port

Open Clash Verge and read the actual HTTP or mixed port. Confirm that the client is running and that the listener is enabled. A port conflict can cause Clash to start without the expected listener, while a firewall or security application can prevent local binding. Testing 127.0.0.1 is preferable to testing a LAN address for a same-computer CLI.

Clash shows the request as DIRECT

This is normally a rule-order or mode issue. Confirm that the client is in Rule mode, search the active profile for a matching direct rule, and inspect the policy shown in the connection log. A domain rule that appears in a downloaded configuration may not be active if another provider or profile is selected.

The CLI reaches Google but authentication fails

Network reachability and account authorization are different problems. Check that you are using the correct account, project, region, model access, and supported authentication method. Do not repeatedly rotate nodes when the server is clearly returning an authorization response. Save the HTTP status and message, remove secrets from diagnostic logs, and follow the CLI's current authentication documentation.

Requests work sometimes and then time out

Test a fixed node instead of an automatic group. Compare failures with Clash's live connections and note whether the selected node changes between requests. Intermittent behavior can also come from DNS fallback, overloaded nodes, unstable Wi-Fi, MTU problems, or a rule that sends different hostnames to different policies. Make one controlled change at a time.

Security and Maintenance Practices

A local proxy is powerful because it can influence traffic from many applications. Keep the listener bound to localhost unless LAN sharing is genuinely required. If you enable LAN access, configure an operating-system firewall rule, avoid exposing the port to public networks, and disable the setting when finished. Never assume that a local port is harmless just because it does not require a password.

Update Clash Verge, the underlying core, and your subscription profile on a predictable schedule. An update can change supported proxy protocols, DNS behavior, or rule syntax, so keep a copy of the last known-good profile before making significant changes. Do not store private subscription URLs in public repositories or commit proxy environment variables containing credentials into project files.

For development projects, prefer temporary shell variables or a local ignored environment file. Review process output before sharing it. Debug logs can contain full URLs, query parameters, project identifiers, and account-related information. Redact these values before posting a question online.

A Repeatable Diagnostic Workflow

When Gemini CLI stops working after an update, resist the urge to reinstall everything. A short layered workflow usually identifies the failing component more quickly:

1. Check the application layer: confirm Clash Verge is open, the intended profile is active, and a proxy group has a selected node.
2. Check the listener layer: verify the actual local port and run a curl request through it.
3. Check the routing layer: inspect whether the target hostname is DIRECT, PROXY, or assigned to the expected policy.
4. Check the terminal layer: print the environment variables in the exact shell that launches Gemini CLI.
5. Check the service layer: separate DNS, TLS, authentication, quota, and model-access errors.
6. Check the node layer: compare a known-good node with the automatic group and record whether failures follow the node.

This sequence matters because each layer depends on the previous one. Changing Gemini authentication while the terminal is not using Clash creates noise. Rewriting DNS rules while the selected node is offline creates noise. Capture a small amount of evidence at every layer: the local port, the curl result, the Clash policy, the CLI error, and the time of the failure.

Once the request succeeds, remove temporary diagnostic settings. If you used Global mode, return to Rule mode and confirm Gemini still works. If you added a broad test rule, replace it with the narrowest practical rules based on observed traffic. A configuration that is easy to explain is usually easier to maintain.

Frequently Asked Questions

Does Gemini CLI automatically use Clash Verge?

Not necessarily. Some applications honor the operating system proxy, but terminal applications often require explicit HTTP_PROXY, HTTPS_PROXY, or ALL_PROXY variables. Test from the same shell that launches the CLI.

Which Clash port should I use?

Use the HTTP or mixed port displayed in Clash Verge. Many installations use 7890, but the value may be different. The correct port is the one currently shown in your client settings, not a number copied from another guide.

Should I leave Clash in Global mode?

Global mode is useful as a temporary diagnostic because it reduces rule-related variables. For daily work, Rule mode is generally preferable because it can proxy Gemini-related services while keeping local traffic direct. Always test your final rule configuration after switching back.

Can I put an API key directly in the proxy URL?

You should not combine service credentials with a proxy URL or publish them in shell history. Keep API credentials in the authentication method supported by Gemini CLI or in a protected local environment, and redact them from logs and screenshots.

Related Reading

For broader background, see the Clash beginner guide to understand profiles, modes, nodes, and subscriptions. If your desktop client shows connections but applications still report no internet, read the DNS and fake-IP troubleshooting guide. Windows users can also review the Clash Windows setup tutorial before tuning terminal-specific behavior.

Summary

Some alternative proxy clients hide terminal behavior behind a system-wide toggle, which can make the first test feel easier but leaves less visibility when one developer tool behaves differently from another. Clash gives you an inspectable local port, policy selection, live connections, and rule-level control, so you can see whether Gemini CLI is actually using the intended route rather than guessing from a browser result.

That combination is especially useful for AI coding workflows that mix Google services with local repositories, package managers, and private development tools. If you want a controllable starting point for this setup, Download Clash for free and use the layered checks in this guide to build a reliable configuration.