Gemini CLIをClashで安定利用する国内向け設定ガイド

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

Gemini CLIは、ターミナルからGeminiのモデルを利用してコードの説明、テスト作成、リファクタリング、ドキュメント生成などを行う開発者向けのコマンドラインツールです。一方、ClashはGemini CLIそのものを動かすソフトウェアではなく、アプリケーションが外部へ接続するときの通信経路を制御するプロキシクライアントです。役割を混同すると、認証エラーをClashの問題だと判断したり、ルール設定の不備をGemini CLIの不具合だと考えたりしやすくなります。

FlClash、Clash Verge Rev、Clash for Windowsなどのクライアントは、mihomoなどのカーネルを画面から操作します。カーネルはYAML設定を読み込み、mixed-portでHTTPおよびSOCKSの接続を待ち受け、rulesを上から順番に照合します。Gemini CLIは通常、ターミナルの環境変数に設定されたHTTPまたはHTTPSプロキシを利用するため、まずはシステム全体をTUNへ切り替えるより、ローカルプロキシを明示する方法から始めるのが安全です。

項目	担当するもの	確認する場所
Gemini CLI	コマンド入力、認証、AIモデルへのリクエスト、結果の表示	ターミナル、CLIの設定、環境変数
Clashクライアント	設定の追加、カーネルの起動、プロキシの選択、ログ表示	FlClashなどの画面
mihomoカーネル	DNS、ルール照合、プロキシ接続、ローカルポートの待ち受け	カーネルログ、設定ファイル
Googleの認証とAPI	アカウント、APIキー、クォータ、利用可能なモデルの判定	Gemini CLIまたはGoogle側の応答

Clash側の基本設定を準備する

まずFlClashなどのクライアントで、利用するサブスクリプションまたはローカルYAMLを読み込み、mihomoカーネルが正常に起動していることを確認します。設定画面で現在の混合ポートを確認してください。代表的な値は7890ですが、アプリケーションや既存設定によって異なります。ターミナルの環境変数へ入力するポートは、画面に表示されている実際の値を使う必要があります。

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

mixed-portはHTTPとSOCKS5の両方を受け付けるポートです。Gemini CLI側でHTTPプロキシとして指定する場合も、この混合ポートを使えます。external-controllerのポート、たとえば127.0.0.1:9090はクライアントがカーネルを管理するためのAPIポートであり、通常のWeb通信を送るプロキシポートではありません。両者を取り違えると、接続拒否や応答形式のエラーが発生します。

利用するプロキシグループを選ぶ

Clashの画面で、通常の「PROXY」「Proxy」などのプロキシグループに利用可能なノードが登録されているか確認します。ノードの遅延テストが成功しても、Gemini関連のHTTPS通信が必ず成功するとは限りません。接続先へのTLS通信、DNS解決、長時間のストリーミング応答が安定しているかを、ログと実際のCLI操作で確認してください。

ルールモードでは、設定の上にあるルールから順番に評価されます。特定のドメインをプロキシグループへ送るルールを追加する場合、広い範囲のルールより前に置くことが重要です。たとえば先にDOMAIN-SUFFIX,googleapis.com,DIRECTが存在すると、後から追加したプロキシ指定が適用されません。変更後は設定の検証を実行し、YAMLのインデントとグループ名の綴りを確認します。

rules:
  - DOMAIN-SUFFIX,googleapis.com,PROXY
  - DOMAIN-SUFFIX,google.com,PROXY
  - DOMAIN-SUFFIX,generativelanguage.googleapis.com,PROXY
  - MATCH,DIRECT

上の例で使っているPROXYは、実際の設定に存在するプロキシグループ名へ置き換えてください。サービスの接続先はクライアントのバージョン、認証方式、API経路によって異なる場合があります。ドメインを無制限に推測して追加するのではなく、Clashの接続ログに表示された宛先を確認し、必要なものだけをルールへ加えるのが適切です。

ターミナルからGemini CLIをClash経由にする

Clashが起動し、ノード選択も完了したら、Gemini CLIを実行するターミナルでプロキシ環境変数を設定します。HTTP、HTTPS、SOCKSのどれを利用できるかはCLIと実行環境によって異なるため、まずは混合ポートをHTTPプロキシとして指定する構成を試します。HTTPSサイトへ接続するときも、環境変数名は通常HTTPS_PROXYですが、値のスキームはhttp://になります。

# macOS / Linux / zsh / bash
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=http://127.0.0.1:7890

gemini

Windows PowerShellでは次のように設定します。設定はそのPowerShellウィンドウの間だけ有効です。永続化する前に、一時設定で通信を確認すると、別のアプリケーションへ意図せず影響を与えずに済みます。

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

gemini

接続を確認する実作業の手順

