Fix Gemini CLI Proxy Issues with v2rayN: A Quick Guide

Map the connection path before changing settings

Gemini CLI does not automatically inherit every behavior of a graphical application. A browser may follow the Windows system proxy configured by v2rayN, while a command-line program may create its own network connection and consult only environment variables, a command-line option, or its own runtime configuration. If those values are empty, the request can leave through the direct network even though the v2rayN tray icon shows that the system proxy is enabled.

A useful connection path has several separate stages: the Gemini CLI process must receive a proxy instruction, the instruction must point to a listening local port, v2rayN must accept the connection, its routing rules must select the intended outbound, and the selected node must complete the remote handshake. DNS can participate at more than one stage. A failure at any stage may appear in the terminal as a generic timeout, connection reset, unavailable host, or authentication-related error.

Do not begin by replacing the node if a browser already works through the same v2rayN profile. First compare the browser path and the terminal path. If the browser is proxied but the terminal has no proxy variables, the node is probably not the first problem to solve. Conversely, if a terminal test reaches the local port but v2rayN reports that the core is stopped or the outbound handshake fails, the investigation should move to the core, routing, DNS, or node configuration.

The ports above are examples, not universal standards. In v2rayN, open Settings → Parameter Settings and inspect the actual HTTP and SOCKS listening ports. Some profiles use a mixed port, and some installations use different numbers because another application occupied the default. Never assume that port 10809 is correct merely because it is frequently used in examples.

Verify that v2rayN is listening locally

Before configuring Gemini CLI, select a known working node in v2rayN and start the core. Confirm that the tray menu or main window indicates that the system proxy is active, but treat that indicator as only one piece of evidence. The important question is whether a local HTTP or SOCKS listener is bound to the address and port that your terminal will use.

For a first test, prefer the HTTP proxy listener because most command-line tools understand an HTTP proxy URL directly. In v2rayN, check Settings → Parameter Settings → Local Port, or the equivalent inbound and port section shown by your installed version. Record whether the address is 127.0.0.1, localhost, or another local address, and record the protocol separately from the port.

On Windows, a local port can be checked from PowerShell with Test-NetConnection 127.0.0.1 -Port 10809. A successful TCP test proves only that something is listening; it does not prove that the listener can reach Gemini. If the test fails, recheck the port in v2rayN, start the core, and look for a port conflict. You can also use Get-NetTCPConnection -LocalPort 10809 to see whether a process owns the port.

If the local listener accepts connections but Gemini CLI still fails, watch the v2rayN core log while running one command. A log entry showing no new connection suggests that the CLI is not using the configured proxy. An entry showing an outbound connection, DNS failure, TLS error, or timeout means that the request reached v2rayN and the next layer needs attention.

Set proxy variables for the current terminal

Environment variables are often the quickest way to make a CLI process use v2rayN. Set both uppercase and lowercase forms because different libraries inspect different spellings. For HTTPS API requests, define HTTPS_PROXY; defining HTTP_PROXY as well is useful because the proxy itself commonly receives an HTTP CONNECT request even when the destination uses HTTPS. Keep NO_PROXY limited to addresses that must bypass the proxy.

1. Check the port

   In v2rayN, open “Settings” → “Parameter Settings” and copy the actual local HTTP proxy port. Replace 10809 below if your installation uses another value.

2. Set PowerShell values

   Run $env:HTTP_PROXY="http://127.0.0.1:10809", $env:HTTPS_PROXY="http://127.0.0.1:10809", and the matching lowercase assignments in the same PowerShell window.

3. Set CMD values

   In Command Prompt, run set HTTP_PROXY=http://127.0.0.1:10809 and set HTTPS_PROXY=http://127.0.0.1:10809. These values apply only to that Command Prompt session.

4. Inspect the variables

   Use Get-ChildItem Env:*proxy* in PowerShell or set *proxy* in CMD. Confirm there is no old port, quotation error, or unrelated proxy address.

5. Launch Gemini CLI

   Start Gemini CLI from the same terminal window after setting the variables. A new terminal opened from the Start menu will not automatically inherit temporary PowerShell or CMD assignments.

PowerShell commands for a common HTTP listener look like this:

$env:HTTP_PROXY="http://127.0.0.1:10809"
$env:HTTPS_PROXY="http://127.0.0.1:10809"
$env:http_proxy=$env:HTTP_PROXY
$env:https_proxy=$env:HTTPS_PROXY
gemini

For a SOCKS5 listener, the URL would usually be socks5://127.0.0.1:10808 or, for libraries that distinguish remote DNS handling, socks5h://127.0.0.1:10808. However, do not switch to SOCKS merely because the HTTP test failed. First establish whether the Gemini CLI version and its runtime support that scheme. Some Node-based network stacks accept HTTP proxy variables but do not automatically implement SOCKS5 without an additional proxy agent or application-specific setting.

Variables are process-scoped. If you launch Gemini CLI through an IDE task, a desktop shortcut, a separate terminal profile, or a service manager, it may not inherit the values you tested interactively. In that situation, place the variables in the relevant shell profile only after confirming the temporary test works. Persistent configuration is convenient, but a wrong port stored permanently can make later troubleshooting confusing.

Check the CLI runtime and application routing

