ブラウザは使えるのにGemini CLIだけ失敗する理由

Gemini CLIを初めて導入したときによくある症状が、「ブラウザではGeminiのウェブサイトを開けるのに、ターミナルで実行したGemini CLIは接続タイムアウトになる」という現象です。Clashを起動しているため、すべての通信が自動的にプロキシを通ると思いがちですが、実際にはアプリケーションごとにプロキシの扱いが異なります。

ChromeやEdgeなどのブラウザは、OSのシステムプロキシ設定を参照します。そのため、Clash Verge Revで「システムプロキシ」を有効にすると、ブラウザのHTTPS通信はClashのHTTPポートへ送られます。一方、Gemini CLIはターミナルから起動するNode.jsベースのコマンドラインアプリケーションです。実行環境やライブラリの設定によっては、OSのシステムプロキシを自動的に使用せず、直接インターネットへ接続しようとします。

つまり、ブラウザが正常に動作していることは、Gemini CLIも同じ経路を使っていることの証明にはなりません。まずClashが動作しているか、次にCLIがClashのリスニングポートを認識しているか、最後に対象ドメインが適切なルールでプロキシへ振り分けられているかを分けて確認する必要があります。

この問題はGemini CLI自体の故障とは限りません。多くの場合、CLIを実行するシェルにプロキシ環境変数が設定されていないこと、またはシステムプロキシだけではCLIの通信を捕捉できないことが原因です。

最初に確認するClash側の設定

環境変数を設定する前に、Clash側が接続を受け付けられる状態になっているか確認します。ここを飛ばすと、CLIの設定が正しくても存在しないポートへ接続することになり、同じタイムアウトが続きます。

Clashの起動状態とプロファイル

Clash Verge Revなどのクライアントを起動し、現在使用するプロファイルが有効になっていることを確認してください。プロファイルが読み込まれていない、またはプロキシグループに利用可能なノードがない場合、接続先をプロキシにしても通信は失敗します。「プロキシ」画面で少なくとも一つのノードに遅延値が表示され、選択中のプロキシグループがそのノードを使用していることを確認しましょう。

その後、「接続」画面を開いたままGemini CLIを実行します。リクエストがClashを通過していれば、通常は新しい接続記録が表示されます。何も表示されない場合、CLIはClashへ到達していません。これはルールの問題ではなく、環境変数やTUNモードなど、より手前の経路に問題がある可能性が高い状態です。

HTTP・混合ポートの確認

Clashの設定画面で、HTTPプロキシまたは混合ポートの番号を確認します。環境によって異なりますが、HTTPポートに7890、SOCKSポートに7891、混合ポートに7893などが使われることがあります。重要なのは、他の解説記事に書かれた番号をそのまま使うのではなく、現在のクライアントに表示されている番号を使うことです。

ターミナルからローカルポートへ簡単なリクエストを送り、Clashが応答するか確認できます。HTTPポートが7890の場合は次のように実行します。

curl -I -x http://127.0.0.1:7890 https://example.com

HTTPレスポンスヘッダーが返れば、少なくともターミナルからClashのHTTPポートへ接続できています。接続拒否が表示された場合は、ポート番号の間違い、Clashの停止、またはファイアウォールによるローカル通信の制限を確認してください。

ポート番号は環境によって異なります。Clashの外部コントローラーAPIポートと、プロキシ通信を受け付けるHTTP／SOCKSポートを混同しないでください。APIポートをHTTP_PROXYに設定しても、通常のウェブ通信は処理できません。

Gemini CLIにプロキシ環境変数を設定する

Gemini CLIをClash経由で通信させる最も基本的な方法は、CLIを起動するターミナルにプロキシ環境変数を設定することです。環境変数は、アプリケーションに「HTTPやHTTPSの接続をどこへ送るか」を伝える仕組みです。ブラウザのシステムプロキシとは別の設定なので、Clashでシステムプロキシを有効にしただけでは十分でない場合があります。

macOS・Linuxでの設定

macOSのターミナルやLinuxのBash、Zshでは、次のように設定します。ここではClashのHTTPポートが7890である例を使用しています。

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

gemini

HTTPS通信であっても、HTTPプロキシ形式のURLをHTTPS_PROXYに指定する構成は一般的です。これは「プロキシサーバーとの接続方式」がHTTPであり、「その先へアクセスする対象」がHTTPSという意味です。Clashの混合ポートを使う場合は、同じポートをHTTP形式で指定できます。

設定が有効かどうかは、Gemini CLIを実行する前に次のコマンドで確認できます。

echo $HTTP_PROXY
echo $HTTPS_PROXY
echo $ALL_PROXY

毎回入力するのが面倒な場合は、シェルの設定ファイルへ追加します。Zshなら~/.zshrc、Bashなら~/.bashrcが一般的です。追記後は設定を再読み込みします。

source ~/.zshrc
# または
source ~/.bashrc

ただし、すべてのCLIを常にプロキシ経由にしたいとは限りません。パッケージマネージャーや社内サーバーまでプロキシへ送ると、速度低下や認証エラーが発生することがあります。Gemini CLIを使うときだけ設定したい場合は、シェル設定ファイルへ恒久的に追加せず、専用のスクリプトや一時的なexportを利用する方が安全です。

