Gemini CLI With Clash: Setup Guide For Reliable Access

Why Gemini CLI Needs a Carefully Configured Proxy

Gemini CLI brings an AI coding workflow into the terminal: you can ask for explanations, generate snippets, review files, plan changes, and iterate without leaving a shell session. That workflow depends on several network requests rather than a single page load. The command-line client may need to reach an authentication service, an API endpoint, a model service, documentation resources, and package or update services. If only one of those destinations is unreachable, the visible symptom may simply be a timeout or a generic connection error.

Clash helps by placing those requests behind a local HTTP or SOCKS5 listener and then applying rules to each destination. The terminal application does not need to know which remote node is selected. It only needs to send traffic to the local proxy port; Clash then selects a proxy group, resolves the destination, and forwards the connection according to the active configuration.

This is different from turning on a browser extension. A browser extension usually affects browser traffic only, while Gemini CLI is a separate process launched from PowerShell, Command Prompt, Terminal, or a script. It will not automatically inherit a browser's proxy settings. It may also ignore the operating system proxy if proxy environment variables are absent or if the application uses a networking library with its own behavior.

Check the Clash Side Before Opening the Terminal

Before changing shell variables, make sure Clash itself is ready. The exact menu names differ between Clash Verge, Clash Verge Rev, Mihomo clients, ClashX, and Android clients, but the underlying checks are the same. You need an active configuration, at least one usable proxy node, a running local mixed port or HTTP port, and a rule mode that sends the required destinations to a proxy group.

Port numbers are examples, not universal defaults. Open the Clash client and look under Settings, General, Ports, or similar. Clash Verge and Clash Verge Rev commonly expose a mixed port in the general settings area. If the client has a system proxy switch, enabling it is useful for ordinary desktop applications, but it is not a substitute for setting variables in the terminal.

Use Rule mode first. Global mode can prove that the selected node works, but it hides routing mistakes because every destination is forced through the proxy. Once the CLI connects successfully, switch back to Rule mode and inspect the connection log. A Gemini-related request should show the expected proxy group rather than DIRECT or REJECT.

Select a Suitable Proxy Group

For interactive terminal work, latency and consistency matter more than a short burst of high speed. Select a node that can maintain HTTPS connections for several minutes and does not frequently return authentication, TLS, or connection-reset errors. If your configuration includes a URL-test group, allow the test to finish before launching the CLI. A node with the lowest ping is not always the best choice because an ICMP or TCP latency test does not measure the complete application path.

Do not paste a subscription URL, access token, API key, or personal project content into a public issue or a terminal recording. A subscription URL is an account credential, and environment variables can also be exposed by diagnostic commands or shell history. Use visibly fake values in examples and replace them only in your local session.

Configure HTTP and SOCKS5 Variables in Your Terminal

Most command-line tools recognize one or more conventional proxy variables. The most compatible starting point is an HTTP proxy URL assigned to both HTTP_PROXY and HTTPS_PROXY. The name HTTPS_PROXY describes the destination protocol, not necessarily the protocol between the CLI and the local listener. An HTTPS request can commonly be sent through a local HTTP CONNECT proxy.

Do not set every variable to a different port without a reason. Conflicting values make troubleshooting harder. If your Clash client exposes only a mixed port, use that port for the HTTP and HTTPS variables. If the CLI specifically requires SOCKS5, use the SOCKS5 listener or a mixed port documented as supporting SOCKS5.

Windows: PowerShell and Command Prompt

In PowerShell, set variables for the current window with the following commands:

$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:ALL_PROXY = "socks5://127.0.0.1:7891"
$env:NO_PROXY = "localhost,127.0.0.1,::1"

These values apply only to processes started from that PowerShell window after the assignment. Start Gemini CLI in the same window. To remove them later, use Remove-Item Env:HTTP_PROXY, Remove-Item Env:HTTPS_PROXY, and the equivalent commands for the other variables.

In Command Prompt, use:

set HTTP_PROXY=http://127.0.0.1:7890
set HTTPS_PROXY=http://127.0.0.1:7890
set ALL_PROXY=socks5://127.0.0.1:7891
set NO_PROXY=localhost,127.0.0.1,::1

To make the settings persistent for future Command Prompt sessions, Windows provides setx, but persistent variables can surprise other applications. A temporary session is safer while diagnosing the connection. If a tool was already open before the variables were set, close and restart it so the child process receives the new environment.

macOS and Linux: POSIX Shells

In Terminal, Bash, or Zsh, export the variables before launching the CLI:

export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export ALL_PROXY="socks5://127.0.0.1:7891"
export NO_PROXY="localhost,127.0.0.1,::1"

Use env | grep -i proxy to display the current values. If the variables are placed in ~/.zshrc or ~/.bashrc, open a new shell or run the appropriate source command. On Linux, graphical terminals and services launched by a desktop menu may not read the same shell startup files, so launching Gemini CLI from the verified terminal is preferable during the first test.

Hands-On Workflow: Test the Exact Path Gemini CLI Uses

The most useful test is not a general browser check. It is a layered check performed from the same terminal and under the same environment variables that will start Gemini CLI. This separates a dead Clash listener, a bad node, a DNS problem, a routing mismatch, and an application-specific limitation.

