Clash TUN Mode Setup

How TUN Captures Traffic

Clash TUN mode uses a virtual network interface to receive IP packets. The core then identifies connections, matches them against rules, and selects an outbound route. It is useful for apps that ignore system proxy settings, including some command-line tools, games, and desktop apps that establish their own network connections. Before enabling it, make sure the client uses a core with TUN support. Clients with the same name may ship with different cores and permission settings.

The configuration examples here target mihomo, the successor to Clash Meta. Available options may differ in the original Clash, legacy Premium cores, and other forks. Check the core information in your client or its startup logs, then verify settings against the documentation for that core. A TUN toggle in the interface does not guarantee that every configuration option is supported.

1. App starts a connection: The operating system looks up the destination in its routing table.
2. Route points to the virtual interface: Packets selected for capture enter TUN instead of going straight out through the physical network adapter.
3. Core applies routing rules: Rules based on domains, IP addresses, processes, and other criteria determine whether traffic is proxied, sent directly, or blocked.
4. Connection reaches its outbound route: Proxied traffic still uses a physical network interface. The core must prevent its own outbound connections from being routed back into TUN.

TUN vs. System Proxy

A system proxy typically provides an HTTP or SOCKS endpoint to apps that support those settings. For example, with a local proxy at 127.0.0.1:7890, only connections that explicitly use that endpoint are handed to the core. TUN works through the network interface and routing table, so apps do not need to know about the proxy port.

“All traffic” is a useful shorthand, not a guarantee of coverage. Existing connections, uncaptured IPv6 routes, higher-priority routes from other VPNs, and platform-specific limitations can all affect what gets captured. Decide which apps you need to route, then verify their connections in the logs—don’t rely on the toggle alone.

For initial troubleshooting, turn off the system proxy and enable only TUN to reduce variables. They can work together, but a successful browser test with both enabled does not prove TUN is working: the browser may still be connecting through the system proxy port.

Three Checks Before You Enable TUN

Verify the proxy outbound first

Use the system proxy to confirm that a connection works first. Check that your subscription is imported, the proxy group has an available node, and your rules do not reference a policy name that does not exist. TUN cannot fix a failed node connection, an empty subscription, or an authentication error. Keep a backup of your original configuration and change one category of settings at a time.

Check permissions and network conditions

• Windows: Use the client’s service mode if available. Install the service with administrator privileges so it can run the core; you do not need to run all your everyday apps as an administrator.
• macOS: The client may use a helper app to obtain network management permissions. Approve the system prompts and make sure security software is not blocking interface creation.
• Linux: Creating a TUN device and changing routes usually requires root or suitable network management capabilities. Containers also need access to /dev/net/tun; elevating process privileges alone may not be enough.

Temporarily disconnect other tunnels

Disconnect other VPNs, game accelerators, and similar proxy clients first. You may not need to turn off a corporate VPN or virtual machine network, but simplify the setup as much as possible during initial testing. If they must run together, compare route prefixes and priorities rather than letting both clients repeatedly replace the default route.

mihomo TUN Configuration Example

Merge this snippet into your existing configuration; it is not a complete subscription with proxy nodes. Keep your existing proxies, proxy-groups, and rules. If the file already contains tun or dns, edit that section instead of adding a duplicate key at the same level.

mixed-port: 7890
mode: rule
log-level: info

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53
    - tcp://any:53

dns:
  enable: true
  listen: 127.0.0.1:1053
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - 1.1.1.1

stack: Choose a Packet Processing Mode

mihomo commonly supports system, gvisor, and mixed. system uses an implementation tied to the system network stack; gvisor uses a user-space network stack; mixed typically handles TCP with system and UDP with gVisor. Support varies by platform and core build.

For your first setup, start with the client’s default; this example uses mixed. Change stacks only when you can reproduce a specific connection issue, then restart the core and test again. These are different implementations, not a performance ranking—no single option is faster on every device.

auto-route and the Outbound Interface

auto-route: true lets the core add the routes needed to capture traffic; it does not replace administrator authorization. auto-detect-interface: true detects the interface used for outbound connections, helping proxy traffic avoid looping back into its own tunnel. If Wi-Fi, Ethernet, and a VPN are all active, check which interface was detected.

If the network stops working only after waking from sleep or switching Wi-Fi, restart the core so it can detect the outbound interface again, then inspect the routes. Don’t immediately hard-code the physical adapter’s address: a fixed interface name may stop working when the network changes.

dns-hijack and the DNS Listening Port

any:53 captures standard UDP DNS requests entering TUN, while tcp://any:53 covers the corresponding TCP DNS requests. Matching requests are passed to the core’s DNS module; the system DNS server does not need to be set to 127.0.0.1:1053.

listen: 127.0.0.1:1053 creates an additional local listening endpoint for the DNS module. It serves a different purpose from mixed-port: 7890; port 7890 is not a DNS port. These hijack rules cannot directly capture an app’s own DoH or DoT traffic, which does not use standard DNS on port 53.

Enable TUN on Windows, macOS, and Linux

Windows: Start the Service, Then Enable TUN