Windows PowerShellでの設定

Windows PowerShellでは、環境変数の書き方がmacOSやLinuxと異なります。ClashのHTTPポートが7890の場合は次のように入力します。

$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"

gemini

設定は現在開いているPowerShellセッションにだけ適用されます。新しいターミナルを開くと消えるため、動作確認には便利です。恒久的に設定したい場合は、Windowsの「環境変数」画面からユーザー環境変数として登録できますが、他の開発ツールにも影響します。まずは一時設定でGemini CLIが正常に動くか確かめてから、恒久設定を検討してください。

NO_PROXYの扱い

ローカルアドレスや社内ネットワークを直接接続にしたい場合は、NO_PROXYを設定します。たとえば次のように指定できます。

export NO_PROXY=localhost,127.0.0.1,::1,.local

NO_PROXYを誤って広く指定すると、Gemini関連のドメインまで除外され、CLIがClashを迂回することがあります。特に*.google.comのような大きな範囲を入れている場合は注意してください。トラブルシューティング中は、まずNO_PROXYを unset して挙動を確認し、必要なローカルアドレスだけを戻すのが分かりやすい方法です。

ClashのルールとDNSを確認する

環境変数を設定した後もタイムアウトする場合は、リクエストがClashへ届いたか、そしてClashが正しいポリシーを選んだかを分けて確認します。Clashの「接続」画面にGemini CLIの通信が表示されるなら、少なくとも入口までは成功しています。表示された接続のドメイン名、ポリシー、最终接続先を確認してください。

対象ドメインがDIRECTになっていないか

Clashはルールを上から順に評価します。上位のルールで対象ドメインがDIRECTに分類されると、後ろに書いたプロキシルールは実行されません。Gemini CLIがアクセスするドメインは、API、認証、設定取得などの処理によって複数に分かれる場合があります。そのため、ブラウザで表示できたドメインだけを許可しても、CLIの認証エンドポイントやAPIエンドポイントが漏れることがあります。

一時的な切り分けでは、Clashのモードを「グローバル」に変更して通信を試す方法があります。グローバルモードで成功し、ルールモードで失敗するなら、ノードやポートではなくルールの優先順位が原因です。通常運用ではグローバルのままにせず、接続ログを参考に必要なドメインだけを適切なポリシーへ振り分けてください。

DNS解決の失敗を確認する

タイムアウトのように見えても、実際にはDNS解決が失敗していることがあります。CLIがホスト名をIPアドレスへ変換できない場合、Clashの接続一覧に期待するドメインが現れないことがあります。端末でnslookupやdigを使い、名前解決が可能か確認してください。

nslookup example.com
# macOS・Linuxでは
dig example.com

ClashのDNS機能を利用する場合は、設定ファイルのdnsセクションで有効化やリスニングアドレスを確認します。ただし、既存のVPN、セキュリティソフト、企業ネットワークのDNSポリシーと競合することもあります。設定を一度に多く変更せず、まずはCLIの通信がClashの接続ログに現れるかを基準に切り分けましょう。

接続一覧にドメインが表示され、ポリシーもPROXYになっているのに失敗する場合は、ルールよりもノードの状態、TLS接続、認証情報、またはプロバイダー側の制限を確認します。

環境変数で解決しない場合はTUNモードを使う

CLIがプロキシ環境変数を無視する、Node.jsの依存ライブラリが独自の接続方式を使う、あるいは子プロセスが環境変数を引き継がない場合、環境変数だけでは通信を捕捉できません。このような場合に有効なのがClashのTUNモードです。

TUNモードは仮想ネットワークインターフェースを作り、アプリケーションがプロキシ設定を理解しているかどうかにかかわらず、システムの送信トラフィックをClashへ渡します。CLIが直接TCP接続を行っていても、OSのルーティング層で捕捉できるため、環境変数に依存しない構成を作れます。

TUNモードの有効化手順

Clashの設定画面を開く

Clash Verge Revを起動し、設定またはホーム画面からTUNモードの項目を探します。表記はクライアントやバージョンにより「TUN Mode」「サービスモード」「仮想ネットワーク」など異なる場合があります。

必要な権限を許可する

TUNモードは仮想インターフェースやルーティングテーブルを変更するため、macOSでは管理者認証、WindowsではUACの確認が必要になることがあります。公式クライアントから表示された認証ダイアログだけを確認して許可してください。

ルールモードでCLIを再実行する

TUNモードを有効にした後、プロキシモードを通常は「ルール」に戻し、Gemini CLIを再起動します。接続画面にCLIの通信が現れ、対象ドメインが意図したポリシーで処理されることを確認してください。

TUNモードを有効にしても接続できない場合、TUNが実際に起動しているか、システムのVPNや別の仮想ネットワークソフトと競合していないかを確認します。複数のVPN、Docker、仮想マシン、他のプロキシクライアントが同時にルーティングを変更すると、経路が不安定になることがあります。不要なネットワークツールを一時停止し、Clashだけで再テストすると原因を絞り込みやすくなります。

