Docker pull がタイムアウト？Windows／macOS で Docker Desktop を Clash の HTTP／HTTPS プロキシへ向ける手順

この記事で扱う症状

すでに Clash（Mihomo／Meta 系コアを載せた GUI 含む）でブラウザや各種アプリの通信は問題なく通っているのに、Docker Desktop だけが docker pull でイメージ取得に失敗したり、レイヤーのダウンロードが極端に遅い。あるいは docker build の途中で外部パッケージ取得だけが詰まる。コンテナを起動したあと、apt や npm の外向き通信だけが不安定、といった症状です。

原因は単一ではなく、大きく分けて「ホスト OS のプロキシ設定」「Docker エンジン（デーモン）が参照する HTTP／HTTPS プロキシ」「Windows の WSL2 バックエンドや macOS の LinuxKit VM から見た到達経路」「コンテナ内の環境変数」のどこかで情報が途切れていることが多いです。本稿では層を意識して順に確認し、イメージレジストリ（Docker Hub やミラー、プライベート レジストリ）へ安定して到達できる状態へそろえる流れを整理しました。

なぜ「ブラウザは通るのに Docker だけ失敗」しやすいか

多くのユーザーは Clash をシステムプロキシまたはTUNで有効にしていますが、Docker のクライアントとエンジンは、必ずしもその設定をそのまま引き継ぎません。特に docker pull は Docker Desktop が内部で動かす Linux 環境からレジストリへ HTTPS で接続するため、ホストのブラウザがプロキシ経由でも、エンジン側にプロキシが未設定だと直出しの経路でタイムアウトすることがあります。

また 127.0.0.1:7890 のようにループバック上の Clashを指す場合、コンテナや VM からは「自分自身の 127.0.0.1」になり、ホストの Clash に届きません。Docker Desktop のプロキシ設定 UI や host.docker.internal、Windows では WSL からホストへ向かうアドレスなど、名前空間が変わるたびに参照すべきホスト名／IP が変わる点がつまずきどころです。TUN モードの挙動やルートの変化については、当サイトの TUN モードの解説も併せて確認すると整理しやすいです。

ステップ 1：ホストで Clash の待ち受けと疎通を確認する

まず Docker に触る前に、Clash がどのインターフェースでプロキシを公開しているかを確認します。ローカル専用（127.0.0.1）か、LAN に開いているかで、後続の「コンテナや VM からどう指定するか」が変わります。Docker Desktop の仮想環境からホストへ届ける必要がある場合、ファイアウォールでブロックされていないかも合わせて見ます。Windows では WSL2 と Clash を併用したときのルートや MTUが絡むケースもあり、イメージ取得以外の不安定さが同時に出ているときは当該記事のチェックリストと役割分担すると理解が早いです。

続けて、ブラウザではなくターミナルからプロキシ経由で HTTPS が通るかを確認します。例として、プロキシを明示してレジストリ相当のホストに接続できるかを見ると、「プロキシ文字列は正しいか」「認証が要るか」が切り分けられます。ここで失敗する場合は Docker 以前に、Clash のルールやノード側の問題を疑う段階です。

ステップ 2：Docker Desktop の「プロキシ」設定（Windows／macOS 共通の考え方）

Docker Desktop の設定画面には、エンジンがイメージを取得するときに使う HTTP／HTTPS プロキシを指定する項目があります（表示名はバージョンにより「Resources」配下や「Docker Engine」と並列など）。ここに、ホスト上の Clash が待ち受けているアドレスとポートをエンジンが解釈できる形で書きます。

ポイントは次のとおりです。第一に、http://127.0.0.1:ポート が使えない構成では、host.docker.internal（Docker Desktop が提供するホスト名）や、Windows の WSL から見たホスト IP など、VM 内からホストのプロキシへ届くホスト名に置き換えます。第二に、社内プロキシのように認証が必要な環境では、Docker Desktop 側の入力欄にユーザー名とパスワードを含められる形式にする必要があります。第三に、プロキシを有効にしたあとDocker を再起動して反映を確実にします。

ミラーやプライベート イメージレジストリを併用している場合、Clash の分流ルールでレジストリのドメインが意図したプロキシグループへ向かっているかも確認してください。ルールの書き方全般は 分流ガイドを参照しつつ、docker pull 時にログで実際に接続しているホスト名を追うと誤設定に気づきやすいです。

ステップ 3：Windows と WSL2 バックエンドの切り分け

