Gemini CLIをClashで使う設定方法：中国からの接続対策

Gemini CLIとClashを組み合わせる理由

Gemini CLIは、ブラウザを開かずにターミナルからAIへ質問したり、コードや文章を扱ったりできるコマンドラインツールです。開発作業の途中でファイルを確認する、シェルスクリプトから処理を呼び出す、エディターと組み合わせて回答を取得するといった使い方に向いています。一方、中国国内のネットワークから利用する場合、GeminiのAPIエンドポイントへ接続する段階で名前解決、TLS接続、経路制御のいずれかが止まることがあります。

ここで重要なのは、ブラウザでプロキシが使えていることと、Gemini CLIの通信も同じ経路を通ることは別問題だという点です。ブラウザはClashのシステムプロキシ設定を自動的に利用していても、Node.js、Python、Go、curlなどのCLIプログラムは環境変数を見て接続することがあります。そのため、Clash Vergeを起動しただけでは不十分で、CLIが参照するプロキシの入口と、実際に選ばれるノードを確認する必要があります。

本記事では、Clash Verge Revを例に、プロファイルの準備、Mixed Portの確認、環境変数の設定、API通信のテスト、ルールの分離、失敗時の切り分けまでを説明します。画面の名称はバージョンやOSによって少し異なりますが、考え方はWindows、macOS、Linuxで共通です。

設定前に確認するもの

Clash自体にはプロキシノードが含まれていません。プロファイルを持っていない場合は、利用しているサービスの管理画面からClash用のサブスクリプションURLを取得してください。形式が異なるURLを無理に読み込ませると、ノードが表示されない、ルールが空になる、あるいはYAMLの解析エラーが発生することがあります。

また、Gemini CLIのバージョンや公式ドキュメントの認証方式は更新される可能性があります。コマンド名や環境変数名が手元のバージョンと異なる場合は、まずCLIのヘルプ表示と公式ドキュメントを確認してください。Clashの設定は通信経路を整えるものであり、利用資格やAPIサービスの提供地域を変更するものではありません。

ステップ1：Clash Vergeでプロファイルとノードを準備する

Clash Vergeを起動したら、まず「Profiles」または「プロファイル」に移動します。サブスクリプションURLを入力して取得を実行し、設定ファイルが一覧に表示されることを確認してください。ダウンロードが完了しても、そのプロファイルが自動的に有効になるとは限りません。対象ファイルを選択し、現在使用するプロファイルとして切り替えます。

次に「Proxies」画面を開きます。ここではプロキシグループ、ノード、URLテストの結果が表示されます。最初のテストでは、複雑な自動選択グループよりも、応答時間が安定した単一ノードを手動で選ぶと切り分けが簡単です。自動選択が頻繁にノードを変更すると、接続できたのか、認証が失敗したのか、特定の出口だけが問題なのか判断しにくくなるためです。

「Settings」または「設定」では、システムプロキシ、Mixed Port、Allow LAN、TUNなどの項目を確認できます。Gemini CLIだけをテストする段階では、まずHTTPまたはMixed Portと環境変数の組み合わせを使う方法が分かりやすいでしょう。TUNモードは便利ですが、仮想ネットワークインターフェース、DNS、他のVPNソフトとの競合が加わるため、最初からすべてを有効にすると原因の特定が難しくなります。

ステップ2：Mixed Portとプロキシ入口を確認する

CLIアプリケーションがClashを利用するには、端末からアクセスできるローカルポートが必要です。Clash Vergeでは、HTTP、SOCKS、Mixed Portなどのリスナーが用意されています。Mixed PortはHTTPプロキシとSOCKS5の両方を受け付けられるため、複数のCLIツールを試す際に扱いやすい選択肢です。ただし、アプリ側がどのプロトコルを使うかは別に確認してください。

設定画面で、たとえばMixed Portが7890になっている場合、ローカルの接続先は通常127.0.0.1:7890です。別のアプリが同じポートを使っている、Clashが別のポートへ変更された、あるいはポートが無効になっている場合、環境変数を正しく書いても接続できません。ポートを変更した後は、ターミナルを開き直すか、現在のシェルで環境変数を再設定してください。

WindowsではPowerShell、macOSとLinuxではBashやZshなど、シェルごとに環境変数の書き方が異なります。以下は一般的な例です。実際のポート番号はClash Vergeの画面に表示されている値へ置き換えてください。

# PowerShell
$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"

# macOS / Linux
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"

# Some tools also read lowercase names
export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"

環境変数は、そのターミナルから起動したプロセスへ引き継がれます。GUIから起動したエディターや別のターミナルには自動で反映されないことがあるため、設定後は同じウィンドウからCLIを実行してください。恒久的に設定する場合はシェルの設定ファイルに追加できますが、共有PCや業務端末では環境への影響を確認してから行うことをおすすめします。

ステップ3：Gemini関連通信をプロキシ経由でテストする

