Gemini CLIをv2rayNで使う方法｜中国からの接続設定ガイド

Gemini CLIを中国から試したい場合、単にコマンドをインストールするだけでは安定して動作しないことがあります。Google側のサービス到達性、v2rayNのアクティブサーバー、ローカルプロキシポート、ターミナルの環境変数、Gemini CLIの認証方式がすべて正しくつながって、はじめてコマンドラインからモデルへリクエストを送れます。ブラウザーで別のサイトが開くからといって、ターミナル上のGemini CLIも自動的にプロキシを使うとは限りません。

この記事では、Windowsのv2rayNを中心に、サブスクリプションの登録、Xrayコアとノードの選択、システムプロキシまたはTUNモードの使い分け、ターミナルへのプロキシ反映、Gemini CLIの認証、エラー発生時の確認順序を説明します。macOSやLinuxでも考え方は共通ですが、環境変数の設定方法とプロキシの引き継ぎ方はシェルごとに異なります。なお、地域、Googleアカウント、APIの提供条件、利用規約によって利用可否は変わるため、通信経路を用意することが利用資格を保証するわけではありません。

Gemini CLIとv2rayNの役割を分けて理解する

Gemini CLIは、ターミナルからGeminiのモデルへプロンプトを送信し、回答を表示したり、ローカルの作業ディレクトリで開発支援を行ったりするコマンドラインツールです。一方、v2rayNはアプリケーションそのものではなく、Xrayなどのコアを使ってローカルのプロキシ入口を開き、指定したノードへ通信を転送するクライアントです。したがって、Gemini CLIの画面にエラーが出た場合でも、CLI本体、認証、v2rayN、ノード、DNS、または現在のネットワークのどこに問題があるかを分けて確認する必要があります。

v2rayNでは、選択したノードを「アクティブサーバー」に設定するだけでは、すべてのアプリが自動的にその経路を使うとは限りません。Windowsでは「システムプロキシを有効化」を使う方法が簡単ですが、ターミナルやCLIがシステムプロキシを参照するかどうかは、使用するランタイムやHTTPライブラリに依存します。より確実にするには、Gemini CLIを起動するシェルでHTTP_PROXY、HTTPS_PROXY、必要に応じてALL_PROXYを設定します。

v2rayNのローカルポート番号は環境によって異なります。よく使われる例では、HTTPポートが10809、SOCKSポートが10808ですが、設定画面で実際の値を確認してください。別のアプリや過去の設定と競合している場合、ポート番号を変更している場合、HTTPとSOCKSを取り違えている場合は、v2rayNが接続できていてもGemini CLIだけが通信できません。

事前準備とクライアント・コアの選び方

最初に、v2rayNの対応するデスクトップ版を公式のインストールページから取得し、OSとCPUアーキテクチャに合うパッケージを選びます。Windowsでは、解凍後に主プログラムを起動する構成が一般的です。macOSやLinuxでは、実行権限、システムのネットワーク設定、ファイアウォールの許可が必要になる場合があります。インストール先や実行ファイル名は配布形式によって異なるため、ダウンロード後に不明な実行ファイルを追加するのではなく、正規のパッケージに含まれるものを使用してください。

Gemini CLI用のノードを選ぶときは、表示名や地域名だけで判断しないでください。まず現在のネットワークからリモートポートへ到達できること、次にv2rayNの遅延テストや実際のWebアクセスが安定すること、最後にターミナルからHTTPS接続できることを確認します。Web閲覧が軽快でも、長時間のAPI通信、ストリーミング応答、複数回の認証リクエストで切断されるノードがあります。短い疎通確認と、数分間の実際のCLI利用は別のテストとして扱います。

最初の検証では、いきなりTUNモードを有効にするより、v2rayNのHTTPプロキシを明示してGemini CLIだけを通す構成が扱いやすいでしょう。ブラウザー、開発ツール、パッケージマネージャーまで同時に経路を変えると、どのアプリの通信が失敗しているか分かりにくくなります。HTTPプロキシで正常に動作した後、必要であればTUNモードへ広げます。

v2rayNにサブスクリプションとアクティブノードを設定する

サブスクリプションURLは、契約先や管理者から提供されたものだけを使用してください。URLには認証情報が含まれることがあるため、公開チャット、スクリーンショット、ログ共有サービスに貼り付けないでください。登録後はURLを保存しただけで完了したと考えず、更新が成功し、ノード一覧に最新の内容が表示されていることを確認します。

1. サブスク登録

   v2rayNのメイン画面で「サブスクリプショングループ」または同等の管理画面を開き、「追加」から提供されたURLを保存します。表示名は用途が分かる短い名前にします。

2. 内容を更新

   登録したグループを選び、更新操作を実行します。ノード数、更新時刻、エラー表示を確認し、空のグループや古いグループを選択したままにしないでください。

3. コアを確認

   「設定」→「パラメータ設定」などのコア設定で、使用するXrayコアが存在し、対象ノードのプロトコルと互換性があることを確認します。

4. ノードを有効化

   ノード一覧から1つを選択し、「アクティブサーバーに設定」などの操作を実行します。行をクリックしただけでは、通信経路が切り替わらないことがあります。

5. ポートを記録

   「設定」→「HTTPポート」「SOCKSポート」またはローカルポート欄を開き、実際の待受番号を記録します。以下のコマンド例は、HTTPが10809の場合の例です。

システムプロキシを使う場合は、v2rayNの「システムプロキシを有効化」を実行してから、通常のブラウザーでHTTPSサイトを確認します。ただし、ブラウザーが開いてもGemini CLIが同じプロキシを使うとは限りません。ターミナルから明示する場合、PowerShellでは次のように設定します。

