Fix TUN mode startup failures

TUN needs three things, and one missing is enough

The core has to create a virtual adapter, rewrite the routing table so the default route points at it, and hold enough privilege to do both. Miss one and the switch will not stay on. Before reinstalling anything, open the log page and scroll back to the moment you flipped it: the TUN lines there say whether permission was denied, the device could not be opened, or the route was never installed. That one line decides everything below.

• The virtual adapter. Windows relies on the Wintun driver; macOS and Linux use the system's own utun / tun device.
• The routing table. The default route has to move onto the virtual adapter, and on every mainstream system that is a privileged operation.
• Privilege. Administrator, root, or a background service the client installed ahead of time.

Windows: driver files, elevation, and service mode

• The driver file is gone. Clients normally ship the Wintun DLL next to the executable, and either an antivirus quarantining it or an incomplete extraction will stop the adapter from being created. Extract the archive again in full, then whitelist the client's folder.
• Not elevated. The blunt fix is right-click, Run as administrator. If doing that every single time annoys you, install service mode instead.
• Another VPN client is already running. A corporate VPN, a game accelerator, another proxy tool — whoever grabbed the default route first wins. Quit them properly; minimising to the tray does not count.
• Hyper-V, WSL2 and Docker Desktop each add virtual adapters, which makes the routing table busier than usual. TUN comes up but never wins the default route, and the symptom looks like enabled-but-no-internet.

Service mode (some clients label it Service Mode or system service) deserves its own note. It installs a resident system service that does the adapter and routing work, so the client itself no longer needs elevation. Clash Verge Rev has a separate install button for it in settings; once it is in place, an ordinary double-click can bring TUN up. Installing it triggers one UAC prompt, and that one you cannot avoid.

macOS: almost everyone gets stuck on the authorization step

• The first time you enable TUN, macOS asks for your password to authorize a background helper. Click Cancel and the prompt often never comes back, so the switch keeps flipping itself off. Quit and relaunch the client, or find the entry that reinstalls the helper, to make it ask again.
• In System Settings, under login items and background extensions, the entry belonging to the client may have been switched off. With it off, the helper cannot start.
• The utun device is taken. Corporate VPNs and tools like Tailscale create utun interfaces of their own. Disconnect them first, then try.

Linux: privileges and /dev/net/tun

1. Check that the tun device exists at all. Trimmed-down kernels and container environments often ship without it, and the tun module has to be loaded first.
2. A binary run as an ordinary user has no network administration rights. Either use the service mode your client provides, or grant the binary CAP_NET_ADMIN.
3. Reapply the capability after every core update. Overwriting the binary wipes it, and the failure comes back looking brand new.

ls -l /dev/net/tun
sudo modprobe tun
sudo setcap cap_net_admin,cap_net_raw+ep /path/to/mihomo

It starts, but nothing goes through

route print 0.0.0.0
netstat -rn
ip route show

Those three cover Windows, macOS and Linux; read them to see where the default route points now. Still on the physical adapter means auto-route never took effect, or something else put it back. Pointing at the virtual adapter and still dead moves suspicion to DNS and the firewall: TUN needs to intercept port 53 queries, and a system or antivirus firewall that blocks the virtual adapter lets traffic in but never out. One more case: system proxy and TUN switched on at the same time. Some clients break the loop for you, some do not, so while you are debugging leave exactly one of them on.