Fix Docker Hub Timeouts with Clash Transparent Proxy Setup

Why Docker Hub Times Out Behind Clash

Docker image pulls can fail even when ordinary websites open normally through Clash. A command such as docker pull nginx:latest may pause for several minutes and then return i/o timeout, context deadline exceeded, or Client.Timeout exceeded while awaiting headers. This usually does not mean that Docker Hub is completely unavailable. More often, the Docker Engine is using a different network path from your browser, while Clash is only proxying applications that understand the system proxy.

There is another complication: a Docker pull is not a single request to one hostname. The client may contact registry-1.docker.io for registry operations, auth.docker.io for authentication, and a content delivery network such as production.cloudflare.docker.com or another storage endpoint for image layers. If only one of these domains is routed incorrectly, authentication can succeed while the actual layer download times out.

This guide presents a practical Clash transparent proxy setup for Docker on a local computer or server. It covers TUN mode, Docker Engine proxy variables, DNS behavior, rule order, node selection, and log-based troubleshooting. The examples use Mihomo-compatible configuration syntax, but the same principles apply to many Clash clients that expose a TUN or redirection feature.

1Understand the Docker and Clash Traffic Path

Before changing configuration, identify which component is making the request. A browser usually honors HTTP or SOCKS proxy settings configured by the operating system or by the Clash client. The Docker command-line tool, however, communicates with the Docker daemon. On Linux, that daemon commonly runs as a system service under systemd; on Windows and macOS, Docker Desktop runs the engine inside a managed virtual machine. The process that needs proxy access is therefore often the daemon, not the terminal window where you type the command.

Transparent proxying solves a different problem. Instead of requiring every application to support a proxy, Clash captures traffic at the network layer through TUN, redirection, or a similar mechanism. This can help Docker containers and daemon traffic, but it depends on permissions, route settings, DNS interception, and whether Docker is running inside a separate virtual machine.

The first diagnostic question is simple: does the same machine reach Docker Hub through a browser or curl, but fail with docker pull? If yes, focus on Docker daemon proxy settings and transparent capture rather than immediately replacing the proxy subscription.

2Configure Clash Transparent Proxy Mode

For a desktop installation, TUN mode is normally the easiest transparent approach. Open your Clash client, select the active profile, and enable the TUN or enhanced network mode. The exact label differs between Clash Verge Rev, Mihomo Party, and other clients. Administrator or root permission may be required because the client must create a virtual network interface and modify routes.

A basic Mihomo configuration can look like this:

The important options are auto-route, which installs routes through the TUN interface, and dns-hijack, which allows Clash to intercept ordinary port 53 queries. fake-ip mode can prevent local DNS results from bypassing the proxy decision. If your client or operating system has compatibility problems with fake IP, test redir-host instead, but do not change several network variables at once.

Choose a stable proxy group

Do not test Docker with an automatic latency group that changes nodes during a pull. Large images contain many layers, and switching nodes halfway through a download can produce inconsistent authentication or broken connections. Select one stable node manually, preferably with low packet loss, reliable HTTPS support, and enough bandwidth for large files. A node that is fast in a browser may still perform poorly with long-lived registry downloads.

3Set the Docker Engine Proxy Explicitly

Transparent routing is useful, but an explicit daemon proxy is often more predictable. It tells Docker where to send registry requests even when the daemon is not fully captured by TUN. Use the HTTP proxy address exposed by Clash, commonly 127.0.0.1:7890 when Docker and Clash share the same network namespace.

On a Linux host using systemd, create a drop-in directory and configuration file:

Check that the daemon received the variables:

Some Docker installations use a different service name, such as docker.service or a rootless user service. Confirm the active unit with systemctl status docker. If Docker runs in rootless mode, place the drop-in under the user systemd directory and restart the user service instead of modifying the system daemon.

On Docker Desktop, open the application settings and look for the Resources, Proxies, or Network section. Depending on the release, Docker Desktop may provide a proxy field, or it may inherit the host proxy. If you use a local Clash listener, verify whether Docker Desktop can access the host loopback address. Inside a virtual machine, 127.0.0.1 refers to that virtual machine, not necessarily the host running Clash. You may need the host gateway address, a LAN listener, or the proxy setting provided by Docker Desktop.

4Add Docker Hub Rules and Verify DNS

Rule order matters because Clash evaluates rules from top to bottom and stops at the first match. Put specific Docker domains above broad rules such as a regional geolocation rule, a catch-all GEOIP rule, or the final MATCH rule. A practical starting point is:

