Gemini CLIをv2rayNで使う設定方法｜端末プロキシ入門
Gemini CLI と端末プロキシの関係
Gemini CLI は、ブラウザの画面ではなくターミナルから Gemini の機能を利用するためのコマンドラインツールです。ブラウザでページを開ける環境でも、Gemini CLI だけが接続できないことがあります。理由は、ブラウザと CLI が同じプロキシ設定を自動的に使うとは限らないためです。
v2rayN でノードを選択し、システムプロキシを有効にしても、すべてのターミナル通信が必ず同じ経路を通るわけではありません。CLI が参照する環境変数、通信ライブラリの仕様、認証方式、DNS の解決方法などが関係します。そのため「v2rayN は接続済みなのに Gemini CLI は失敗する」という場合は、ノードの障害と端末側のプロキシ設定を分けて確認することが大切です。
最初から複雑なルーティングや TUN モードを設定する必要はありません。まずは v2rayN でノードが正常に使えること、次にターミナルへプロキシ情報を渡すこと、最後に Gemini CLI の認証と API 通信を確認する、という順番で進めます。
事前に確認する環境
この設定は、Windows、macOS、Linux のデスクトップで v2rayN を使い、同じ端末上のターミナルから Gemini CLI を実行する場合を想定しています。v2rayN は起動しているか、利用可能なノードが一覧にあるか、サブスクリプションが期限切れになっていないかを先に確認してください。
また、Gemini CLI のインストールとログインがすでに完了しているかも確認します。初めて導入する場合、Node.js などの実行環境や CLI 本体のバージョンが原因で起動できないことがあります。プロキシ設定を調べる前に、プロキシを使わない状態でも CLI が起動し、認証画面またはヘルプ表示まで進めるかを見ておくと、問題の範囲を狭めやすくなります。
- v2rayN が起動し、利用可能なノードが選択されている
- サブスクリプションまたは単一ノードの登録が完了している
- ターミナルで Gemini CLI のコマンドが認識される
- 端末の日時、タイムゾーン、証明書検証に大きな問題がない
- 別の VPN やプロキシツールを同時に動かしていない
特に最後の点は重要です。複数のプロキシアプリを重ねると、ポート番号や環境変数が競合し、接続できたりできなかったりする状態になりがちです。最初の動作確認では、v2rayN 以外のプロキシ機能を停止してください。
v2rayN でノードを準備する
v2rayN を開いたら、まず利用するノードを1つ選びます。最初の確認では、最速のノードを探すよりも、遅延が安定していて失敗履歴の少ないノードを選ぶ方が分かりやすいです。ノードを選択しただけでは通信がプロキシ経由になるとは限らないため、接続状態とプロキシモードを別々に見ます。
Windows では、v2rayN のメニューからシステムプロキシを有効にすると、OS のプロキシ設定を参照するアプリが v2rayN のローカルポートを使えるようになります。macOS や Linux でも、v2rayN の画面に表示される HTTP または SOCKS のローカルポートを確認できます。ポート番号は環境や設定によって異なるため、固定値を思い込まず、実際の v2rayN の設定画面を確認してください。
ブラウザで通常のウェブページを開き、v2rayN の接続ログに通信が表示されるかを確認します。ブラウザが正常に動作しない段階で Gemini CLI の設定を始めると、CLI、ノード、プロキシモードの問題が混ざります。まず GUI アプリで基準線を作ることが、最も効率的な切り分けです。
ターミナルにプロキシを設定する
Gemini CLI などのコマンドラインツールでは、ターミナルの環境変数にプロキシを指定する方法がよく使われます。v2rayN のローカル HTTP ポートを使う場合は、端末の環境に HTTP_PROXY と HTTPS_PROXY を設定します。実際のホスト名は通常ローカルの 127.0.0.1、ポート番号は v2rayN の画面に表示された HTTP ポートです。
一時的な確認では、現在開いているターミナルだけに環境変数を設定します。Windows の PowerShell、macOS や Linux のシェルでは記述方法が異なるため、使っているシェルの構文に合わせてください。設定後に同じターミナルで Gemini CLI を起動し、別のターミナルには自動的に引き継がれないことも覚えておきましょう。
SOCKS ポートを使う場合は、CLI や基礎ライブラリが SOCKS プロキシに対応しているか確認が必要です。対応していないツールへ無理に SOCKS の URL を渡すと、設定が無視されたり、名前解決だけが失敗したりします。初心者はまず v2rayN の HTTP ポートを使い、HTTP 経由で接続できることを確認してから、必要に応じて SOCKS を検討するのが安全です。
プロキシを常時使いたくない場合は、環境変数を永続設定にせず、Gemini CLI を使うターミナルセッションだけで有効にします。これにより、社内サイトやローカル開発環境まで意図せずプロキシ経由になることを防げます。API キーや認証情報を含むコマンドを、共有端末の履歴や公開ログへ残さないことにも注意してください。
実際の確認手順
- v2rayN を起動し、利用可能なノードを1つ選択する
- v2rayN のローカル HTTP ポート番号を設定画面で確認する
- システムプロキシを有効にし、ブラウザで通常のページを開く
- Gemini CLI を実行するターミナルだけに HTTP プロキシ環境変数を設定する
- 同じターミナルで CLI のヘルプ表示、ログイン、または簡単な問い合わせを試す
- 成功したら、必要に応じて永続設定やプロジェクト単位の設定へ進む
この手順では、各段階で結果を記録します。ブラウザが開けないなら v2rayN、ブラウザは開けるが CLI だけ失敗するなら環境変数または CLI 側、認証だけ失敗するならアカウントや API 設定を優先して調べます。すべてを一度に変更せず、1項目ずつ確認するのがポイントです。
プロキシ設定後に CLI が突然動いた場合でも、設定内容をメモしておくと次回の再現が簡単です。ホスト、ポート、使用したシェル、v2rayN のモードを控えておけば、パソコンを再起動したあとや別の端末へ移行したあとも、同じ条件で確認できます。
接続できないときの切り分け
最初に確認するのは、v2rayN のノードが本当に通信可能かどうかです。v2rayN が起動していても、選択中のノードが失効している、サブスクリプションが古い、サーバーが一時停止している、といった可能性があります。別の利用可能なノードへ切り替え、ブラウザの接続を再確認してください。
次に、環境変数の名前とポート番号を確認します。HTTP_PROXY と HTTPS_PROXY の大文字・小文字はツールによって扱いが異なる場合があります。必要に応じて小文字の http_proxy と https_proxy も確認します。ただし、複数の値を同時に残すと、どの設定が採用されたか分かりにくくなるため、不要な古い値は削除してください。
ブラウザは成功するのに Gemini CLI だけ失敗する場合、CLI が環境変数を読んでいない可能性があります。CLI のヘルプや公式ドキュメントでプロキシオプションの有無を確認し、Node.js 側の通信ライブラリがプロキシへ対応しているかも調べます。環境変数を設定したターミナルとは別のウィンドウで実行していないか、設定後に新しいプロセスを起動したかも確認しましょう。
エラーがタイムアウトなら、ノード、ローカルポート、ネットワーク経路を優先します。証明書や TLS に関するエラーなら、システム時刻、古いランタイム、セキュリティソフトによる HTTPS 検査を確認します。認証エラーなら、プロキシを何度も切り替えるより、アカウント、API キー、ログイン状態、利用地域やサービス側の条件を確認する方が適切です。
TUN モードを使うべき場面
システムプロキシと環境変数を設定しても、Gemini CLI の通信がどうしてもプロキシを通らない場合は、v2rayN の TUN モードを検討できます。TUN はより広い範囲の端末通信を接管するため、アプリが通常のプロキシ設定を無視するケースに有効です。
ただし、TUN を最初から有効にすることはおすすめしません。管理者権限、仮想ネットワークアダプター、DNS、他の VPN との競合など、確認すべき項目が増えるからです。まずシステムプロキシと CLI の環境変数で成功するかを試し、それでも対象通信だけが漏れると分かった場合に、TUN を段階的に使ってください。
TUN に切り替える前には、他の VPN、ゲーム用ネットワークツール、企業のセキュリティクライアントなどを一時停止できるか確認します。切り替え後はブラウザだけでなく、Gemini CLI と通常のローカル開発作業の両方を試し、必要な通信までプロキシへ送られていないかを見ます。目的は速度を上げることではなく、対象アプリの通信経路を安定させることです。
よくある質問
v2rayN でシステムプロキシをオンにすれば、Gemini CLI も自動で使えますか？
必ず使えるとは限りません。CLI が OS のプロキシ設定を参照しない場合があるため、まずターミナルの HTTP_PROXY と HTTPS_PROXY を確認してください。
HTTP ポートと SOCKS ポートのどちらを選べばよいですか？
対応状況が分からない初心者は、まず v2rayN に表示される HTTP ポートを試すのが無難です。CLI や実行環境が SOCKS に対応していることを確認できた場合のみ、SOCKS ポートへ切り替えます。
ブラウザは開けるのに Gemini CLI だけタイムアウトします。何を疑うべきですか？
プロキシ環境変数の設定先、ポート番号、CLI の起動プロセス、ランタイムのプロキシ対応を優先して確認します。ノードを何度も変更する前に、同じターミナルから実行しているかを見直してください。
TUN を使えば必ず解決しますか？
いいえ。TUN は通信経路の問題には有効ですが、認証失敗、期限切れのノード、古い CLI、サービス側の制限までは解決しません。原因を分類してから使うことが大切です。
Gemini CLI と v2rayN の組み合わせでは、「ノードが使える」「ターミナルがプロキシを認識する」「CLI の認証が正常」という3つを順番に確認します。設定を一度に複雑にするより、システムプロキシ、環境変数、必要なら TUN という段階を守る方が、再現性のある環境を作りやすくなります。