いきなりGemini CLIを実行するのではなく、まず一般的なHTTPS接続を確認します。curlが使える環境なら、Clashのログ画面を開いた状態でテストしてください。コマンドを実行した直後にClashのConnectionsやログへ通信が表示されれば、少なくともCLIからローカルポートまでの経路は成立しています。

curl -I --proxy http://127.0.0.1:7890 https://generativelanguage.googleapis.com

レスポンスが返らない場合は、DNS、TLS、ノード、ルールの順に確認します。Clashのログに通信が出ていなければ、curlのプロキシ指定が認識されていないか、ポートが違う可能性があります。ログに通信が出ていてもタイムアウトするなら、選択中のノードやルールが原因かもしれません。HTTPステータスが401や403の場合は、ネットワーク経路ではなく認証情報、APIキー、サービス側の権限を確認します。

Gemini CLIを利用するときは、APIキーをコマンドラインへ直接書く方法を避けるのが安全です。コマンド履歴にキーが残る可能性があるため、環境変数、OSの資格情報ストア、CI/CDのシークレット機能などを使い分けてください。キーを誤って公開した場合は、利用サービスの管理画面から直ちに無効化し、新しいキーを発行します。

ステップ4：Gemini CLIへ環境変数を引き継ぐ

CLIがプロキシを認識する方法は、使用するランタイムやライブラリによって違います。多くのHTTPクライアントはHTTP_PROXYとHTTPS_PROXYを参照しますが、すべてのプログラムが自動対応するとは限りません。Gemini CLIの起動コマンド、Node.jsの依存ライブラリ、社内ラッパースクリプトなどが独自の設定を持つ場合は、そちらの指定が優先されることもあります。

まず環境変数が現在のシェルで有効か確認します。値を表示するときは、APIキーなどの秘密情報を同じ画面へ出力しないよう注意してください。プロキシURLだけを確認し、ホストとポートが期待どおりかを見ます。

# macOS / Linux
printf '%s\n' "$HTTPS_PROXY"

# PowerShell
$env:HTTPS_PROXY

SOCKSポートしか有効にしていない場合、HTTP形式のURLを指定しても動作しません。そのときは、CLIや使用ライブラリがSOCKS5に対応しているかを確認し、対応していればsocks5://127.0.0.1:7891のように指定します。対応していない場合は、Clash VergeでMixed PortまたはHTTPポートを有効にする方が簡単です。

シェルから直接実行した場合は成功するのに、VS Codeの統合ターミナルやIDEのタスクから実行すると失敗することがあります。これはIDEが起動時の環境を保持しているためです。IDEを再起動する、タスク定義で環境変数を明示する、同じシェルからIDEを起動するなどの方法で環境を揃えます。WindowsではGUIアプリとPowerShellの環境が異なることもあるため、最初の検証は単純なターミナルから行うと原因が見えやすくなります。

ステップ5：Gemini関連の通信だけをルールで分ける

すべての通信をGlobalモードでプロキシへ送るとテストは簡単ですが、国内サービス、社内システム、プリンター、ローカル開発環境まで経由してしまう可能性があります。実運用ではRuleモードを利用し、GeminiやGoogle APIに必要なドメインをプロキシへ割り当て、それ以外は既存のルールに任せる構成が扱いやすいでしょう。

ルールの具体的なドメイン名は、使用するCLIのバージョンやAPI機能によって変わります。ClashのConnections画面で実際に発生した通信を確認し、どのホスト名がProxy、DIRECT、REJECTのどれに分類されたかを見てください。ドメインを推測して大量に追加するより、必要な通信をログから確認して最小限のルールを作る方が、誤った経路や過剰なプロキシ利用を防げます。

# Example only; adapt to your own rule groups
rules:
  - DOMAIN-SUFFIX,generativelanguage.googleapis.com,PROXY
  - DOMAIN-SUFFIX,googleapis.com,PROXY
  - DOMAIN-SUFFIX,google.com,PROXY
  - MATCH,DIRECT

サブスクリプションが提供するルールを利用している場合、ローカルルールの位置と優先順位に注意してください。Clashは上から順番にルールを評価するため、先に広いDIRECTルールがあると、後ろに追加したAPIドメインのルールへ到達しません。逆に、広すぎるGoogle関連ルールを上位へ置くと、必要のないサービスまでプロキシへ流れます。

確認項目	期待する状態	問題がある場合
CLIの接続先	ClashのConnectionsに表示される	環境変数、ポート、アプリの起動元を確認
ルール判定	Gemini関連ドメインがProxyになる	ルールの順序とグループ名を確認
ノード状態	遅延テストとHTTPS接続が成功する	別ノード、DNS、TLSエラーを確認
認証状態	APIキーが有効で応答が返る	キー、権限、利用制限を確認

接続できない場合の切り分け

