Same machine, different default route: why Docker Clash feels “ignored”

You start Mihomo in Clash Verge Rev on macOS, enable System Proxy, and your browser’s exit IP matches the airline you picked. Then you docker run --rm -it debian:stable-slim bash, type apt update, and mirrors stall or curl https://api.ipify.org still prints your home ISP. Nothing is “wrong” with the container; it is following Linux networking rules on the default bridge while your host uses a different stack where Clash owns outbound policy. Container proxy problems are search-shaped around phrases like Docker Clash, HTTP_PROXY, and bridge network because the mental model of “I turned on a proxy, so every process should see it” collides with how Docker isolates each container behind NAT.

This walkthrough is complementary to our WSL2 host bridge and DNS guide and the macOS shell environment guide: those articles focus on shells on the host glass; this one is for processes inside libnetwork’s default bridge, user-defined networks, and optional host mode. The goal is a reproducible sequence: prove TCP from the container to your mixed inbound, align allow-lan and firewall with that path, export http_proxy / https_proxy (and uppercase twins) the way real libraries read them, teach LAN listeners when the hop crosses from container namespace to host loopback, then separate DNS failures from proxy failures the way we do for Fake-IP in the Fake-IP and DNS article. If you still need a client build, our download page lists current installers; below assumes a working profile and a known mixed or HTTP port, often 7890.

ℹ️
Scope: We target Docker Engine and Docker Desktop on macOS, Windows, and common Linux distros, default bridge and user-defined bridge networks, and HTTP CONNECT on the Mihomo mixed port. Swarm, Kubernetes, rootless edge cases, and per-registry TLS MITM are mentioned only as pointers so the core HTTP_PROXY story stays testable in fifteen minutes.

What actually breaks: system proxy, TUN, and the container boundary

On the host, Clash may toggle OS-level proxy settings or install a virtual adapter when you enable TUN mode. A shell on macOS or Windows that reads those settings—or an app using the system configuration API—sees a curated path. A container’s primary network namespace, unless you map it to host on Linux, does not automatically inherit the host’s WinINET, Network Extension, or TUN interface. The container’s default gateway is the Docker bridge (docker0 or a user-defined bridge), and its first hop toward the public Internet is whichever route the Linux network stack inside that namespace computes, not the policy engine running on the host. That is the fundamental reason bridge network traffic “skips” Clash on Docker until you inject a forward proxy the application understands.

Many HTTP clients—curl, wget, Go’s default client, most Node HTTP stacks when env is respected—read HTTP_PROXY, HTTPS_PROXY, and NO_PROXY. apt, pip, and language-specific package managers have their own configuration surfaces; still, a consistent trio of environment variables is the first lever that works across stacks without recompiling. SOCKS-heavy workloads may need ALL_PROXY with a socks5h:// URL. None of that matters if the next hop to your Mihomo port never completes, so the next section insists on a TCP success path before you export anything.

Step 1: Choose the right host address for containers

Containers must dial whatever IP or DNS name on the host where your mixed inbound listens when allow-lan (or an explicit bind) exposes it beyond 127.0.0.1. Docker Desktop (macOS and Windows) provides the special name host.docker.internal that resolves to a routable address toward the host from inside the guest namespace. A minimal check:

docker run --rm debian:stable-slim sh -c "getent hosts host.docker.internal || true; apt-get update -qq && apt-get install -y -qq curl && curl -sS -o /dev/null -w '%{http_code}\n' --proxy http://host.docker.internal:7890 https://www.google.com"

Replace 7890 with your mixed port. The last line is expected to print 200 once Clash accepts the hop; if you see connection refused, jump ahead to the allow-lan section before you touch Compose files.

On native Linux without Docker Desktop, host.docker.internal may be absent or require --add-host=host.docker.internal:host-gateway (Docker 20.10+). The portable pattern is the documented host-gateway target, which expands to a bridge-appropriate address automatically. You can also compute the default gateway of the container (ip -4 route show default) and use that gateway IP, which is typically the user-defined bridge’s address on the host. Either way, the theme is the same: the container is not 127.0.0.1 on the host; treat it like a small VM talking across NAT.

Step 2: Make Mihomo accept container sources: allow-lan and listeners

Clash’s mixed inbound is often safe-defaulted to loopback only. That protects laptops on untrusted networks but blocks containers, which connect from another L3 scope. In Mihomo, enable allow-lan: true in YAML or the equivalent Allow LAN toggle in a GUI, and make sure the mixed port (or a dedicated port / socks-port) is bound to an interface that answers traffic from the Docker bridge range. Re-read the section on allow-lan and firewall for OS-specific firewall rules: macOS may prompt for incoming connections, Windows Defender may need an inbound rule, and on Linux, nftables or iptables on the docker0 path must not drop new SYN packets toward your Clash process.

