Gemini CLIをv2rayNで使う設定方法｜接続トラブル対策

Gemini CLIとプロキシ設定の考え方

Gemini CLI は、ブラウザで開くチャット画面ではなく、ターミナルから Gemini の機能を呼び出すためのコマンドラインツールです。コードの確認、文章の整理、ログの要約、開発中の質問などをターミナル内で完結できる一方、通信は通常のブラウザとは別の経路を使います。そのため、ブラウザが正常に表示できていても、Gemini CLI だけが接続エラーになることがあります。

v2rayN を使う場合に重要なのは、ノードを登録することと、ターミナルの通信をプロキシへ向けることを分けて考えることです。v2rayN が起動していてノードが選択されていても、Gemini CLI のプロセスがプロキシ設定を読まなければ、通信は直接接続のままです。最初から複雑なルーティングや TUN に進むより、まず v2rayN のローカルプロキシポートを確認し、環境変数で Gemini CLI に明示する方が切り分けやすくなります。

また、Gemini CLI の利用にはサービス側のアカウント、認証方法、API キーやログイン状態が関係します。v2rayN は通信経路を整えるツールであり、認証情報を発行したり、利用地域やアカウントの制限を変更したりするものではありません。通信経路の問題と認証の問題を混同しないことが、最初のポイントです。

v2rayNでノードとローカルポートを準備する

まず v2rayN を起動し、サブスクリプションまたは単一ノードを登録します。サブスクリプションを使う場合は、提供元から受け取った URL を正確にコピーして追加し、更新後にノード一覧が表示されることを確認してください。単一の vmess://、vless://、trojan:// などの共有リンクしかない場合は、対応する手動インポートを使います。ノードが一覧にない状態では、Gemini CLI 側の設定を調整しても接続確認ができません。

次に、v2rayN の設定画面でローカルの HTTP プロキシまたは SOCKS プロキシのポートを確認します。環境によって番号は異なるため、例としてよく見かけるポート番号を決め打ちせず、実際に表示されている値を使ってください。HTTP プロキシが 127.0.0.1:10809、SOCKS プロキシが 127.0.0.1:10808 と表示されているなら、それぞれ別のプロキシとして扱います。

最初の確認では、v2rayN で利用可能なノードを1つ選び、システムプロキシを有効にします。ブラウザで通常のページを開けるかを確認し、v2rayN の基本接続が成功している状態を作ってください。ブラウザも開けない場合は、Gemini CLI の設定へ進まず、ノードの有効期限、サブスクリプションの更新状態、時刻設定、他の VPN やプロキシソフトとの競合を先に調べます。

ターミナルにプロキシ環境変数を設定する

Gemini CLI にプロキシを使わせる一般的な方法は、起動するターミナルの環境変数にプロキシアドレスを設定することです。HTTP 系の通信を受け付けるローカルポートを使う場合は、HTTP_PROXY と HTTPS_PROXY を同じ値に設定します。アドレスは通常 http://127.0.0.1:ポート番号 の形式です。SOCKS ポートを使う場合は、利用する CLI やランタイムが SOCKS をサポートしているかを先に確認してください。

Windows の PowerShell では、現在開いているセッションだけに環境変数を設定できます。たとえば v2rayN の HTTP ポートが 10809 なら、$env:HTTP_PROXY="http://127.0.0.1:10809" と $env:HTTPS_PROXY="http://127.0.0.1:10809" を順に実行します。設定後に同じウィンドウから Gemini CLI を起動してください。別の PowerShell を開くと、この一時設定は引き継がれない場合があります。

macOS や Linux の bash、zsh では、export HTTP_PROXY=http://127.0.0.1:10809 と export HTTPS_PROXY=http://127.0.0.1:10809 のように設定します。大文字の変数を読まないツールもあるため、必要に応じて http_proxy と https_proxy も同じ値にします。設定を常用する場合はシェルの設定ファイルへ追加できますが、共有 PC や複数のネットワークを使う端末では、まず一時設定で動作を確認する方が安全です。

プロキシを解除するときは、PowerShell なら Remove-Item Env:HTTP_PROXY と Remove-Item Env:HTTPS_PROXY、bash や zsh なら unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy を使います。プロキシ環境変数を残したまま v2rayN を終了すると、別のコマンドラインツールまで接続できなくなることがあります。検証が終わったら、現在のシェルにどの設定が残っているか確認してください。

