What TUN mode actually does in Clash-class clients
TUN (short for network tunnel) mode creates a virtual network adapter on your operating system. Instead of asking each application to honor an HTTP or SOCKS proxy, the kernel forwards eligible IP packets into the proxy core—typically Mihomo, the engine many GUIs still label “Clash Meta.” The core then applies your rules, proxy-groups, and DNS policy the same way it would for browser traffic, but at a layer where stubborn binaries cannot “opt out” simply because they never read OS proxy variables.
Picture two doors into the same security checkpoint. System proxy mode posts a polite sign that well-behaved apps follow. TUN mode moves the checkpoint onto the road itself, so vehicles that would otherwise speed past the sign still get classified. Neither approach is magic: if your rules say “send this subnet direct,” TUN will happily obey. The win is coverage, not a forced detour through a remote node for every packet on earth.
If you are new to the broader Mihomo ecosystem, skim the Clash official home page for client context, then return here when you are ready to stop chasing “mystery leaks” application by application.
Why “traffic leaks” persist with system proxy alone
Leaks frustrate people because the failure mode feels personal: “I enabled the proxy; why does this one updater still phone home the old way?” In practice, leaks usually come from predictable categories:
- Apps that ignore system proxy settings, including some CLI tools, legacy installers, and background agents that open raw TCP sockets.
- Split stacks where IPv6, link-local, or mDNS traffic follows a path your HTTP rules never saw.
- DNS shortcuts that resolve differently from the browser you used to sanity-check connectivity.
- Competing overlays—corporate VPNs, zero-trust clients, or hypervisors—that reorder interface metrics after sleep or dock events.
TUN does not delete those categories; it shrinks the blast radius by giving the core a consistent place to intercept flows before they scatter across interfaces. Pair that with sane DNS settings and fresh rule providers, and most “ghost” leaks collapse into either a mis-typed bypass rule or an upstream node issue you can measure instead of debate.
When TUN is worth the extra surface area
Not every laptop needs TUN on day one. If you live entirely inside browsers and IDE tooling that respects the OS proxy, Rule mode plus system proxy may feel lighter: fewer drivers, fewer UAC prompts, and less wrestling with another virtual NIC in ipconfig output. Reach for TUN when you notice a repeating pattern—terminals, game launchers, sync daemons, or language package managers—that stubbornly bypass the tray toggle.
TUN also helps when you want policy parity between GUI apps and headless services without maintaining parallel environment variables on every shell profile. The trade-off is operational: you are installing a tunnel interface, often requiring elevation on Windows, and you must stay aware of other software that also thinks it owns the routing table. Treat TUN as a power tool, not a default hammer.
Prerequisites: permissions, drivers, and honest baselines
Before flipping the switch, freeze a baseline. Note your default gateway, active DNS servers, and whether a corporate VPN is supposed to be online. After TUN enables, you should be able to explain what changed in one sentence: “Traffic now hits the Mihomo stack first, then rules decide DIRECT versus PROXY.” If you cannot articulate that, pause and read your GUI’s documentation for service mode versus user mode.
On Windows, many clients install or bundle a Wintun-style driver. Accept the elevation prompt once, then reboot if the vendor release notes say so—half the “TUN is broken” threads are stale adapters after an incomplete upgrade. On macOS, approve system extension dialogs when prompted; ignoring them leaves the interface unregistered. On Linux, capabilities and iptables/nftables integration vary by distribution; follow your client’s wiki instead of cargo-culting random scripts.
Keep your core current. Older builds occasionally mishandle edge cases around UDP-heavy stacks or fast-changing rule providers. If you recently migrated cores, cross-check the Mihomo upgrade guide so YAML keys and TUN templates match the version your GUI ships.
What your profile must express (without turning this into YAML golf)
Exact keys differ slightly between GUIs, but the story arc is stable. You need a tun section that defines stack choice (userspace versus system), whether IPv6 is forwarded, and sometimes interface names or MTU hints. You still need healthy proxies and proxy-groups, because TUN does not invent outbound capacity—it only ensures packets reach the decision engine.
Your rules remain the contract of trust. If the last line is a blunt MATCH into a slow group, TUN will loyally follow that instruction for every captured flow. If domestic CDNs should bypass the tunnel, encode that explicitly with GEOIP, rule providers, or domain sets you maintain deliberately. For remote lists, the rule providers tutorial explains refresh cadence and ordering—stale GEOIP data produces surreal toggling that feels like “TUN is leaking” when the database is simply wrong.
DNS, fake-ip, and why TUN magnifies resolver choices
TUN and DNS are siblings that finish each other’s sentences. When fake-ip is on, the client may hand applications synthetic addresses that map back to domain-aware rules inside the core. That is powerful for split routing, but confusing if you expect ping or an external traceroute to resemble public DNS answers. Learn which tools read the system resolver versus their own bundled lists.
If domestic domains must resolve to real addresses for CDN selection, maintain a focused bypass list rather than disabling fake-ip globally. Watch for captive portals and hotel Wi-Fi portals: they often require direct DNS to a gateway IP; a maximalist TUN profile can stall until you temporarily carve out those hosts. Document the carve-outs you choose so future-you does not assume the tunnel “broke” after a router firmware update.
Platform notes that actually show up in support threads
On Windows, Hyper-V, WSL2, and some emulators create virtual switches that reorder metrics. If only WSL traffic misbehaves, you may need split guidance from both Microsoft and your Clash GUI rather than a single YAML tweak. On macOS, Little Snitch-class firewalls can prompt in parallel with TUN startup; approve the right binaries once to avoid half-initialized tunnels. On Linux, Wayland versus X11 rarely matters, but NetworkManager plugins sometimes rewrite DNS; watch resolvectl output when debugging.
| Symptom | First sane check |
|---|---|
| Browser works, terminal does not | System proxy versus TUN coverage; shell-specific proxy exports |
| Everything is slow, not “blocked” | MTU on TUN stack; try toggling GSO or follow vendor notes |
| DNS resolves but TCP never completes | Rule order sending traffic to a dead group; verify health checks |
| TUN toggles off after sleep | GUI service not set to restart; conflicting VPN seizing routes |
Living next door to another VPN or zero-trust client
Two tunnel owners in one routing table is a negotiation, not a feature. Some enterprise VPNs insist on being the default route; Mihomo may need explicit bypass ranges for the VPN control plane just to stay connected. Others allow “split tunnel” profiles that happily coexist once you declare which RFC1918 subnets must stay DIRECT.
When fights persist, prefer sequencing over desperation toggling: disconnect the corporate VPN, bring Mihomo up cleanly, then reconnect the VPN and observe which adapter wins. Screenshot the working state. If neither vendor documents coexistence, assume you will maintain a small set of static routes or interface metrics yourself—annoying, but still clearer than random reboots.
Troubleshooting playbook when “TUN is on but nothing works”
Elevation and helper services
Confirm the core or helper runs with the privilege level your GUI requests. On Windows, a user-mode tray app cannot install routes that require administrator approval; the symptom is a cheerful UI with zero effective capture. Re-run the installer’s service setup if needed.
Loopback and local development servers
Developers often run APIs on localhost. Most profiles exclude loopback by default, but aggressive global templates occasionally drag local ports into the tunnel. If hot reload breaks, add explicit DIRECT rules for your dev hostnames before blaming Webpack.
UDP, QUIC, and gaming
Some transports are UDP-heavy. If your node or middle box drops UDP inconsistently, TUN will surface that pain everywhere, not just in the browser. Test with a controlled tool, swap nodes if your subscription allows, and read provider guidance on QUIC versus TCP fallbacks.
Limits, ethics, and realistic expectations
TUN improves local policy enforcement; it does not grant immunity to network policies upstream of your machine. Corporate firewalls, ISP traffic inspection, and captive portals still exist. Respect local laws and organizational acceptable-use rules. If you are diagnosing connectivity for work, coordinate with IT instead of smuggling full-tunnel behavior past an explicit split-tunnel mandate.
Also remember observability: when everything routes through one engine, logging verbosity matters. Turn down debug spam after you finish troubleshooting so laptops stay cool and SSDs stay bored.
Documentation versus installers
When you want step-by-step menus beyond YAML theory, the Clash documentation hub collects tutorials that align with maintained clients. For repository history, issue trackers, and license text, upstream GitHub remains the right place to audit source—but keep daily installs on the curated channel so signatures and bundles stay consistent across machines.
Putting it together without turning your laptop into a science project
Compared with whack-a-mole per-app proxy variables, a well-tuned TUN profile feels quieter: terminals, browsers, and background updaters converge on the same routing story, and DNS stops being a secret third voter. The upfront cost is honest housekeeping—permissions, driver health, rule hygiene, and occasional coexistence tweaks when another VPN joins the party.
When you want that calmer baseline without chasing nightly artifacts, pick a client that documents its TUN stack, walk the checklist in this guide in order, and re-run a simple before-and-after test: one domestic site that must stay direct, one international site that must use your chosen group, and one DNS-sensitive hostname that used to misbehave. If all three behave, you have earned the right to close the terminal and get back to real work.