1. In the client settings, make sure you are using a mihomo core with TUN support, then test your subscription connection.
2. Find the service mode or service management option, then install and start the service as prompted. Menu names vary by client, so follow the options in your current version.
3. Enable TUN and check the logs for permission errors, interface creation failures, or route errors.
4. Go to Settings → Network & Internet → Proxy and temporarily turn off manual proxy setup to rule out the browser still using the system proxy.
5. Use PowerShell to inspect network interfaces and IPv4 routes, then start a new connection.

Get-NetAdapter -IncludeHidden
Get-NetRoute -AddressFamily IPv4 |
  Sort-Object DestinationPrefix, RouteMetric
curl.exe --noproxy "*" -I https://example.com/

--noproxy "*" tells this curl request not to use an explicit proxy, but it does not bypass TUN routing. The example address is for connectivity testing only. After a successful request, check the client’s connection list to confirm which rule and outbound route were used. Some tunnel interfaces may not appear fully in the adapter list, so check the routes and logs as well.

macOS: Approve Permissions and Check Routes

1. Use the client’s settings to install or enable any required helper app, then approve the requested system permissions.
2. Disconnect other VPNs, then enable TUN. Go to System Settings → Network and check for any other active network tunnels.
3. To rule out the system proxy, check the HTTP, HTTPS, and SOCKS proxy settings under Details → Proxies for the active network service.
4. Check interfaces and routes in Terminal, then compare the results with the client’s connection logs.

ifconfig
netstat -rn -f inet
route -n get 1.1.1.1
curl --noproxy '*' -I https://example.com/

macOS virtual interfaces often have names that include utun, but other system services can create them too. Seeing a utun interface does not prove it belongs to the current client. Compare the interfaces before and after enabling TUN, and check the route used by your test connection.

Linux: Check the Device, Permissions, and Policy Routes

Desktop clients usually provide a privilege escalation or service installation flow. If you run the core directly, validate the configuration first, then start it through a properly configured system service. Don’t grant excessive permissions to a regular app or your entire user directory just to test quickly.

mihomo -t -f config.yaml
test -c /dev/net/tun && echo "TUN device available"
ip link show
ip rule show
ip route show table all
curl --noproxy '*' -I https://example.com/

mihomo -t mainly checks whether the configuration can be parsed; it does not prove the core has permission to modify routes at runtime. Linux may also use policy routing tables, so checking only the main routing table can miss capture rules. Check both ip rule and all routing tables.

Verify Traffic Capture, DNS, and UDP

Verify TUN in stages. A webpage loading only shows that one connection path works; it does not prove DNS, UDP, IPv6, or every app is working as expected. Follow these steps to build a clearer picture.

1. Interface layer: Compare virtual interfaces and routes before and after enabling TUN, and check for persistent errors. Interface names and default route entries do not look identical on every platform.
2. Connection layer: Turn off the system proxy, make a new connection with curl using --noproxy, and find the request in the client’s connection list.
3. Routing rules: Check which rule and proxy group matched. A DIRECT match is a routing result, not proof that TUN failed.
4. DNS layer: Check DNS logs and distinguish standard port 53 requests from app-level encrypted DNS and cache hits.
5. UDP layer: Test with an app that actually sends UDP, and confirm that the selected node and protocol support UDP forwarding. A successful TCP test does not prove UDP works.

With Fake-IP enabled, DNS lookups for some captured domains may return mapped addresses in the 198.18.0.0/16 range. This is expected for that configuration; it is not the website’s real public IP address. Filtered domains, apps using their own encrypted DNS, and cached requests may behave differently.

Troubleshooting Network Issues After Enabling TUN

If a LAN printer, NAS, or router admin page becomes unreachable, first check which rule matches the destination’s private IP address. If traffic is being sent through a proxy, add a direct rule for the relevant subnet. If it is already going direct, check LAN routes and firewall settings. Don’t assume every LAN issue is caused by Fake-IP.

Changing rules only affects outbound route selection. If packets never reach the core, adding a domain rule won’t help; if the proxy node itself is unreachable, changing stack repeatedly won’t fix it. Before making another change, note five things: the app, destination, matched rule, error log, and whether another VPN is enabled.

Subscription Updates and Restoring Network Settings

Some clients save the TUN toggle as a local setting, while others merge interface options into the runtime configuration. Updating a subscription file may overwrite your changes. Use the client’s supported override, merge, or persistent configuration feature, and check the effective configuration after an update—not just the snippet saved in an editor.

When you’re done, turn off TUN before exiting the client normally so the core can remove routes it created. If the network remains disrupted after an unexpected shutdown, restart the client and turn off TUN to clean up, then check whether the system proxy was left enabled. Don’t delete system routes in bulk unless you know where they came from.

• Only need a browser proxy? A system proxy is usually easier to set up and troubleshoot.
• Need to route apps that don’t support proxies? Enable TUN and verify the routes and connection records.
• Need multiple VPNs to coexist? Define the address ranges each one should capture before designing rules and routes.
• Need help diagnosing an issue? See Troubleshooting. For basic imports and mode settings, see the Clash Configuration Guide.