The exact layer download hostname can vary. Start a pull while watching Clash logs, then add the domain that appears in the connection record. Avoid blindly proxying every cloud provider domain, because Docker image layers may be hosted on infrastructure shared with many unrelated services. Domain rules are easier to audit than a large collection of guessed IP ranges.

DNS must follow the same policy as the connection. Test resolution from the host:

A healthy registry endpoint may return 401 Unauthorized from /v2/; that response is not necessarily an error. It confirms that HTTPS reached the registry and that authentication is required. By contrast, a DNS failure, connection reset, or long hang indicates a routing or resolution problem.

When fake IP mode is enabled, some applications may display addresses from the reserved fake range rather than the real Docker server. That is expected. Do not add fake IP addresses to permanent allowlists. If a Docker component rejects fake IP responses, add the affected domain to fake-ip-filter or temporarily test redir-host mode:

Use exclusions sparingly. Excluding Docker domains from Clash DNS can reintroduce local resolver failures, especially when the original timeout is caused by DNS interference.

5Hands-On Setup and Test Procedure

Apply the configuration in a controlled sequence so that each test tells you something useful. The following workflow works well on Linux and can be adapted to Docker Desktop.

For deeper inspection, use docker system info and check the daemon logs:

Do not judge the setup only by the speed of the first layer. A reliable route should complete authentication, manifest retrieval, and every layer without repeated retries. If the first few layers are quick but later layers stall, inspect the CDN hostname rather than changing the Docker registry rule.

6Read Logs and Fix the Most Common Failures

Clash logs are most useful when filtered by the time of the failed pull. Look for the requested host, selected rule, policy group, and connection result. If auth.docker.io is shown as DIRECT while registry-1.docker.io uses PROXY, the rule list is incomplete or ordered incorrectly. If no Docker hostname appears at all, the daemon traffic is probably bypassing Clash and the explicit proxy or route needs attention.

MTU problems are less common but can appear on VPN, TUN, PPPoE, or nested virtualization networks. Symptoms include successful small requests but stalled large TLS transfers. If your Clash client exposes an MTU option, test a conservative value such as 1400 or 1380, then retest. Change only one value at a time and keep a record of the original setting.

Another common mistake is proxying the daemon to 127.0.0.1:7890 when the daemon runs in a container or virtual machine. In that environment, use a reachable host address and ensure the Clash listener accepts connections from that network. Conversely, do not use 0.0.0.0 as a public-facing solution without firewall restrictions.

7Keep the Configuration Reliable

A Docker-specific proxy setup should be simple enough to maintain. Keep the Docker rules near the top of the rule list, document why each domain is included, and avoid copying large IP lists from unverified sources. Docker infrastructure changes over time, while a small set of domain rules can be updated after checking current logs.

• Use a dedicated proxy group for Docker when your client supports it, so image pulls do not unexpectedly switch nodes.
• Keep NO_PROXY entries for local registries, private networks, and internal service names that should never leave the local network.
• Do not enable both several competing VPN clients and Clash TUN mode during troubleshooting; overlapping routes make results difficult to interpret.
• Test authentication and an uncached image after every major profile update.
• Monitor disk space as well as network logs. Docker may report an apparent download failure when the filesystem is full.
• For production servers, consider a nearby pull-through registry cache. It reduces repeated downloads and makes deployments less dependent on an interactive desktop proxy.

Transparent proxying is a routing technique, not a guarantee that every proxy node can handle Docker Hub. Choose nodes with dependable HTTPS connectivity, avoid frequently changing automatic groups, and keep a direct fallback only when your network can actually reach the registry without restrictions.

Frequently Asked Questions

Does Docker automatically use Clash system proxy settings?

Usually not. The Docker CLI sends requests to the Docker daemon, and the daemon may run as a separate service or inside a virtual machine. Configure the daemon proxy explicitly, use Docker Desktop's proxy settings, or capture the daemon traffic with a correctly configured TUN route.

Why does docker login work while docker pull fails?

Authentication and layer downloads can use different hostnames. The registry and authentication endpoints may match your PROXY rules, while the image layers come from a CDN or object-storage domain that is still routed DIRECT. Watch Clash logs during the layer phase and add the missing domain.

Is a 401 Unauthorized response from Docker Registry an error?

Not by itself. A request to /v2/ commonly returns 401 to indicate that the registry is reachable but requires credentials or a token. A timeout, DNS error, TLS failure, or connection reset is more indicative of a routing problem.

Should every Docker domain be forced through the proxy?

Not necessarily. Proxy the registry, authentication, and observed layer-delivery domains that cannot be reached reliably through your local connection. Keep private registries and internal network names in NO_PROXY, and review the rules periodically to avoid unnecessary proxy traffic.