A Docker Hub pull timeout does not always mean your Clash node is down. Docker may be using a separate network path from your browser or terminal: the Docker daemon performs image downloads, and it may not inherit the proxy variables set in your shell. This guide walks through practical checks for Docker’s proxy settings, Clash routing rules, TUN mode, and node connectivity. You’ll also learn how to test each layer with simple commands and recognize the difference between a proxy problem and a Docker Hub response that is working as intended.

Trace the Request Before Changing Settings

When you run docker pull nginx, Docker does more than connect to one hostname. The client asks the daemon to pull the image, and the daemon contacts Docker Hub services to authenticate, retrieve image metadata, and download layers. Depending on the image and the response from the registry, traffic may involve domains such as auth.docker.io, registry-1.docker.io, and a content delivery host used for layer downloads.

This matters because a browser test is not a reliable test of the daemon’s route. A browser may use Clash’s system proxy settings, while the daemon uses its own network configuration. Similarly, setting HTTPS_PROXY in one terminal only affects programs started from that environment; it does not automatically update a Docker service that started earlier under systemd, Docker Desktop, or another service manager.

Start with the exact symptom and the component that reports it. A timeout while resolving or connecting to a registry host suggests a network path problem. An authentication error, a denied response, or an image-not-found message is different: the request may have reached Docker Hub, but the credentials, image name, tag, or permissions need attention. Copy the full error text before making changes so you can compare results after each test.

Use a controlled test: Pull a small, public image with an explicit tag, such as docker pull hello-world:latest. This reduces uncertainty caused by private registries, large layers, or an incorrectly spelled image name.

Check the Clash Listener and Selected Node

Before configuring Docker, confirm that Clash is running and that the selected proxy group can reach the services Docker needs. In Clash Verge, Clash Verge Rev, or another Mihomo-based client, check the active profile, the current mode, and the node selected by the group used for general traffic. A node that passes a latency test is not necessarily able to download registry layers reliably; a short connectivity check is useful, but a real request is the stronger test.

Find the local HTTP or mixed port in the client’s settings or configuration. Common examples are 7890 for an HTTP proxy and 7893 for a mixed port, but these are examples only. Use the actual port shown by your client. The HTTP proxy protocol is suitable for Docker’s HTTP_PROXY and HTTPS_PROXY variables; a SOCKS-only listener should not be entered as though it were an HTTP proxy.

On the same host where the Docker daemon runs, test the listener directly. Replace the port and proxy URL with the values configured on your machine:

Test the Clash HTTP Listener
curl -x http://127.0.0.1:7890 -I https://registry-1.docker.io/v2/

A response such as HTTP/1.1 401 Unauthorized from the registry API can be a successful connectivity result. The registry commonly challenges unauthenticated requests; the important point in this test is that the request received an HTTP response instead of timing out. A connection refusal usually means the port is wrong, the listener is disabled, or it is bound to a different address. A timeout may point to the node, the Clash route, DNS, or an upstream network issue.

Then compare a normal request without the explicit proxy. If the proxied request succeeds but the direct request fails, you have evidence that Docker needs to use Clash explicitly or that the relevant traffic must be captured by TUN mode. If both fail, first troubleshoot the Clash listener and node rather than editing Docker settings.

Configure the Docker Daemon Proxy

On Linux, Docker Engine commonly runs as a system service. The daemon, rather than the interactive Docker CLI, makes the registry connections. Shell variables can help test tools such as curl, but they do not necessarily configure the already-running service. Configure the daemon itself, using either Docker’s daemon proxy configuration or a systemd service drop-in. Choose one method and verify that the daemon received the settings.

Option 1: Configure Docker in daemon.json

On Docker Engine versions that support daemon proxy settings, add a proxies object to the daemon configuration. The usual Linux location is /etc/docker/daemon.json. If the file already contains settings, merge this object into the existing JSON rather than replacing the file. JSON does not allow comments or trailing commas.

Docker Daemon Proxy Configuration
{
  "proxies": {
    "http-proxy": "http://127.0.0.1:7890",
    "https-proxy": "http://127.0.0.1:7890",
    "no-proxy": "localhost,127.0.0.1,.local"
  }
}

