Gemini CLI With Clash: Reliable Access Setup Guide

Why Gemini CLI needs explicit proxy routing

Gemini CLI brings Gemini assistance into a terminal, which makes it useful for code explanation, refactoring, test generation, documentation, and repository-level tasks. The command-line workflow is different from opening Gemini in a browser, however. A browser may follow the operating system proxy automatically, while a terminal process may use its own HTTP client, inherit only selected environment variables, or bypass the desktop proxy entirely. As a result, “the browser works” does not prove that Gemini CLI can reach its API endpoint.

Clash adds a local forwarding layer between the CLI and the public network. A typical setup consists of a Clash or mihomo core, a graphical client such as FlClash or Clash Verge Rev, a subscription containing proxy nodes and policy groups, and an environment variable that tells command-line programs where to send HTTP or HTTPS requests. These are separate parts. Importing a subscription does not automatically configure Gemini CLI, and enabling TUN mode is not always necessary.

For most developers, begin with the least invasive route: run Clash in rule mode, enable its system proxy if needed, and explicitly assign the local mixed port to the terminal process. A common mixed port is 7890, but the actual value must be checked in the active configuration. Do not assume that every Clash client uses the same port, because a client may choose 7890, 7897, 7898, or another available port.

Prepare Clash and import a subscription

Install a maintained Clash-compatible client from the download center, then open its configuration or profiles page. FlClash, Clash Verge Rev, and other mihomo-based clients use different interface labels, but the workflow is similar: add a subscription URL, download the profile, select it, start the core, and check the active proxy group. A subscription URL is sensitive because it commonly contains an access token. Store it in a password manager or another private location, and never paste the complete URL into a public issue, terminal screenshot, or repository.

Check the profile before starting the core

After the profile is downloaded, confirm that it is a Clash-compatible configuration rather than an HTML login page or a JSON error response. A healthy profile generally contains fields such as proxies, proxy-groups, and rules. It may also contain mihomo-specific fields such as rule-providers, sniffer, geodata-mode, or advanced DNS settings. Those fields require a compatible mihomo core; an older classic Clash core may fail to parse them or silently omit important behavior.

Set the operating mode to rule unless you have a specific reason to use global mode. In rule mode, Gemini-related domains can be sent through a selected proxy group while local development services remain direct. Global mode is useful for a short diagnostic test, but it can unexpectedly proxy package registries, intranet addresses, container endpoints, and local services.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

The example uses loopback binding deliberately. allow-lan: false prevents other devices on the local network from using the proxy unless you explicitly need LAN access. If the client already generates these values, do not create a second configuration merely to copy the example. Instead, read the current values from the client’s settings or the active YAML profile.

Confirm a working policy group

Before involving Gemini CLI, test the selected policy group with a browser or a command-line request. Choose a node that passes the client’s latency or connectivity check, but remember that a low ICMP or TCP latency does not guarantee that an HTTPS API request will succeed. The node must also complete TLS negotiation, resolve the target domain correctly, and remain stable during a streamed response.

Use the client’s connection view to confirm that traffic is actually leaving through the expected group. If no connection appears when you test the service, the request may be bypassing Clash, the command may be using a different proxy port, or the application may be connecting through a method not covered by the current rules.

Configure Gemini CLI through the local proxy

The most portable approach is to set proxy environment variables in the same terminal session where Gemini CLI will run. For a local HTTP mixed port, use the following examples. The http:// scheme is intentional: a Clash mixed port accepts HTTP proxy requests and commonly supports the HTTP CONNECT method for HTTPS destinations.

# macOS, Linux, and compatible shells
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 NO_PROXY=127.0.0.1,localhost,::1

gemini

Not every command-line dependency reads all three variables. HTTP_PROXY and HTTPS_PROXY are the important starting points; ALL_PROXY is useful for tools that use a generic proxy setting. Some applications recognize lowercase names instead, so you can set both forms when behavior is unclear.

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 no_proxy=127.0.0.1,localhost,::1

On Windows PowerShell, set the variables for the current session like this:

$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:NO_PROXY = "127.0.0.1,localhost,::1"

gemini

These variables do not change Clash’s port. Replace 7890 with the actual mixed port shown by your client. If the client exposes separate HTTP and SOCKS ports, the mixed port is usually the simplest choice because one address can handle both ordinary HTTP proxy requests and HTTPS tunneling. A SOCKS5 port can work for software that explicitly supports SOCKS, but it is not interchangeable with an HTTP proxy port.

Make the setting repeatable

For temporary testing, set the variables only in the current shell. This makes it easy to compare direct and proxied behavior. Once the configuration is confirmed, place the exports in the shell startup file used by your terminal, such as ~/.zshrc or ~/.bashrc. On Windows, use a PowerShell profile or a project-specific script instead of globally forcing every application through Clash.

A project-specific launcher reduces side effects and makes the route visible to other developers. For example, create a private script with the proxy values omitted from version control, or use a shell function that exports the variables and starts Gemini CLI. Do not hard-code subscription tokens, API keys, or credentials in the launcher. Proxy settings and authentication settings should remain separate.

Gemini CLI authentication may use an interactive account login or an API key, depending on the installation and provider configuration. Proxying the connection does not replace authentication. If the command reaches the service but reports an invalid credential, expired login, quota problem, or permission error, the Clash route is probably working and the next investigation belongs to the account or project configuration.

Hands-on diagnosis from the terminal

Run these checks after Clash is started and before changing several settings at once. The goal is to identify whether the failure occurs at the local port, DNS resolution, TLS connection, proxy policy, authentication, or the CLI itself. Use a harmless public HTTPS endpoint for the first test and avoid printing authorization headers or complete API URLs containing secrets.

