Gemini CLI With V2RayN: Setup Tips For Reliable Access

Gemini CLI is becoming a practical coding assistant for terminal-based workflows, but access from mainland China can be inconsistent. A browser may open normally while the command-line client reports a timeout, an authentication failure, or an upstream connection error. The difference is usually not the Gemini account itself. It is often caused by the way the terminal process discovers proxy settings, the local port exposed by v2rayN, the selected Xray route, or a node that cannot reliably reach the required service.

v2rayN does not automatically proxy every command-line program simply because the desktop client is running. It normally starts a local HTTP or SOCKS5 inbound, and an application must either use the system proxy, inherit suitable environment variables, or connect through a TUN-based traffic path. This distinction is the key to setting up Gemini CLI correctly. First make the v2rayN connection work, then make the terminal use the intended local port, and only after that troubleshoot Gemini CLI authentication or project settings.

Article overview

This guide explains how to prepare v2rayN, import and select a subscription node, identify the local proxy ports, route Gemini CLI traffic from a terminal, and isolate common errors without changing several variables at once. It is intended for beginners who want a repeatable setup rather than a temporary workaround.

Understand the traffic path before changing settings

A Gemini CLI request usually passes through more layers than a web page opened in a browser. The terminal launches a process, the process reads proxy-related environment variables or application configuration, the connection reaches a local v2rayN inbound, and the Xray core then applies routing rules before sending traffic through the selected outbound. If any layer is bypassed, the CLI may connect directly even though a browser is already using v2rayN.

Gemini CLI startsProxy variables loadLocal port receivesXray matches rulesRemote API connects

Keep four separate questions in mind:

Is v2rayN running? The client should show an active core and a selected server, not merely a list of imported nodes.
Is the node usable? A subscription entry may exist while its address, port, certificate, or transport is no longer valid.
Which local port is available? An HTTP proxy port and a SOCKS5 port are different services. Sending HTTP proxy syntax to a SOCKS5 port can produce an immediate protocol error.
Does Gemini CLI inherit the proxy? A terminal opened before v2rayN starts may not have the same environment as a newly opened terminal, and system proxy settings do not always affect command-line libraries.

Layers to verify

10808

Example HTTP port

10809

Example SOCKS5 port

5 min

Typical first check

The port numbers above are common examples, not universal defaults. v2rayN versions, profiles, and manually edited settings may use different values. Always open the v2rayN settings page and confirm the actual HTTP and SOCKS5 ports before copying a command into the terminal.

Practical conclusion: test the local port first

If a request cannot reach the local v2rayN port, changing the Gemini model, API key, or subscription group will not solve the problem. A successful local proxy test gives you a clear boundary between terminal configuration and remote connectivity.

Prepare v2rayN and select a reliable outbound

Begin with the desktop client rather than Gemini CLI. Open v2rayN and confirm that the subscription group has been updated recently. A saved subscription URL is not proof that the update succeeded: the provider may return an authorization error, an empty response, or a group containing old server entries. Check the update result in the log pane and note whether the number of imported nodes changed unexpectedly.

Next, select one node and make it active. Selecting a row for inspection or latency testing is not always the same as setting it as the current outbound. Use the server action that marks the node as active, then check the active indicator, the status area, and the core log. These three signals should agree. If the row appears selected but the core is still using another outbound, Gemini CLI tests will produce misleading results.

Start the core
Open v2rayN and confirm that the Xray core status is running. If the core stops immediately, inspect the log before testing Gemini CLI.
Update the group
Open the subscription-group menu, run an update, and wait for a completed result. Do not use an old node simply because its name looks familiar.
Activate one node
Select a node with a recent successful latency test, then use the command for setting it as the active server.
Check proxy ports
Open the v2rayN settings and record the HTTP and SOCKS5 listening ports. In this example, they may be 10808 and 10809.
Enable a mode
For a terminal-only test, use explicit proxy variables. Enable the system proxy only when other desktop applications also need the route.