1. Confirm the listener. In Clash, note the actual HTTP, SOCKS5, or mixed port. Make sure the client is running and that the selected proxy group has a node rather than an empty or failed selection.
2. Set temporary variables. Apply the PowerShell, Command Prompt, or POSIX commands above. Keep the terminal open; do not launch the CLI from a different window that has not inherited those values.
3. Inspect the environment. Run Get-ChildItem Env:*proxy* in PowerShell, set | findstr /i proxy in Command Prompt, or env | grep -i proxy on macOS and Linux. Check for spelling, scheme, address, and port.
4. Test a harmless HTTPS request. Use a command-line HTTP client available on your system, for example curl -I https://example.com. The response only proves that an HTTPS request can pass through the configured path; it does not authenticate Gemini CLI.
5. Read the Clash connection log. Filter the log by the request time. Confirm that the connection appears and identify whether it was assigned to the intended proxy group. If there is no log entry, the request did not reach Clash or the client bypassed the environment variable.
6. Launch Gemini CLI. Start it from the same shell. Complete authentication only through the normal interactive flow provided by the application, and never place a real token in a command pasted into a shared transcript.
7. Repeat with one small request. Ask for a short explanation of a local, non-sensitive code fragment. Watch the Clash log while the request is running, then test a second request to distinguish a transient node failure from a consistent routing problem.

Interpret the Results Before Changing More Settings

If the simple HTTPS request fails and Clash shows no connection, inspect the variable name and port first. If Clash shows the connection but it is assigned to DIRECT, review the rules and the current mode. If it is assigned to a proxy group but fails, test another node and inspect whether the node itself can establish ordinary HTTPS connections.

If the simple request works but Gemini CLI fails, the issue may involve application-specific proxy support, authentication, certificate validation, or a destination that is not covered by your expected rules. Check the CLI's own error text and compare its timestamp with Clash logs. Avoid changing DNS, TUN, and routing rules simultaneously because that removes the evidence needed to identify the actual fault.

Routing, DNS, and TUN Choices for Developer Workflows

Environment variables are usually enough when Gemini CLI uses a standard HTTP client and all of its network requests honor those variables. They are also the least disruptive option: Git, package managers, local services, and container tools remain unchanged unless they inherit the same shell environment.

TUN mode is broader. Mihomo creates a virtual network interface and captures traffic from applications that do not understand HTTP or SOCKS5 proxy variables. This can help when the CLI uses a library that ignores conventional variables, when an authentication helper starts a separate process, or when a subprocess opens a direct socket. TUN mode also captures more traffic, so a mistaken rule can affect package downloads, local development services, database connections, and private network addresses.

When enabling TUN, preserve direct access to loopback and local networks. Common private ranges include 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16, although the correct exclusions depend on your network. A local development server at localhost:3000 should not be sent to a remote node. If Docker, virtual machines, or a corporate LAN are involved, do not blindly copy a private-range bypass list; verify which networks those tools actually use.

DNS Practical Notes

DNS can fail before the CLI creates an HTTPS connection, especially when a domain is blocked, hijacked, or resolved to an unusable address. mihomo's DNS module can use fake-ip or redir-host enhanced modes and can route DNS requests according to configuration. However, changing enhanced mode is not the first response to every CLI error. Start by checking whether Clash logs the attempted domain and whether the returned address is consistent.

With fake-ip, a domain may appear as an address from the reserved 198.18.0.0/16 range inside Clash. That is expected in a compatible setup; it is not the remote server's real public address. If a command-line tool receives an unexpected fake address because it bypasses Clash's fake-IP handling, add the necessary application or domain exception according to the client documentation rather than disabling DNS interception globally.

Troubleshoot Timeouts, Authentication, and Direct Connections

Connection errors contain useful clues. “Connection refused” usually means nothing is listening on the configured local port, the port is wrong, or a local firewall is blocking access. “Could not resolve host” points toward DNS, a malformed proxy URL, or a resolver that the application uses outside Clash. A timeout after the request appears in Clash generally indicates a node, route, or remote service problem. An authentication failure after the network request succeeds is a separate account or credential issue, not proof that Clash is misconfigured.

Case sensitivity is another practical source of confusion. Many tools accept lowercase forms such as http_proxy and https_proxy, while some libraries prefer uppercase values. During testing, define both cases if the application documentation recommends it, but avoid leaving contradictory values in the same shell. On Windows, also check whether a system-level variable and a user-level variable contain different proxy ports.

Once the setup works, remove unnecessary variables and keep the smallest reliable configuration. A common final arrangement is one HTTP proxy value, one HTTPS proxy value pointing to the same local mixed port, a limited NO_PROXY list for loopback and local services, and a rule-mode Clash profile with a manually verified proxy group. Record the port and the reason for each exception in a private note so a future client update does not turn troubleshooting into guesswork.

A Practical Final Configuration

For most beginners, the reliable order is straightforward: install a maintained Clash client with the mihomo core, import a valid subscription, select Rule mode, verify a working node, set temporary proxy variables, test from the target terminal, and then launch Gemini CLI. If the application still bypasses the proxy, enable TUN mode and retest with local-network exclusions in place. Keep DNS changes separate from the first connectivity test.

This approach gives every layer a clear job. Clash handles nodes, rules, DNS, and connection logging. The shell variables tell the terminal application where the local proxy is. Gemini CLI handles its own authentication and requests. When those responsibilities are separated, a failure can be located without repeatedly reinstalling the client or replacing an entire configuration.

For a clean start, use the download center to choose a suitable client and then follow the beginner setup workflow. After the basic connection is confirmed, review routing and DNS behavior if your terminal tools require broader capture.