実際の設定手順を順番に実行する

v2rayN を起動し、サブスクリプションを更新するか、利用可能なノードを手動で追加する。
ノードを選択し、v2rayN の接続状態が正常であることを確認する。
設定画面で HTTP プロキシまたは SOCKS プロキシのアドレスとポートを確認する。
PowerShell、bash、zsh など、Gemini CLI を実行するターミナルを新しく開く。
利用するプロキシポートに合わせて HTTP_PROXY と HTTPS_PROXY を設定する。
そのターミナルから Gemini CLI を起動し、ログインまたは認証処理を実行する。
簡単な質問を送信し、応答が返ること、通信が途中で止まらないことを確認する。

この順番では、v2rayN、ローカルポート、環境変数、Gemini CLI の認証を一つずつ確認できます。いきなり TUN を有効にしたり、複数の環境変数を無差別に追加したりしないでください。最初の成功条件をシンプルにしておくと、後で常用設定に移行するときも、どの変更が効果を与えたのか判断しやすくなります。

コマンドを実行しても反応がない場合は、ターミナルを閉じて新しいウィンドウを開くことも試します。環境変数は、設定した後に起動したプロセスへ渡されるため、すでに起動中のターミナルやエディター内蔵ターミナルに反映されないことがあります。IDE のターミナルを使う場合は、IDE 自体を再起動する必要があるケースもあります。

接続エラーを切り分ける

Gemini CLI のエラーは、まず通信、プロキシ、認証の3つに分けます。ブラウザは開けるのに CLI だけ失敗するなら、環境変数の名前、ポート番号、プロキシ形式、CLI を起動したターミナルの種類を確認します。特に HTTPS_PROXY の値を間違えたり、v2rayN で設定されていないポートを指定したりすると、接続拒否やタイムアウトが起きます。

「接続が拒否された」「connection refused」と表示される場合は、指定先のローカルポートで待ち受けているプロキシがない可能性が高いです。v2rayN が終了していないか、ポート番号を別の設定値と取り違えていないか、ローカルアドレスを 127.0.0.1 としているかを確認します。「タイムアウト」なら、ノードの経路、サブスクリプションの有効性、現在のネットワーク、DNS やファイアウォールも候補になります。

認証画面までは進むのに権限エラーや API エラーになる場合は、プロキシが完全に失敗しているとは限りません。ログイン状態、使用しているアカウント、API キーの設定、サービス側の利用条件を確認してください。認証情報を環境変数やコマンド履歴に残す場合は、第三者に見られないように管理し、公開リポジトリや画面共有へ貼り付けないことが大切です。

ブラウザ、別のターミナル、別のノードで結果を比較するのも有効です。ブラウザと CLI の両方が失敗するなら、v2rayN やノード側を優先して調べます。ブラウザだけ成功するなら、CLI が環境変数を読んでいるか、HTTP と SOCKS の形式が合っているかを確認します。別ノードだけ成功するなら、Gemini CLI の設定ではなく、元のノードの品質や経路に問題がある可能性があります。

安定利用のための見直しポイント

動作確認が終わったら、毎回手動で環境変数を入力する方法を続けるか、専用の起動用スクリプトやシェル設定へ移すかを決めます。個人の端末で常用する場合でも、プロキシを使うコマンドと直接接続するコマンドを分けられる状態にしておくと、別の開発作業への影響を減らせます。すべての通信を常に TUN へ流す必要はなく、Gemini CLI だけに環境変数を渡す方法にも利点があります。

通信が不安定になったときは、ノードを何度も切り替える前に、v2rayN の接続状態、システム時刻、サブスクリプションの更新日時、ターミナルの環境変数を順番に確認してください。クライアントを再インストールしても、期限切れのサブスクリプションや誤ったポート番号は直りません。逆に、最新の v2rayN でも設定を引き継いだ古い値が残っていると、問題が続くことがあります。

v2rayN は使い方ガイドも参照しながら、まず通常のプロキシ接続を安定させるのがおすすめです。Gemini CLI の認証情報は公式の案内に従って管理し、利用地域やサービスの規約、現地の法令も確認してください。経路を正しく設定しても、アカウント側の制限やサービス障害まで解決できるわけではありません。