Step 1: test the local proxy port

On macOS or Linux, check whether something is listening on the configured port:

curl --proxy http://127.0.0.1:7890 \
  --connect-timeout 10 \
  --max-time 20 \
  -I https://www.google.com

On Windows PowerShell, the same curl syntax may be mapped to another command in older environments. Use curl.exe when you need the native curl behavior. A connection refused error usually means the core is stopped, the port is wrong, or another process is using the address. A timeout suggests that the core accepted the request but could not complete the outbound connection, so inspect the selected policy, DNS, and core log.

Step 2: test inherited environment variables

Confirm that the shell contains the intended proxy without exposing unrelated secrets:

env | grep -i proxy

For PowerShell, use:

Get-ChildItem Env: | Where-Object Name -Match "PROXY"

Then run a request without the explicit --proxy argument:

curl --connect-timeout 10 \
  --max-time 20 \
  -I https://www.google.com

If the explicit proxy test works but the inherited-variable test fails, Gemini CLI may be receiving a different environment, the variable spelling may not match the underlying HTTP library, or a wrapper script may be clearing proxy variables. If both curl tests work but Gemini CLI fails, inspect the CLI’s own logs, authentication flow, and supported proxy behavior.

Step 3: inspect Clash connections and rules

Keep the Clash connection panel open while launching Gemini CLI. You should see outbound requests appear when the CLI performs login, checks account state, or sends a prompt. The exact domains may vary by release, authentication method, region, and enabled features. Do not build a rule from a single guessed hostname. Instead, record the domains visible in the connection log, verify that they belong to the service you intend to use, and route only those domains through the appropriate policy group.

Check whether a rule such as GEOIP,CN,DIRECT, a broad DOMAIN-SUFFIX entry, or a provider-specific rule sends the request direct before it reaches the intended proxy rule. Clash evaluates rules from top to bottom. A later proxy rule cannot override an earlier matching direct rule. When testing, temporarily use global mode or place a narrow diagnostic rule above conflicting rules, then restore the normal rule set after confirming the result.

Step 4: separate transport from authentication

A successful HTTPS connection can still return an authentication or authorization failure. Treat these results differently:

• Connection refused: The local Clash port is unavailable, incorrect, or occupied by another process.
• Timeout or connection reset: Check the selected node, DNS mode, TLS path, and whether the proxy permits the destination.
• Certificate or TLS error: Check system time, certificate inspection software, and whether a custom CA was improperly configured. Do not disable certificate verification as a first response.
• 401 or invalid credential: The request reached the service, but the login session or API key is not accepted.
• 403 or region restriction: The service rejected the account, source location, policy, or request type. Changing a node may help diagnose the route, but it does not fix an account policy.
• 429 or quota error: The service is rate-limiting the account or project. Repeatedly changing Clash nodes will not remove the quota.

Choose between system proxy, TUN, and global mode

System proxy mode is normally sufficient when Gemini CLI reads the operating system proxy or the explicit environment variables shown above. It keeps routing easy to understand and leaves applications that do not need the proxy untouched. It is also the best starting point for diagnosing a CLI because the route can be enabled or disabled without changing the entire network stack.

TUN mode creates a virtual network interface and can capture applications that ignore system proxy settings. It may be useful when Gemini CLI is started by an IDE, background process, task runner, or service that does not inherit your terminal environment. TUN also introduces additional variables: administrator permission, route installation, DNS interception, IPv4 and IPv6 behavior, and possible conflicts with other VPN software. Enable it only after confirming that a normal proxy cannot cover the required process.

Global mode sends nearly every eligible request through the selected policy. It is a diagnostic tool rather than an ideal permanent configuration for development. Package managers, Git remotes, cloud SDKs, private registries, Docker services, and localhost endpoints may require direct access or a separate proxy group. After a global-mode test, return to rule mode and create targeted rules based on observed connections.

Common failures and stable fixes

The browser works, but the terminal fails

Check the environment variables first. A browser may use the system proxy while the shell has no proxy configuration at all. Next, verify that the terminal process was started after the variables were exported. GUI applications launched from an operating-system menu may not inherit variables from an interactive shell, while an IDE-integrated terminal may inherit a different set of values. Start with a direct terminal invocation and compare the result with the IDE.

The CLI reports a network error during login

Interactive authentication can contact more than one endpoint. The initial login page, callback, token exchange, account check, and model request may not use identical domains. Watch the Clash connection log through the complete login sequence. If the callback uses localhost, keep it in NO_PROXY; if the browser completes login but the CLI cannot exchange the result, check whether the callback process and the terminal share the same environment and local permissions.

Streaming responses stop or hang

AI command-line tools often keep an HTTPS connection open while receiving streamed output. A node that handles short requests may still reset long-lived connections, apply an idle timeout, or have unstable packet loss. Test another node in the same policy group, check the core log for resets, and avoid repeatedly retrying large prompts. If only long responses fail, compare node stability and timeout behavior rather than changing YAML syntax randomly.

DNS errors appear only in rule mode

Rule mode can expose DNS differences that global mode hides. The core may resolve a domain locally, through a configured remote server, or through fake-IP processing, depending on the profile. Review dns.enable, the DNS mode, fallback behavior, and any private-domain exclusions. Do not copy a DNS block from an unrelated profile without checking mihomo compatibility. A malformed or unsupported DNS field can prevent the entire configuration from loading.

Another Clash process owns the port

Only one process should listen on a given local port. If Clash Verge Rev, FlClash, Clash for Windows, or another proxy client is still running, the new client may fail to start its core or may expose a different port than expected. Quit the old client, disable its system proxy and TUN mode, then start one core. Confirm the active process and port before testing Gemini CLI again.

FAQ