Clashクライアントを起動し、設定を読み込んでカーネルの状態が稼働中になっていることを確認します。
プロキシグループで利用するノードを選び、必要ならURLテストを実行します。
クライアントの接続ログを開き、混合ポートが127.0.0.1:7890で待ち受けていることを確認します。
新しいターミナルでHTTP_PROXYとHTTPS_PROXYを設定します。
Gemini CLIを起動し、認証または簡単な質問を実行します。
ログに対象ドメイン、使用したプロキシグループ、接続結果が表示されるか確認します。

CLIがプロキシ環境変数を認識しているかを分けて調べるには、まず一般的なHTTPS接続をテストします。次のコマンドはプロキシ経由でTLS接続を確立できるかを見るための例です。レスポンスの内容や認証情報は保存・共有しないでください。

curl -I --proxy http://127.0.0.1:7890 \
  --connect-timeout 10 \
  https://generativelanguage.googleapis.com/

このテストが失敗する場合は、Gemini CLIを再インストールする前に、Clashのポート、選択中のノード、DNS、ルール、ファイアウォールを確認します。curlは成功するのにGemini CLIだけが失敗する場合は、CLIが参照する環境変数名、Node.jsなどの実行ランタイム、認証設定、CLI独自のネットワーク実装を調べます。

ルールとTUNを安定運用向けに調整する

Gemini CLIだけをプロキシ化するなら、環境変数による明示設定で十分なことが多く、TUNを最初から有効にする必要はありません。TUNは、システムプロキシを参照しないアプリケーション、コンテナ、仮想環境、独自のネットワークスタックを使うツールまで取り込みたい場合に検討します。TUNを有効にすると、DNSの経路、ルーティング、VPN権限、他のネットワークソフトとの競合まで確認範囲が広がります。

方式	向いている用途	注意点
環境変数	Gemini CLIだけをClashへ通す	新しいターミナルごとに設定が必要な場合がある
システムプロキシ	ブラウザーや対応アプリも同じ経路にする	他のアプリの通信まで変更される
TUN	プロキシ設定を参照しないアプリや開発環境を含める	OS権限、DNS、ルーティングの問題が増える

国内の開発環境では、社内ネットワーク、VPN、セキュリティソフト、HTTPS検査プロキシが重なることがあります。接続が不安定な場合は、まずTUNを無効にして環境変数方式へ戻し、同じ操作を再試行してください。特定のノードだけ失敗するならノード側の経路やTLS条件を疑い、すべてのノードで失敗するならローカルポート、DNS、認証、サービス側の状態を疑うと切り分けやすくなります。

よくあるエラーの切り分け

connection refused：Clashが停止している、ポート番号が違う、別のプロセスが設定ポートを使用している可能性があります。
timeout：選択中のノード、DNS解決、ファイアウォール、経路上のパケットロスを確認します。
407 Proxy Authentication Required：企業プロキシなど、追加のプロキシ認証を要求されています。Clashのローカルポートと上流プロキシの認証を混同しないでください。
401または403：通信経路が確立していても、アカウント、APIキー、権限、利用地域、クォータの問題が残っている場合があります。
証明書エラー：システム時刻、CA証明書、企業のHTTPS検査、Node.jsなどのランタイム設定を確認します。検証を無効にして解決しようとするのは安全ではありません。
一部のコマンドだけ失敗：Gemini CLIのサブコマンドごとに異なるAPIエンドポイントや認証処理が使われていないか、Clashの接続ログを比較します。

ルール変更後は、一度に複数の項目を変えないことが重要です。まずプロキシグループを固定し、次にドメインルール、最後にDNSやTUNを変更します。接続ログには認証トークンやプロンプトの内容が記録される場合があるため、診断時も必要な範囲だけを保存し、共有前に機密情報を削除してください。

FAQ：Gemini CLIとClashに関する質問

Gemini CLIはClashのシステムプロキシだけで利用できますか？

CLIがOSのシステムプロキシを参照する実装であれば利用できる場合があります。ただし、すべてのコマンドラインツールがOS設定を自動的に読むとは限りません。確実に経路を指定したい場合は、まずHTTP_PROXYとHTTPS_PROXYを設定して試してください。

HTTPSなのにプロキシURLがhttp://になるのはなぜですか？

http://127.0.0.1:7890は、ローカルのClashポートまでの接続方式を表します。そのポートを通じて、Clashが宛先のHTTPS通信を中継します。ClashがHTTPSプロキシを明示的に提供している場合を除き、環境変数の値を任意にhttps://へ変更しないでください。

TUNを有効にすればGemini CLIの問題は必ず解決しますか？

いいえ。TUNはプロキシ環境変数を無視するアプリの通信を取り込むための機能で、認証、クォータ、API権限、サービス側のエラーを解決するものではありません。まず明示的な環境変数方式を確認し、必要性がある場合だけTUNを試してください。

接続できても利用規約や地域制限の問題は残りますか？

残ります。ネットワーク経路を変更しても、アカウントの利用資格、APIの提供地域、組織ポリシー、利用規約が変わるわけではありません。Gemini CLIとGoogleの公式ドキュメントを確認し、許可されたアカウントと用途で利用してください。