TUNモードはシステム全体の通信へ影響します。社内ネットワーク、プリンター、銀行サイト、ローカル開発環境などを直接接続にするルールを用意し、問題が起きたときにすぐ無効化できるようにしてください。

症状別の切り分け方法

設定を変更した後は、毎回同じ条件でテストすることが重要です。複数の項目を同時に変更すると、どの設定が効いたのか分からなくなります。次の順番で確認すると、比較的短時間で原因を特定できます。

Clashのポートへcurlで接続する：ローカルポートが応答するか確認します。失敗する場合は、CLIの前にClashの起動状態やポート番号を直します。
環境変数を設定して簡単なHTTPS通信を試す：同じターミナルでcurlを実行し、Clashの接続ログに表示されるか確認します。
Gemini CLIを実行する：ログに現れない場合は、環境変数名、シェル、子プロセスの引き継ぎを確認します。
グローバルモードで比較する：グローバルで成功する場合は、ルールやDNSの振り分けを見直します。
TUNモードで比較する：環境変数を無視している可能性がある場合に、TUNモードで通信経路を補います。

接続ログに何も表示されない場合

ログに何も表示されない場合、Gemini CLIはClashへ接続していません。環境変数が設定されていないシェルから起動している、別のターミナルアプリケーションが異なるシェル設定を読み込んでいる、またはCLIがプロキシ環境変数をサポートしていない可能性があります。まずechoで値を確認し、同じウィンドウでCLIを起動してください。

ログには表示されるがタイムアウトする場合

Clashのログに表示される場合は、通信がClashまで到達しています。表示されたポリシーがDIRECTならルールを修正し、PROXYなのに失敗するならノードの遅延や可用性を確認します。ノードを変更しても失敗する場合は、DNS、TLS、認証、アカウントの有効状態などを確認します。

接続はできるが認証で失敗する場合

タイムアウトが解消した後に認証エラーが表示されるなら、ネットワーク経路は改善しています。APIキーやログイン状態、CLIの設定ファイル、使用中のアカウント権限を確認してください。ネットワークエラーと認証エラーを同じ問題として扱わず、エラーメッセージが変化したこと自体を切り分けの進展として捉えることが大切です。

安定運用のための設定ポイント

Gemini CLIを日常的に利用する場合は、単に接続できる状態を作るだけでなく、再現性と安全性も考慮しましょう。まず、Clashのポート番号を固定し、シェル設定やスクリプト内で参照する値を一元化します。ポートがクライアントの再起動ごとに変わる設定になっていると、突然CLIだけが失敗する原因になります。

次に、プロキシ環境変数をすべてのツールへ無条件に適用しないことをおすすめします。社内GitサーバーやローカルAPIにはNO_PROXYを使い、必要な通信だけを直接接続にします。また、APIキーや認証トークンをコマンド履歴へ書き込まないよう注意してください。プロキシ設定と認証情報を同じスクリプトへ保存する場合は、ファイルのアクセス権を制限し、公開リポジトリへコミットしないようにします。

DNS設定を変更した場合は、変更前の値を記録しておきましょう。DNS、TUN、システムプロキシ、VPNを同時に変更すると、問題が解決しても副作用の原因が追跡できなくなります。Clashでは設定をバックアップし、変更は一項目ずつ行うのが安全です。

「ブラウザが動くか」ではなく、「Gemini CLIの接続がClashのログに表示され、意図したポリシーで処理されているか」を確認することが、最も確実な診断方法です。

まとめ：まず環境変数、必要ならTUNモード

Gemini CLIの接続タイムアウトは、Clashが停止しているとは限りません。ブラウザはシステムプロキシを使っていても、CLIは別の経路から直接接続していることがあります。最初にClashのプロファイル、HTTP／混合ポート、ノードの状態を確認し、次にCLIを起動する同じターミナルへHTTP_PROXYとHTTPS_PROXYを設定してください。

環境変数を設定しても接続ログに何も表示されない場合は、CLIが環境変数を参照していない可能性があります。その場合はルールモードとグローバルモードを比較し、必要に応じてTUNモードを有効にします。Clashは単純なオン・オフ式のプロキシと異なり、アプリケーション、ドメイン、DNS、ルーティングを個別に確認できるため、原因を段階的に切り分けられます。

ClashのHTTPまたは混合ポートが実際に待ち受けているか確認する。
Gemini CLIと同じターミナルでプロキシ環境変数を設定する。
Clashの接続ログで対象ドメインとポリシーを確認する。
ルールやDNSが原因なら、グローバル比較後に必要なルールだけ修正する。
環境変数が無視される場合は、管理者権限に注意してTUNモードを利用する。

これからClashを導入する場合や、現在のクライアントを更新したい場合は、対応OSとコアの情報を確認できるダウンロードページをご利用ください。適切なクライアントと設定を選べば、ブラウザだけでなく、Gemini CLIのような開発者向けツールも同じルールベースのネットワーク環境で安定して運用できます。

Gemini CLI Clash設定接続タイムアウト

Gemini CLIが接続タイムアウト？Clashの設定と直し方を解説