For a first Gemini CLI test, explicit proxy variables are easier to reason about than TUN mode. TUN can capture broader traffic, but it adds another layer involving virtual network adapters, DNS handling, permissions, and route exclusions. Once the CLI works through an explicit local proxy, you can decide whether TUN is useful for applications that do not support proxy variables.

HTTP proxy path

Example port: 127.0.0.1:10808
Variables: HTTP_PROXY, HTTPS_PROXY
Best use: CLI tools with HTTP proxy support

Replace 10808 with the port shown in your v2rayN settings.

SOCKS5 path

Example port: 127.0.0.1:10809
Variables: ALL_PROXY or tool-specific option
Best use: Applications supporting SOCKS5

Use the SOCKS5 scheme only when the client or library supports it.

Do not assume that an HTTP proxy and a SOCKS5 proxy are interchangeable. The address may be the same, but the handshake format is different. If an application reports an invalid response, unexpected EOF, or a connection reset immediately after connecting to localhost, verify the proxy type before changing the remote node.

Route Gemini CLI traffic from the terminal

The safest setup method is to open a new terminal after v2rayN is ready, define proxy variables for that terminal session, and run a small connectivity test before starting Gemini CLI. A new shell makes it easier to know which variables are active and avoids relying on settings inherited from a previous session.

Windows PowerShell

In PowerShell, set both uppercase and lowercase forms when you are unsure how the underlying Node.js or networking library reads environment variables. Many tools recognize uppercase names, while some dependencies inspect lowercase names. The following example uses the HTTP proxy port from the v2rayN settings:

$env:HTTP_PROXY="http://127.0.0.1:10808"
$env:HTTPS_PROXY="http://127.0.0.1:10808"
$env:http_proxy=$env:HTTP_PROXY
$env:https_proxy=$env:HTTPS_PROXY
$env:NO_PROXY="127.0.0.1,localhost"

# Confirm the values in the current shell
Get-ChildItem Env:HTTP_PROXY,Env:HTTPS_PROXY,Env:NO_PROXY

These assignments apply only to the current PowerShell process and programs launched from it. They do not permanently alter every terminal or Windows application. That temporary scope is useful during diagnosis: close the shell and the test configuration disappears, reducing the chance that unrelated commands continue using an unsuitable proxy.

Windows Command Prompt

In Command Prompt, use set instead of PowerShell’s $env: syntax:

set HTTP_PROXY=http://127.0.0.1:10808
set HTTPS_PROXY=http://127.0.0.1:10808
set http_proxy=http://127.0.0.1:10808
set https_proxy=http://127.0.0.1:10808
set NO_PROXY=127.0.0.1,localhost

set HTTP_PROXY

If the terminal uses a SOCKS5 inbound instead, the variable might be written as socks5://127.0.0.1:10809, but support depends on the application and its networking stack. Do not switch to SOCKS5 merely because the HTTP test fails. First confirm that the HTTP port is enabled and that the command is being run in the same shell where the variable was set.

Before running an interactive Gemini CLI login command, test a known HTTPS destination through the local proxy with a command-line HTTP client available on your system. For example, in PowerShell you can use:

curl.exe -I https://example.com

A successful response proves that the terminal can reach the local proxy and that the selected node can complete at least one HTTPS request. It does not prove that every Google endpoint, authentication flow, streaming response, or API operation will work. It does, however, separate a basic proxy failure from a Gemini-specific failure. If the command hangs, refuses the connection, or returns a proxy protocol error, fix v2rayN or the environment variables first.

After the basic test succeeds, start Gemini CLI from the same terminal. Keep the log pane visible in v2rayN while performing the first request. A new connection entry confirms that traffic reached the core. If the CLI fails but no corresponding connection appears in the v2rayN log, the process is probably ignoring the variables or using a different configuration source.

Choose a stable configuration for daily use