A successful browser test does not prove that every Node.js request uses the same proxy mechanism. Gemini CLI may rely on its own HTTP client, a Node runtime’s fetch implementation, or a proxy-aware dependency whose behavior changes between releases. Check the CLI’s built-in help and release documentation for supported proxy flags or environment variables, but begin with the standard variables because they are easy to remove and reproduce.

Run the CLI from the same shell in which the variables are visible. If the command has a diagnostic or verbose mode, enable it for one request and look for the target host, connection attempt, and proxy-related message. Do not paste API keys, authorization headers, subscription URLs, or full authentication errors into public logs. A useful diagnostic record contains the core version, v2rayN local port, selected node, route mode, and the fact that the request was made with or without proxy variables.

Routing mode in v2rayN can also produce a misleading result. In a rule-based mode, the Gemini service domain may match a direct rule, a proxy rule, or an unresolved fallback rule. Check the active routing mode under Settings → Routing Settings and review the rule set. For diagnosis, a temporary global proxy mode can answer an important question: if Gemini CLI works globally but fails in rule mode, the problem is probably domain matching or DNS classification rather than the local listener.

Do not leave global mode enabled permanently without considering local services, private addresses, and traffic that should remain direct. Once the test identifies the cause, restore rule mode and add or correct only the required domain rules. A rule should be evaluated together with the DNS strategy, because a domain resolved locally before routing may be classified differently from one resolved through the proxy.

Separate DNS failures from proxy failures

DNS errors can occur before a proxy connection, inside the proxy path, or at the remote exit. These cases look similar in a short terminal message but require different fixes. If the CLI reports that a hostname cannot be resolved and v2rayN shows no new outbound request, the local process or local DNS path may be failing. If v2rayN logs a connection to the node followed by a remote resolution error, the problem is farther along the route.

In v2rayN, inspect Settings → DNS Settings and note whether DNS is handled by the system resolver, a remote server, or the core’s fake-IP or routing mechanism. Avoid changing several DNS servers at the same time. Make one controlled change, restart the core, and repeat the same Gemini CLI command so the result remains comparable.

• Local resolution failure: The terminal cannot resolve the target, while the local listener receives no useful request. Check the active network, resolver availability, and whether a stale NO_PROXY entry bypasses v2rayN.
• Direct-rule failure: The domain resolves locally and the routing table sends it direct. Temporarily test global proxy mode, then correct the domain rule if that changes the result.
• Remote DNS failure: The request reaches the node but the core log records a failed lookup at the proxy exit. Check the selected DNS strategy and whether the node can reach the resolver.
• TLS or endpoint failure: DNS succeeds, but the connection is reset or times out after resolution. Check node health, system clock, transport parameters, and the core log rather than repeatedly editing shell variables.

Use TUN mode only when process proxying is insufficient

TUN mode is useful when Gemini CLI ignores system proxy settings and does not honor the required environment variables. Instead of asking each application to understand HTTP or SOCKS, v2rayN creates a virtual network interface and captures traffic at the operating-system network layer. The core then applies routing rules and sends matching traffic through the selected outbound.

TUN is not a universal repair button. It may require administrator approval, a compatible driver, and a core that supports the selected TUN configuration. It can also change how DNS requests, local network addresses, container traffic, and other applications are handled. Before enabling it, close duplicate proxy tools and record the current v2rayN mode so that you can undo the change cleanly.

After enabling TUN, disable the shell proxy variables for one controlled test, or at least keep track of which mechanism is active. Running both TUN capture and an environment proxy can create a loop or make logs difficult to interpret. In v2rayN, confirm that the TUN interface is up, the core is running, and the Gemini domain matches a proxy route. Then run the same CLI command and compare the core log with the earlier process-proxy test.

If TUN makes browsing fail or local services unreachable, inspect bypass rules for private networks and local addresses. A common mistake is to treat every failure after TUN activation as a node problem when the actual cause is an overly broad route, a DNS interception conflict, or another VPN already controlling the default interface.

Follow a repeatable final test

Once one method appears to work, verify it with a small test matrix instead of assuming the issue is fixed. Keep the same v2rayN node and the same terminal command while changing only one variable: no proxy, HTTP proxy, rule mode, global mode, or TUN mode. Record whether the request reaches v2rayN and whether the failure occurs before or after the outbound handshake.

1. With v2rayN stopped, confirm that the direct command fails in the expected way or produces a clearly different result.
2. Start v2rayN, select a known working node, and confirm the HTTP listener with Test-NetConnection.
3. Set both uppercase and lowercase HTTP proxy variables in one terminal session and run Gemini CLI.
4. Compare rule mode with temporary global mode. If only global mode works, correct routing or DNS classification.
5. Test a second node without changing the CLI variables. If only one node works, inspect the failing node or core compatibility.
6. Use TUN only if the CLI still bypasses process proxying, then disable duplicate proxy mechanisms and repeat the command.

After the test succeeds, write down the working proxy URL, the v2rayN core version, the selected node, the routing mode, and whether TUN is enabled. Keep secrets out of that record. If you use a persistent shell profile, add only the confirmed variables and remove obsolete ports. If you use TUN, document the required permissions and the intended bypass rules so a future v2rayN update does not leave the configuration ambiguous.