After toggling, restart the core once and look at the listening sockets. If the UI still shows 127.0.0.1:7890 only, the container will never see an open port even if your HTTP_PROXY string is perfect. The acceptance test is still plain TCP: from inside a throwaway container, nc -vz host.docker.internal 7890 (with apt-get install netcat-openbsd if needed) or the curl --proxy probe above should succeed with sub-second handshakes.

Step 3: Set HTTP_PROXY and friends for a one-off docker run

Assuming the TCP probe is green, export standard variables so libraries agree:

export PROXY_HOST="http://host.docker.internal:7890"  # or http://172.17.0.1:7890 on Linux with known gateway
docker run --rm -e http_proxy="$PROXY_HOST" -e https_proxy="$PROXY_HOST" \
  -e HTTP_PROXY="$PROXY_HOST" -e HTTPS_PROXY="$PROXY_HOST" \
  -e NO_PROXY="localhost,127.0.0.1,::1" \
  debian:stable-slim sh -c "apt-get update -qq && apt-get install -y -qq curl && curl -sS https://api.ipify.org; echo"

Uppercase and lowercase both matter: some runtimes only read HTTP_PROXY. NO_PROXY should list on-cluster hostnames, local registries, and *.internal services you do not want to send through a remote exit. Getting container proxy wrong here often looks like “CI passes on a developer Mac but Linux CI times out” because the gateway IP and special DNS names differ between Docker Desktop and bare metal.

Step 4: Docker Compose maps: environment, env_file, and build-time proxy

Compose services repeat the same idea at scale. A minimal pattern in docker-compose.yaml (Compose V2) keeps a single truth for your team:

services:
  app:
    build:
      context: .
      args:
        http_proxy:  http://host.docker.internal:7890
        https_proxy: http://host.docker.internal:7890
    environment:
      http_proxy:  http://host.docker.internal:7890
      https_proxy: http://host.docker.internal:7890
      HTTP_PROXY:  http://host.docker.internal:7890
      HTTPS_PROXY: http://host.docker.internal:7890
      NO_PROXY:    localhost,127.0.0.1,::1,postgres

Build args matter when apt or apk runs during docker build; runtime environment does not reach those steps. If you only set runtime env, multi-stage images that install packages in earlier stages will still look “offline.” Align both or inject a private mirror that does not need the public Internet. For CI runners without Desktop, switch the literal hostname to the Linux gateway IP you measured once per host, or use extra_hosts to pin host.docker.internal with host-gateway.

Step 5: When network_mode: host is simpler—and when it is not

On Linux only, --network host (or network_mode: host in Compose) places the process in the host network namespace. 127.0.0.1:7890 then actually refers to the same loopback where Mihomo listens, so classic HTTP_PROXY strings using 127.0.0.1 can work without allow-lan across bridges. The tradeoff is you lose per-container port mapping, DNS isolation, and the usual compose networking model; two replicas of a service may collide on the same port. macOS and Windows Docker Desktop do not offer true host networking; do not expect this shortcut there. If your workload truly needs the host stack, a Linux dev box or a VM is the honest answer.

DNS: when “Clash is broken in Docker” is a resolver problem

Symptoms overlap: a Python requests call throws before a TCP connection forms, apt says “Failed to resolve,” and you blame Clash on Docker first. If Mihomo is using Fake-IP on the host but the container still uses 127.0.0.11 (Docker embedded DNS) or a corporate nameserver line, the IP you connect to and the SNI you send may not match the routing table Clash expected. Triage the same way as other Fake-IP articles: query from inside the container, compare to host behavior, and only then adjust proxy env. Stacking host-level TUN and container bridges without a clear owner for DNS is how teams burn afternoons.

Step 6: A verification checklist you can keep in a runbook

Use this list whenever someone says “HTTP_PROXY is set, still broken”:

  • Listener: from the container, raw TCP to host.docker.internal:7890 (or your gateway) succeeds in under a second.
  • Policy: the probe target domain in Mihomo is not an accidental DIRECT to a country you did not want—read one log line for the test URL.
  • Case: env | grep -i proxy inside the container shows both HTTP_PROXY and http_proxy as intended.
  • Split: NO_PROXY includes internal registry hosts and dependency caches so you are not double-proxying artifacts.
  • Build vs run: docker history and local rebuild prove whether install steps actually saw the same proxy the runtime uses.
  • Exit IP: with proxy enabled, curl -sS https://api.ipify.org (and without --proxy for contrast) shows the expected separation.
  • Health: after subscription changes, confirm upstream nodes using our subscription import and refresh flow before you re-debug Docker again.

Closing: explicit beats magical inheritance

Frustration with Docker Clash and bridge network setup usually comes from expecting inheritance: the host tray icon is green, so a container “should” follow. In practice, you prove TCP, align listeners with allow-lan, wire HTTP_PROXY the way cross-platform runtimes read it, separate build-time and runtime env, and only then consider host networking on Linux. Once those layers are unambiguous, behavior becomes predictable. When you are ready to standardize on a maintained client on the host side, download Clash for free and experience the difference—the container path will still need explicit env, but the policy engine it talks to will be the one you trust.