For regular coding work, avoid changing the node, proxy port, routing mode, and authentication method at the same time. A stable setup should have one known active node, one documented local port, one shell method for setting proxy variables, and one repeatable test command. Write these values down in a local note without recording sensitive credentials.

Routing mode also matters. If v2rayN is set to direct mode, Gemini CLI may bypass the proxy even when the client is running. If it is set to global mode, more traffic will use the proxy, which can help during a first test but may be unnecessary for local services and domestic destinations. Rule-based mode is usually easier to maintain after the target domains and authentication endpoints have been confirmed, but the exact domain list can change over time.

Explicit terminal proxy: Best for testing and for tools that honor HTTP_PROXY and HTTPS_PROXY. The route is visible in the shell.
System proxy: Convenient when several desktop applications should share v2rayN. It does not guarantee that every terminal library will honor the setting.
TUN mode: Useful for applications that do not expose proxy settings, but it requires careful DNS, route, and permission checks.
Global routing: Helpful as a temporary diagnostic baseline. Return to rule-based routing after confirming the real cause.

v2rayN is connected, but Gemini CLI still times out. What should I check first?

Open a new terminal, set HTTP_PROXY and HTTPS_PROXY to the actual v2rayN HTTP port, then run a simple HTTPS request. If v2rayN shows no new connection, the CLI is not using the proxy.

Should I use 10808 or 10809?

Use the port type shown in v2rayN. An HTTP proxy commonly uses a port such as 10808, while a SOCKS5 inbound may use 10809. The number alone is not enough; the scheme and client support must match.

Why does the browser work while the terminal fails?

The browser may be using the Windows system proxy or a browser-specific extension, while Gemini CLI only reads environment variables. Configure the terminal explicitly and test it independently.

Why did a subscription update remove a working node?

Subscription updates replace provider-managed entries. Check the update result and select a current node again instead of assuming that the previously active row remains valid.

Diagnose common Gemini CLI and v2rayN errors

Error wording can identify the failed layer. A refusal on 127.0.0.1 points to a local listener or port problem. A timeout after the local connection succeeds points farther along the path, such as the active node, transport, routing rule, or remote service. An authentication error usually means that the request reached the service but the login or credential state is invalid; changing the local port will not correct it.

Error: connect ECONNREFUSED 127.0.0.1:10808

Cause and fix: Nothing is listening on that port, or v2rayN uses another HTTP port. Confirm that the core is running and copy the current port from the settings page.

Error: socket hang up or connection reset

Cause and fix: The proxy type may not match the local inbound, or the selected outbound closed the connection during transport negotiation. Test the correct HTTP or SOCKS5 scheme and inspect the Xray log.

Error: request timed out

Cause and fix: The request may have reached v2rayN but failed at the node or remote route. Test another current node, check the system clock, and compare the result with a basic HTTPS request.

Error: certificate has expired or is not yet valid

Cause and fix: Verify the computer date, time zone, and synchronization status first. A significantly incorrect clock can break TLS and VMess-related validation.

Error: unauthorized or authentication failed

Cause and fix: Separate network access from account authorization. Confirm that the terminal reached the service, then repeat the supported Gemini CLI login flow without exposing credentials in a shared script.

When comparing nodes, change only one variable at a time. Keep the same terminal, proxy port, test command, and Gemini CLI operation while switching from one active node to another. If one node works and another fails, the evidence points toward the node, transport, or route rather than the CLI installation. If every node fails but a browser continues to work, focus on environment inheritance and terminal proxy detection.

Finally, remember that v2rayN is a client-side traffic router, not a guarantee that every remote endpoint will be reachable. Providers may change addresses, transports, or subscription contents, and services may apply region, account, or rate limits. A dependable workflow therefore uses a current subscription, a verified active node, an explicitly configured local proxy, and logs from both the terminal and v2rayN. Once those four pieces agree, Gemini CLI errors become much easier to classify and resolve.