仕組み解説 読了目安:13分

Gemini CLIをClash Vergeで使う設定方法と安定接続ガイド

Gemini CLIを試したい開発者向けに、接続エラーやログイン失敗が起きたときの確認ポイントを整理しました。Clash Vergeでプロファイルを読み込み、必要な通信だけを適切に振り分ける方法を、実際の利用手順に沿って紹介します。

Gemini CLIが必要とする通信とClash Vergeの役割

Gemini CLIは、ターミナルから自然言語でコードの説明を求めたり、プロジェクト内のファイルを確認したり、生成結果を受け取ったりするための開発者向けCLIツールです。ローカルでコマンドを実行しますが、モデルへの問い合わせや認証処理はGoogle側のサービスと通信して行われます。そのため、CLI本体が正常にインストールされていても、認証エンドポイントへ到達できなければログイン失敗、接続タイムアウト、応答待ちのまま停止するといった症状が発生します。

Clash Vergeの役割は、Gemini CLI専用の機能を追加することではありません。Clash Vergeに読み込んだプロファイルとmihomo系コアが、OSやアプリケーションから出る通信を受け取り、ルールに従ってDIRECTまたはプロキシグループへ振り分けます。ここで大切なのは、ブラウザだけがプロキシを利用できても、ターミナルで起動したCLIまで同じ経路を使うとは限らない点です。

一般的なCLIツールは、環境変数の HTTP_PROXY、HTTPS_PROXY、ALL_PROXY を参照する方式と、OSのシステムプロキシを参照する方式に分かれます。さらに、TUNモードを有効にすると、プロキシ設定に対応していないプロセスも仮想ネットワークインターフェース経由で処理できます。まずは必要な範囲を見極め、システムプロキシ、環境変数、TUNの順に確認するのが安全です。

基本方針:Gemini CLIの問題をClash Vergeだけの障害と決めつけず、認証状態、CLIのプロキシ設定、Clashのルール判定、実際の接続ログを分けて確認してください。どの層で止まっているかが分かれば、設定を必要以上に変更せずに済みます。

事前準備:Clash Vergeとプロファイルを整える

最初にClash Vergeを起動し、使用するプロファイルが正常に読み込まれていることを確認します。サブスクリプションを登録する場合は、設定画面で購読URLを追加し、取得後に生成されたプロファイルを選択します。プロファイル名が表示されていても、YAMLの解析に失敗していたり、プロキシグループが空だったりする場合は通信テストへ進まないでください。

  1. Clash Vergeを起動し、プロファイル一覧で利用する設定を選択する。
  2. プロファイルの更新を実行し、ノードとプロキシグループが表示されることを確認する。
  3. プロキシ画面で、利用可能なノードを1つ選択する。自動選択グループを使う場合は、URL Testの結果だけでなく実際の接続も確認する。
  4. モードが通常のルールモードになっていることを確認する。GlobalやDirectに切り替えたままだと、意図したルール検証ができない。
  5. まずシステムプロキシをオンにし、ブラウザで一般的なHTTPSサイトを開いてClashの接続ログに記録が出るか確認する。

プロファイル内のルールは、プロキシグループの構成と同じくらい重要です。Gemini CLIの通信先をプロキシへ送るルールが存在しない場合、末尾の MATCH,DIRECT によって直接接続されることがあります。逆に、広すぎるルールを先頭へ追加すると、パッケージマネージャーや社内サービスまで同じプロキシに送られ、別の障害を生む可能性があります。

設定箇所 確認する内容 よくある結果
プロファイル YAML解析、ノード、プロキシグループ 読み込み失敗、グループが空
プロキシ画面 選択中のノードと遅延、接続可否 タイムアウト、ノード障害
設定画面 システムプロキシ、TUN、コア状態 CLIだけが直接接続する
ログ画面 対象ドメイン、ルール、出口グループ 想定外のDIRECT判定

実際に設定する:CLIへプロキシ経路を渡す

