Clash TUN Mode Explained

1. System Proxies and TUN Capture Traffic at Different Points

If a browser can reach a website but a terminal tool, game, or updater cannot connect, first check whether the app uses a proxy. A system proxy only adds a proxy address to the operating system settings. An app must read and honor those settings to send requests to Clash. When an app opens TCP or UDP connections directly, enabling the system proxy alone usually does not change how those connections are routed.

TUN is a layer 3 virtual network interface that handles IP packets. When enabled, the kernel and client work together to create the interface and adjust routes, sending eligible packets to the proxy kernel. Apps do not need to understand HTTP or SOCKS proxies, but traffic still depends on routing, permissions, and kernel support.

The YAML fields in this article are based on mihomo. Older Clash kernels, forks, and mobile app wrappers do not all support the same features. Before troubleshooting, check the kernel name in the client’s About or kernel information screen. The app name alone does not tell you which kernel is running.

2. How Packets, Routes, and DNS Work Together

From App to Outbound Connection

1. The app resolves a domain name and connects to the resulting IP address.
2. The operating system checks its routing table and sends packets that match TUN routes through the virtual interface.
3. mihomo reads the packets and selects a policy based on the destination address, domain mapping, and matching rules.
4. The kernel opens a direct or proxied outbound connection through the physical network adapter, then returns the response to the app.

The physical network adapter still connects to the router, Wi-Fi, or mobile network. TUN does not replace the actual network connection or increase node bandwidth. The kernel’s own outbound traffic must avoid re-entering TUN and creating a loop; automatic interface detection, interface binding, and route handling all play a part. Running another VPN at the same time can also cause the two apps to compete over the default route or policy routes.

Why DNS Often Determines Whether TUN Works

Rules may match domain names, but network packets primarily contain IP addresses. If DNS requests bypass the kernel, domain-to-IP mappings may be incomplete. Enabling the kernel’s DNS and routing regular DNS requests through it helps match domain rules to connection records.

In fake-ip mode, the app receives a synthetic address, such as one allocated from 198.18.0.1/16. The kernel then uses its mapping to recover the original domain. This is not the destination server’s real address or a node IP. Device discovery, local network services, and apps that rely on real DNS results may need exceptions; adjust fake-ip-filter for the relevant domains.

• dns-hijack captures matching DNS traffic, not all encrypted DNS.
• Browser DoH typically uses HTTPS and cannot be handled simply by intercepting port 53.
• Apps keep using cached DNS results until they expire. After changing DNS settings, restart the app you are testing and clear the system DNS cache if needed.

3. mihomo Configuration and Preflight Checks

Keep TUN disabled while you verify that the subscription, nodes, and rules work through the local mixed port. The example uses 127.0.0.1:7890 as the local proxy address; if your client shows a different port, update the test command too. If the node itself cannot connect, fix the node or subscription first so you do not mistake that for a virtual adapter problem.

curl --proxy http://127.0.0.1:7890 --connect-timeout 10 -I https://example.com

In Windows PowerShell, use curl.exe to avoid older environments interpreting curl as a different command. An HTTP response confirms that this proxy request reached the destination service; it does not prove that every site, UDP, or TUN is working properly.

Example to Merge into an Existing Configuration

mixed-port: 7890
allow-lan: false
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:
    - 223.5.5.5
    - 1.1.1.1

GUI clients often generate the final configuration. Direct edits to cached subscription files may be overwritten when the subscription updates, so use the client’s override, configuration merge, or TUN settings where possible. Do not add duplicate top-level tun or dns keys. After making changes, check the active configuration and startup logs, not just the text in the editor.

4. Setup and Permissions by Platform

Windows: Set Up Service Permissions Before Enabling the Virtual Adapter

1. In your client’s settings, look for Service Mode or an option to install the service, then follow the prompts to grant administrator permissions. Some clients also support running directly as an administrator; follow the client’s documentation for the recommended method.
2. Make sure the service is running, then enable TUN Mode or Virtual Adapter Mode. In Clash Verge Rev, look under Settings for Service Mode and Virtual Adapter Mode. The names and locations may differ between builds.
3. Check the logs for permission errors, adapter creation failures, or route errors. A lit toggle only means the setting was submitted; it does not confirm that the kernel successfully captured traffic.
4. Use Get-NetAdapter to check network interfaces and route print to compare routes before and after enabling TUN. Some implementations use split routes or policy routing and may not visibly replace the default route.

If your organization’s device policy blocks virtual adapters or background services, ask the device administrator to adjust the permissions. Do not disable the entire system firewall for testing. Check the client and kernel’s allowed rules first, then use the logs to pinpoint the failing step.