Validate the JSON before restarting the service. Depending on the installation, you can inspect Docker’s configuration or use a JSON parser to catch syntax errors. After editing, restart Docker during a suitable maintenance window because existing containers may be affected by a daemon restart. Then inspect the daemon information and retry the controlled pull.

Option 2: Use a systemd Drop-In

A systemd drop-in is a useful alternative on Linux when the daemon should receive proxy environment variables. Create a service override rather than editing a packaged unit file, which could be replaced during an upgrade. The example below assumes Clash listens on the same host as Docker and accepts HTTP proxy requests on port 7890.

systemd Docker Proxy Override
[Service]
Environment="HTTP_PROXY=http://127.0.0.1:7890"
Environment="HTTPS_PROXY=http://127.0.0.1:7890"
Environment="NO_PROXY=localhost,127.0.0.1,.local"

Save the override in the Docker service’s drop-in directory, then reload systemd’s unit definitions and restart Docker. Confirm that the service has the expected environment after the restart; do not assume that saving the file changed a running daemon. If your distribution uses a differently named service or a rootless Docker installation, check the corresponding service unit and user-level configuration before applying commands copied from a system-wide setup.

Do not configure a proxy URL that only exists inside a different network namespace. For example, if Docker Engine is running inside a virtual machine, 127.0.0.1 refers to that virtual machine, not necessarily to the desktop operating system where the Clash client is running. In that case, use an address reachable from the daemon’s environment, and ensure the Clash listener is deliberately configured to accept connections from that address. Avoid exposing an unauthenticated proxy to an untrusted network.

Do not mix configuration blindly: Docker Desktop, rootless Docker, and Linux Docker Engine have different service boundaries. A proxy setting in your shell, the desktop application, and daemon.json may affect different components. Identify where the daemon runs before choosing a configuration method.

Make Clash Rules Match Docker Hub

A daemon can connect to the Clash listener and still time out if Clash sends the registry traffic through an unsuitable route. In rule mode, inspect the matched rule and the proxy group it selects. Check the registry, authentication, and layer-download destinations involved in the failing pull; testing only registry-1.docker.io may not cover every request in a complete image download.

If your configuration uses domain-based rules, place the relevant Docker Hub rules before broad rules that could send the same traffic directly or to an unreliable group. A focused example might look like this:

Example Docker Hub Rules
rules:
  - DOMAIN,auth.docker.io,Proxy
  - DOMAIN,registry-1.docker.io,Proxy
  - DOMAIN-SUFFIX,docker.io,Proxy
  - MATCH,Final

Replace Proxy with the name of a proxy group that exists in your configuration. Rule order matters: Clash evaluates rules in sequence and uses the first matching rule. If a broad rule appears earlier, adding a more specific rule at the bottom may have no effect. Also check whether the client is using the profile you edited, whether the profile merges rules from another source, and whether an application-level rule or script changes the final routing decision.

Layer downloads can be served from a host other than the registry API host. If authentication and metadata requests succeed but the transfer of a particular layer stalls, inspect Clash’s connection or log view while reproducing the pull. Note the actual destination domain, then decide whether a narrowly scoped rule is appropriate. Avoid assuming that one hostname covers all Docker Hub traffic, and avoid adding large wildcard rules without understanding what else they will route.

For a quick diagnosis, temporarily route the relevant traffic through a known-working proxy group, then repeat the same pull. If it works, refine the rule rather than leaving an overly broad test rule in place. If changing the group has no effect, verify that the daemon’s connection is reaching Clash at all; traffic that bypasses Clash cannot be fixed by editing Clash’s domain rules.

Use TUN Mode When Explicit Proxy Is Not Enough

TUN mode captures network traffic at the system network layer and can help when a program does not support conventional proxy variables or when you cannot configure the daemon directly. Enable it only after checking the client’s platform requirements and granting the permissions it requests. On desktop systems, the feature may depend on a privileged helper, a virtual network interface, or system routing changes. A successful TUN setup should be verified in Clash’s connection view, not inferred merely from the toggle appearing enabled.