Windows 版 Docker Desktop は、多くの環境で WSL2 をバックエンドに使います。ホストの PowerShell ではプロキシが通っても、WSL2 のディストリビューション内で動く docker クライアントや、裏側の Linux 名前空間から見た経路が異なり、結果として pull だけ失敗することがあります。Docker Desktop 側のプロキシ設定でエンジン全体を揃えたうえで、まだ不安定なら、WSL 内の名前解決や既定ルート、MTU を疑う流れになります。

このとき「ホストと WSL のどちらで詰まっているか」を分けるのが早道です。Docker Desktop のトラブルシュート表示や、WSL を再起動してから同じ docker pull を試す、といった単純な切り分けも有効です。仮想 NIC のメトリックや断線全般は、本記事の焦点が「公式クライアントとプロキシ経路」であるのに対し、WSL2 のルートと MTU を扱う記事で補完できます。両方を読み分けると、再発時のメモも書きやすくなります。

ステップ 4：macOS での注意点（LinuxKit VM とホストの境界）

macOS 版 Docker Desktop も、実際のエンジンはホストの外側に用意された Linux 環境で動きます。そのため、ホストの「システムプロキシに従う」アプリと、Docker エンジンの挙動は一致しないことがあります。Docker Desktop の GUI で HTTP／HTTPS プロキシを明示し、イメージ取得とビルド時の外向き通信の両方をカバーするのが基本線です。

コンテナからホスト上の Clash へ直接接続したい場合、host.docker.internal をプロキシホストに使うパターンがよく知られていますが、Docker のバージョンやネットワークモードによっては追加の設定が必要になることもあります。うまくいかないときは、まず Docker Desktop の公式ドキュメントに沿って推奨のプロキシ指定方法を確認し、そのうえで Clash の待ち受けアドレスと矛盾がないかを見ます。

ステップ 5：コンテナ内の HTTP_PROXY とビルド引数

docker pull が成功しても、コンテナ起動後にだけ apt update や curl https://... が失敗する場合は、コンテナ内にプロキシ環境変数が無いことが原因のことがあります。実行時に -e HTTP_PROXY=... と -e HTTPS_PROXY=... を渡す、Dockerfile で ENV を宣言する、Compose の environment に書く、といった方法で揃えます。

docker build では、--build-arg HTTP_PROXY=... のようにビルド引数として渡す必要があるステージもあります。BuildKit を有効にしている場合でも、プロキシがどのステップで参照されるかは Dockerfile の書き方に依存するため、失敗しているレイヤーのログを見て「どのコマンドが外向き通信しているか」を特定すると早いです。なお、レジストリではなくランタイムの通信全般を TUN で吸い上げたい場合は、モードの理解として TUN モードの記事の整理も参考になります。

ステップ 6：確認の順序とよくある見落とし

最後に、切り分けの推奨順をまとめます。① Docker Desktop のエンジン向けプロキシが有効か。② プロキシのアドレスが VM／コンテナから見て正しいか（ループバックの取り違えがないか）。③ Clash 側でレジストリのドメインが意図したノードに向いているか。④ コンテナ内およびビルド時の環境変数が揃っているか。⑤ それでも遅い場合は MTU や DNS、WSL2 特有の経路を疑う。

ログの見方も重要です。Docker Desktop の診断情報や、Clash の接続ログに、タイムアウトした宛先のドメインが出ていないかを確認すると、分流ルールの不足や、ノード側の制限に早く気づけます。YAML の細部はドキュメント集も参照してください。

まとめ

Docker Desktop で イメージレジストリへの接続が不安定なときは、ブラウザ用のプロキシ設定だけを見ても足りず、HTTP／HTTPS プロキシをエンジンとコンテナの両方に一貫して渡す必要があります。Windows では WSL2 バックエンドとの境界、macOS ではホストと VM の境界を意識し、127.0.0.1 の取り違えを避けることがポイントです。

Clash はルールとログの可視性に優れ、プロキシの出口を切り替えながら切り分けができるため、Docker との組み合わせでも「どのレイヤーで詰まっているか」を追いやすいのが強みです。クライアントの入手先が分かりづらい場合は、説明の一貫性のためにダウンロードページを主な導線にすると取り違えが減ります。

各 OS 向けの推奨クライアントはダウンロードページにまとめています。Docker のプロキシを整えたあと、安定したビルドへそろえて運用すると安心です。→ Clash クライアントを無料でダウンロードし、Docker 開発のネットワークを整える