$env:HTTP_PROXY="http://127.0.0.1:10809"
$env:HTTPS_PROXY="http://127.0.0.1:10809"
$env:ALL_PROXY="http://127.0.0.1:10809"

macOSまたはLinuxのbash、zshでは次を使います。

export HTTP_PROXY=http://127.0.0.1:10809
export HTTPS_PROXY=http://127.0.0.1:10809
export ALL_PROXY=http://127.0.0.1:10809

この設定は、実行したターミナルのセッションにだけ適用されます。新しいターミナルを開いた場合は再設定が必要です。恒久化する場合はシェルの設定ファイルへ追加できますが、共有パソコンや管理された開発環境では、不要なアプリまで同じプロキシを使わないよう注意してください。APIキーや認証情報を環境変数へ保存する場合も、履歴ファイルやプロセス一覧に残る可能性を確認します。

Gemini CLIを導入し、認証方式を選ぶ

Gemini CLIの導入方法やコマンド名は、公開されているリリースと実行環境によって変わることがあります。まず公式ドキュメントに記載された現在のインストール手順を確認し、Node.jsなどの前提ランタイムが要求される場合は、対応する安定版を用意します。古い記事のコマンドをそのまま使うと、パッケージ名の変更、認証フローの変更、サポートされるモデル名の変更によって、インストール後に起動できないことがあります。

認証には大きく分けて、ブラウザーを使ったアカウント認証と、APIキーを環境変数で渡す方式があります。どちらを利用できるかは、Google側の提供条件、アカウント種別、地域、CLIのバージョンに依存します。ブラウザー認証を選ぶ場合は、認証画面が開く通信も同じプロキシ経路を通る必要があります。認証URLはターミナルに表示されても、ブラウザーが直接接続しているとコールバックやトークン取得で失敗することがあります。

APIキー方式では、キーをコマンドラインの引数へ直接書くより、環境変数を使う方が安全です。変数名はCLIの公式説明に合わせてください。サービスによってはGEMINI_API_KEY、別の実装ではGoogle AI関連の別名が使われる場合があるため、推測で複数のキーを設定するのではなく、現在のCLIが認識する変数を確認します。次の例は変数の考え方を示すもので、実際のキー文字列は入力しません。

# PowerShellの例
$env:GEMINI_API_KEY="ここに有効なAPIキーを設定"
gemini

APIキーはサブスクリプションURLと同じく秘密情報です。記事、画面共有、シェル履歴、CIログへ記録しないでください。キーを一度でも公開した可能性がある場合は、管理画面で無効化または再発行し、利用上限、請求設定、許可するAPI、必要に応じたIP制限を確認します。Gemini CLIがローカルファイルを扱う機能を持つ場合、作業ディレクトリに秘密鍵、設定ファイル、認証トークンを置いたまま実行しないことも重要です。

認証後の最初のテストは、長いプロンプトや大きなファイル操作ではなく、短い入力から始めます。応答が返れば、次に少し長い入力、最後に実際の開発作業へ進みます。これにより、認証成功、モデル応答、長時間接続、ローカルツール実行を別々に確認できます。

接続エラーを層ごとに切り分ける

エラーが出たときは、ノードを次々に交換する前に、最初に表示されたメッセージと発生した段階を記録します。サブスクリプション更新、v2rayNコア起動、ローカルポート接続、認証ページ、APIリクエスト、モデル応答は別の層です。たとえば、ECONNREFUSED 127.0.0.1:10809なら、遠隔ノードではなくローカルHTTPポートが待ち受けていない、または番号を間違えている可能性が高いでしょう。

接続確認用に、Windows PowerShellでは次のコマンドでローカルポートの待受状態を確認できます。

Test-NetConnection 127.0.0.1 -Port 10809

結果のTcpTestSucceededがFalseなら、Gemini CLIの認証やモデル名を調整する前に、v2rayNのHTTPポートを直す必要があります。ポートが開いていても遠隔ノードへ接続できるとは限らないため、次にv2rayNのログでコア起動、サーバー接続、TLSまたはRealityなどのハンドシェイクエラーを確認します。ログにノード側のエラーがなく、CLIだけが失敗する場合は、環境変数、証明書検証、ランタイムのプロキシ対応、認証情報へ調査範囲を絞れます。

安全に運用するための確認

Gemini CLIを日常的に使う場合、通信が通ることだけでなく、どのデータを送信しているかを確認してください。プロジェクト全体を無条件に読み込ませるのではなく、必要なファイルだけを対象にし、設定ファイル、秘密鍵、アクセストークン、顧客情報、社内資料を作業ディレクトリから分離します。CLIにファイル操作機能がある場合は、現在のディレクトリと許可範囲を毎回確認します。

v2rayN側では、不要なTUN転送や全アプリへのシステムプロキシを常時有効にしない方が管理しやすいでしょう。Gemini CLIを使う時間だけ環境変数を設定し、作業終了後にPowerShellではRemove-Item Env:HTTP_PROXY、Remove-Item Env:HTTPS_PROXY、Remove-Item Env:ALL_PROXYを実行できます。シェル設定ファイルへ追加した場合は、不要になった行を削除し、別の業務ツールが意図せず同じプロキシを使わないようにします。

最後に、安定性を判断するときは一度成功したかではなく、複数回の短いリクエスト、認証後の再起動、別ターミナルからの起動、数分間の応答継続を確認します。サブスクリプション更新後にアクティブノードが変わっていないか、v2rayNのローカルポートが変わっていないか、APIキーがログへ出ていないかも定期的に確認してください。必要なパッケージと現在の手順を確認したい場合は、使用ガイドを見ると、v2rayNの基本操作から再確認できます。