macOS: Authorize the Helper Service and Check the Outbound Interface

Desktop clients typically need to install or authorize a privileged helper service to create the TUN interface and adjust routes and DNS. Complete the system authorization prompts, then enable TUN. Use ifconfig to inspect utun interfaces, but macOS and other VPNs create these too. The presence of an interface alone does not prove that the current client created it.

ifconfig
route -n get 1.1.1.1
scutil --dns

Use startup logs, route queries, and connection records to verify the result. If you use a corporate VPN, another network extension, or network filtering software, note the existing state and change one variable at a time. Do not identify a conflicting VPN based only on the utun number.

Linux: Check the TUN Device and Network Permissions

Desktop clients may use a service to obtain the required permissions. Command-line mihomo needs permission to create interfaces and set routes. Running it as a root service is common; you can also configure capabilities to meet your deployment requirements. However, granting a single capability to the binary is not guaranteed to work for every DNS and routing setup.

ls -l /dev/net/tun
ip link show
ip rule show
ip route show table all
resolvectl status

resolvectl applies only to systems that use systemd-resolved. Containers need the TUN device and appropriate network capabilities in addition to process permissions; setting enable: true inside the container is not enough. Before changing routes on a remote server, keep a second management connection or console session available to avoid disrupting the SSH return path.

Android and iOS: Use the Built-In VPN Integration

On Android, Clash clients typically capture device traffic through the system VPN permission flow, so desktop service installation steps do not apply. When connecting for the first time, approve the system VPN prompt and check the per-app proxy list: apps excluded there will not use the client even if the rules are set to global mode. An existing VPN connection can also prevent the client from connecting.

Android’s Always-on VPN and Block connections without VPN settings affect what happens if the connection drops. With blocking enabled, quitting the client may temporarily leave the device without internet access, so make sure you know how to restore connectivity. On iOS, compatible clients create a VPN configuration through Network Extension and request authorization through the system prompts. Desktop mihomo TUN fields are not universal configuration options for every iOS client.

5. Verify Traffic Capture, Not Just the Toggle

When testing TUN, temporarily disable the system proxy and remove proxy environment variables from the test terminal so a request cannot succeed through an explicit proxy instead. Restore your original settings when you are done. The command below bypasses proxy settings for this curl request, but the operating system can still route it through TUN.

curl --noproxy "*" --connect-timeout 10 -I https://example.com

1. Check connection records: After running the command, find the destination domain or IP on the client’s Connections page. Check the matched rule and the actual outbound policy.
2. Check route changes: Compare routes and policy routes with TUN off and on. Make sure another virtual adapter has not been selected as the outbound interface by mistake.
3. Test the actual app: Launch an app that normally ignores the system proxy and check its new connections. Disconnect and reconnect any long-lived connections.
4. Test UDP separately: Use an app that actually sends UDP traffic. A successful HTTP request does not guarantee that games, voice calls, or QUIC will work.

If a connection record shows DIRECT, the traffic may have reached the kernel and simply matched a direct rule; that does not mean capture failed. Conversely, if a page loads in the browser but there is no matching connection record, first check for browser extensions, built-in proxies, cached content, or another VPN.

6. Troubleshooting by Layer

A direct rule is not the same as a route exclusion

For example, IP-CIDR,192.168.0.0/16,DIRECT,no-resolve means matching traffic reaches the kernel and is routed directly. It is not a TUN exclusion at the operating system level. Printer discovery and broadcast or multicast traffic also depend on the app’s discovery method and the client’s support. Adding a single direct rule for TCP will not necessarily solve the problem.

Do Not Start by Changing the MTU

Check the path MTU only after ruling out DNS, node, and rule issues, and only if a few sites hang during loading or large transfers fail while small requests work. If the current value is 1500, note it and temporarily try 1400 for comparison. This is a diagnostic value, not a recommended setting for every network. Restore the original value if there is no improvement, and avoid changing the protocol stack, DNS, and MTU at the same time so you can identify the cause.

Restore Settings in This Order After Disabling TUN

1. Disable TUN in the client first, then wait for the interface and automatic routes to be removed.
2. Restore your original system proxy, DNS, and other VPN settings, then reconnect your test apps.
3. If connectivity is still down, check for leftover routes and DNS settings. Restart the client or its service normally before considering other steps; do not delete unknown system routes.

A stable configuration should answer three questions: which traffic enters the virtual adapter, where DNS is resolved, and which policy each connection ultimately follows. Matching these answers to the logs is more effective than repeatedly switching to global mode or changing nodes. Use TUN only when you need to capture traffic from apps that ignore system proxy settings and are prepared to handle the required permissions and route changes. If a browser or explicit proxy already meets your needs, you can keep using that setup.