ここでは、まずターミナル単位でプロキシを指定し、その後にClash Vergeのログで判定を確認します。ClashのHTTPポートやSOCKSポートはプロファイルによって異なるため、画面に表示されている値を使ってください。典型的な初期値としてHTTPプロキシが 7890、SOCKS5が 7891 のことはありますが、固定値とは限りません。

WindowsのPowerShellでは、次のように一時的な環境変数を設定できます。ターミナルを閉じれば解除されるため、まず動作確認をする用途に向いています。

$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:ALL_PROXY="socks5://127.0.0.1:7891"

macOSやLinuxのシェルでは、次の形式を使います。

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=socks5://127.0.0.1:7891

すべてのCLIが3つの変数を同じように扱うわけではありません。HTTPS通信でもプロキシ変数の名前は通常 HTTPS_PROXY ですが、値にはHTTP CONNECTを受け付けるClashのHTTPポートを指定する構成がよく使われます。一方、SOCKS5ポートを設定する場合は、ツールがSOCKS5をサポートしているかを確認してください。対応していないツールにSOCKS5のURLを渡すと、プロキシが存在しているのに接続できない状態になります。

認証方法やCLIのサブコマンドは、インストールしているGemini CLIのバージョンによって変わることがあります。ログインコマンドを実行する前に、ヘルプで現在のオプションを確認してください。

gemini --help
gemini --version

環境変数を設定した後にログインまたは簡単なプロンプトを実行し、Clash Vergeのログで通信を探します。ログに対象ドメイン、使用されたルール、選択されたプロキシグループが表示されれば、CLIの通信がClashへ渡っています。ログに何も出ない場合は、CLIが別のプロセス環境で起動している、環境変数名が認識されていない、またはアプリケーションが独自のネットワーク処理を使っている可能性があります。

注意:APIキーや認証トークンをYAML、シェル履歴、共有ログへ貼り付けないでください。接続確認のために環境変数を表示するときも、値そのものを画面へ出さない方法を選び、確認後は一時変数を解除してください。

通信を必要な範囲だけ振り分けるルール設計

常に全通信をプロキシへ送る設定は簡単ですが、開発環境では副作用があります。社内Git、ローカルパッケージレジストリ、LAN上のデータベース、localhostの開発サーバーまでプロキシへ送ると、名前解決やアクセス制御が壊れることがあります。Gemini CLIに関係する外部通信だけを対象にするなら、プロファイルのルールは具体的なドメインから始め、最後に既存のルールへ戻すのが基本です。

ただし、認証やAPIの通信先はサービス構成やCLIのバージョンによって変わる可能性があります。特定のドメイン名を推測して大量に追加するのではなく、実際のClashログで確認したホスト名を対象にしてください。認証リダイレクトがブラウザへ渡される構成では、ブラウザ側のアクセスも同じルールで処理される必要があります。

rules:
  - DOMAIN-SUFFIX,googleapis.com,Gemini
  - DOMAIN-SUFFIX,generativelanguage.googleapis.com,Gemini
  - DOMAIN-SUFFIX,google.com,Gemini
  - DOMAIN,localhost,DIRECT
  - IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve

上の例は考え方を示すための最小例です。すでに購読設定でルールが生成されている場合は、同じドメインのルールを重複して追加しないでください。Clashのルールは上から順に評価され、最初に一致した行で処理が決まります。追加ルールを末尾へ置くと、先にある MATCH,DIRECT に到達する前に評価されるとは限らないため、ルールプロバイダーや覆写機能を使う場合も挿入位置を確認します。

DNS設定も切り分けの対象です。Fake-IPを使っている場合、通常のHTTPS通信ではドメインルールを適用しやすくなりますが、LANサービスや特殊な認証フローが影響を受けることがあります。Clash Vergeで接続先が想定外のIPとして表示される場合は、Fake-IPフィルター、DNSモード、TUNのDNS引き受け設定を確認し、いきなり全体をRedir-Hostへ変更するのではなく対象ドメインだけを例外化してください。

ログイン失敗と接続エラーを切り分ける