「Clashは接続済みなのにGemini CLIだけ失敗する」という場合、画面上の接続表示だけで判断せず、通信を層ごとに分けて確認します。最初に、Clash Vergeが起動しているか、コアがエラーなく動いているか、選択したノードが利用可能かを見ます。次に、CLIがローカルポートへ接続しているかをログで確認し、その後にリモートホストへのTLS接続とAPI認証を調べます。

1. ローカルポートを確認する：Clashの設定値と環境変数のポート番号を比較します。別のソフトがポートを占有していないかも確認します。
2. CLIの環境を確認する：同じターミナルからcurlを実行し、プロキシ経由の通信がログに現れるかを見ます。
3. ルールを一時的に単純化する：短時間だけGlobalモードで試し、成功するならRuleモードのマッチ順やグループ選択を調べます。
4. 別ノードを試す：ノードによって到達性やTLSの挙動が異なる場合があります。連続した再試行で利用制限を増やさないよう、適度に切り替えます。
5. DNSを確認する：ドメインが解決できない場合、ClashのDNS設定、OSのDNS、ブラウザやランタイム独自のDNS機能を比較します。
6. 認証エラーを分離する：401、403、429などのレスポンスは、プロキシそのものではなくキー、権限、レート制限の問題である可能性があります。

特に注意したいのは、ブラウザの「安全なDNS」やアプリ独自のDoHが、ClashのDNS設計を迂回するケースです。TUNモードを使っている場合も、別のVPN、セキュリティソフト、企業のネットワークエージェントが仮想インターフェースの優先順位を変更することがあります。複数のネットワーク制御ソフトを同時に有効にせず、一つずつ比較してください。

安全で再現しやすい運用方法

Gemini CLIを日常的に使うなら、毎回手作業で複数の環境変数を入力するより、用途ごとの起動方法を決めておくとミスが減ります。たとえば通常の開発用シェルではプロキシを必要なCLIだけに設定し、ブラウザや社内ツールへ影響させない方法があります。反対に、複数のCLIが同じ経路を使う場合は、ClashのシステムプロキシやTUNを検討できます。

設定ファイルは変更履歴を管理し、ノード情報やトークンを含む場合は公開リポジトリへ置かないでください。サブスクリプションURLにも認証情報が含まれることがあるため、スクリーンショット、ログ、Issue本文へ貼り付けないようにします。共有する設定例では、実際のホスト名、ポート、キー、ユーザー名をダミー値へ置き換えてください。

速度だけでなく安定性も見ます。Gemini CLIでは短い質問が成功しても、長いコンテキストやファイル処理でタイムアウトすることがあります。Clashの接続ログ、ノードの遅延、エラーコード、CLI側の再試行状況を同じ時刻で記録すると、問題がプロキシ、API、端末のどこにあるかを後から比較できます。

よくある質問

Gemini CLIだけをClashのプロキシ経由にできますか？

できます。最も簡単なのは、CLIを起動するターミナルにだけHTTP_PROXYとHTTPS_PROXYを設定する方法です。より細かく制御したい場合は、ClashのRuleモードでGemini関連のドメインをProxyグループへ割り当て、他の通信を既存ルールへ任せます。対象ドメインは固定だと決めつけず、実際のConnectionsログで確認してください。

Clashを起動してもGemini CLIが接続できません

ブラウザが動作していてもCLIが動くとは限りません。まずCLIが起動したシェルに環境変数が存在するか、ポート番号がClash Vergeの設定と一致するかを確認します。その後、curlを同じプロキシURLで実行し、Clashのログに通信が表示されるかを見ます。ログがなければローカル設定、ログがあって失敗するならノード、DNS、TLS、認証を順番に切り分けます。

APIキーをClashの設定ファイルに保存できますか？

保存しないことをおすすめします。Clashの設定ファイルはバックアップ、同期、画面共有の対象になりやすく、意図せず公開される可能性があります。APIキーは環境変数、OSのキーチェーン、パスワードマネージャー、CI/CDのシークレット機能などで管理し、不要になったキーは無効化してください。

関連するClashガイド

端末全体のプロキシ設定を見直したい場合は、WindowsでClashを設定する方法、macOSで利用する場合はClash Verge RevのmacOS設定も参考になります。DNSやfake-ipによってCLI以外のアプリにも問題が出ている場合は、Clash接続済みなのにインターネットへ接続できない場合の確認手順を確認してください。

まとめ

別のプロキシアプリでは、CLIごとに証明書やポートの扱いが異なったり、システムプロキシとターミナルの設定が分離していたりして、ブラウザは動くのに開発ツールだけ失敗することがあります。Clashはローカルポート、接続ログ、ルール判定を一つの画面で確認でき、必要な通信だけを分けたい場面でも設定を段階的に調整できます。

Gemini CLIの通信を安定させながら、他のアプリや国内サービスへの影響を抑えたい場合は、今回紹介したようにまず単純なポート設定から始め、テスト後にルールを細かくしてください。Clashの機能を実際に試すなら、Clashを無料でダウンロードして、利用環境に合ったクライアントを確認できます。