Do not assume that enabling TUN automatically routes every Docker deployment. Docker Desktop may run its engine in a virtual machine, while Linux Engine may run as a system service, and rootless Docker has yet another network boundary. The route that captures traffic on the host may not capture traffic originating inside a VM or another isolated environment. If Docker exposes its own proxy configuration, explicit daemon proxy settings are often easier to reason about and test.

For TUN troubleshooting, start with a minimal setup: confirm that the interface is active, confirm that DNS handling is functioning, and watch for the registry connection in Clash while a pull runs. If no corresponding connection appears, Docker may be using a path outside the captured interface, or a virtualized daemon may require its own proxy configuration. If a connection appears with a direct route, review the matching rule and the order of rules. If it appears through a proxy but stalls, test another node and compare results.

When both explicit proxy settings and TUN are enabled, avoid using that combination as an unexplained workaround. It can make the path harder to diagnose, and some deployments may apply proxying twice or create confusing routing behavior. Establish one working method first, document which component handles the traffic, and add the second method only when there is a clear requirement.

Verify the Fix and Isolate Failures

After changing one setting, restart or reload only the component that needs it, then repeat the same test. A useful sequence is: test the Clash listener with curl, test the registry endpoint through that listener, confirm the Docker daemon’s proxy settings, and pull the same small public image. Changing several variables at once makes it difficult to tell whether the fix was a proxy setting, a routing rule, a node change, or a transient network recovery.

Use the following results to narrow down the likely cause:

ResultLikely AreaNext Check
Direct curl fails, proxied curl respondsDocker is not using the working proxy pathConfigure the daemon or test a supported TUN route
Both direct and proxied curl time outClash listener, node, DNS, or upstream connectivityCheck the listener port, node, logs, and resolver
Registry responds with 401Network connection may be workingRetry the pull; investigate credentials only if Docker reports an auth failure
Manifest works but a layer stallsLayer delivery host or transfer pathInspect live Clash connections and the specific failed destination
Clash shows no connection during a pullDaemon traffic may bypass ClashCheck daemon proxy settings and Docker’s network boundary

For an additional check, inspect Docker’s reported proxy information after restarting the daemon, and review the service logs around the time of the pull. A missing proxy value points toward service configuration or an unsupported configuration path. A populated value does not prove the proxy is reachable, so compare it with the listener test. Keep the exact image reference and error message constant while comparing attempts.

Once the pull succeeds, remove temporary broad rules and retain only the configuration you need. Keep the proxy endpoint local where possible, preserve appropriate NO_PROXY entries for local services, and avoid putting credentials in a configuration file that is readable by unintended users. If the setup is managed by an administrator or organization policy, follow that policy rather than overriding it with a personal proxy configuration.

Docker Hub Proxy FAQ

Why does curl work through Clash while docker pull still times out?

The two commands may use different proxy settings. Your shell’s curl command can read environment variables or receive an explicit -x option, while the Docker daemon makes the registry request independently. Configure the daemon or its host environment, restart it where required, and confirm that the daemon can reach the same Clash listener. Also check whether Docker runs in a VM or a rootless environment with a separate network boundary.

Is a 401 response from registry-1.docker.io a failure?

Not by itself. The registry API may return 401 Unauthorized to an unauthenticated probe because it expects a token exchange. If the response arrives quickly, it can confirm that the request reached the registry. A timeout, connection refusal, DNS error, or TLS failure is a different result. Use an actual public-image pull to verify the full authentication and download flow.

Is one rule for docker.io enough?

Not always. Authentication, registry metadata, and image layers may involve different hostnames, including hosts outside the simplest Docker Hub domain rule. Observe the destinations during a failing pull and create focused rules for the traffic that actually needs the proxy. Keep specific rules ahead of broader rules, and verify the selected proxy group in Clash’s logs or connection view.

Should I use TUN mode or configure the Docker daemon?

Use daemon proxy settings when you can configure the component that makes the connection; they make the intended path explicit and are usually easier to verify. TUN mode can help capture traffic that does not honor proxy variables, but it may not capture traffic inside Docker Desktop’s VM or another isolated network. Test one method at a time and choose the one that works consistently in your actual Docker environment.