Gemini CLIのエラーは、認証情報の問題とネットワークの問題が似た表示になることがあります。まずエラーが発生するタイミングを記録してください。ログイン画面を開く前にタイムアウトするのか、ブラウザ認証後にCLIへ戻れないのか、ログイン後のプロンプト送信だけが失敗するのかによって確認箇所が変わります。

  • ターミナル起動直後に接続できない:Clash Vergeのコアが停止していないか、選択中のノードが有効か、CLIへ環境変数が渡っているかを確認します。
  • ブラウザ認証は成功するがCLIで失敗する:認証後のリダイレクト、ローカルコールバックポート、ブラウザとターミナルで異なるネットワーク経路を確認します。ブラウザだけがプロキシを使い、CLIが直接接続しているケースもあります。
  • ログイン後のAPI呼び出しだけ失敗する:認証とモデル通信で利用されるホストが異なる可能性があります。Clashログで失敗時刻の通信を探し、DIRECT判定、DNSエラー、TLSエラー、プロキシ拒否を区別します。
  • 応答が途中で止まる:ノードの帯域、パケットロス、接続維持時間、HTTPプロキシの処理を疑います。遅延テストの数値だけでなく、別ノードと短いリクエストを比較してください。
  • 403や429が返る:これはClashの接続失敗とは限りません。アカウント権限、利用制限、リクエスト頻度、モデル指定などサービス側の条件を確認します。

ログを読むときは、単に「接続があった」かどうかではなく、ルール名と出口ノードを見ます。認証画面が開いていても、API送信が別のルールでDIRECTになっていれば、処理の途中で失敗する可能性があります。逆に、ClashログにTLSハンドシェイクまで記録されていてサービス側からエラーが返っているなら、プロキシの有無よりアカウントやCLIの設定を優先して調べます。

症状 最初に見る場所 対処の方向
Clashログに記録がない 環境変数、TUN、CLIの起動シェル CLIへプロキシ経路を渡す
ルールがDIRECTになる 接続ログとルールの順序 対象ドメインのルール位置を修正
DNSエラーになる DNSモード、Fake-IP、DNSログ DNS経路と例外設定を確認
認証後に戻れない ブラウザ、コールバック、ファイアウォール ローカル接続をDIRECTにする
API制限のエラー CLIの表示、アカウント状態 サービス側の利用条件を確認

安定運用のための確認項目

接続できた後も、毎回TUNをオンにしたり、広いルールを追加したりする必要はありません。まずはGemini CLIを使うターミナルだけに環境変数を設定し、動作が安定したら必要に応じてシステムプロキシやTUNへ広げます。設定範囲を小さく保つと、他の開発ツールが突然別経路へ変わるリスクを減らせます。

自動起動を使う場合は、OS起動直後にClash Vergeのコア、プロファイル、ノード接続がすべて準備できるとは限りません。ログイン直後だけCLIが失敗するなら、Clash Vergeが起動しているかだけでなく、プロファイルが選択済みで、プロキシグループに実際のノードが設定されているかを確認します。自動更新直後に不調になった場合は、プロファイルの差分、コアのバージョン、ルールプロバイダーの更新時刻も記録してください。

また、プロキシを使うことで問題が必ず解決するわけではありません。サービス側の障害、アカウントの利用制限、CLIの互換性、システム時刻のずれ、企業ネットワークのTLS検査など、Clashの外側に原因がある場合もあります。次の順番で再テストすると、変更を最小限にできます。

  1. Clash Vergeでノードを1つ固定し、接続ログが出る状態にする。
  2. CLIのバージョンとヘルプを確認し、不要な認証情報を削除せずに現在の設定を記録する。
  3. プロキシ環境変数を設定した新しいターミナルで、短い接続テストを実行する。
  4. 認証、モデルへの問い合わせ、長めの応答の3段階を個別に確認する。
  5. 安定後に自動選択グループ、TUN、追加ルールを1項目ずつ戻す。

この手順なら、Gemini CLIの認証経路とAPI通信をClash Vergeのログで追跡しながら、必要な通信だけをプロキシへ送れます。設定ファイルを大きく書き換える前に、CLIのプロキシ認識、ルール判定、DNS、ノード品質を順番に分離して確認することが、最も再現性の高い解決方法です。

クライアントをダウンロード