What Is Clash TUN Mode: How Virtual Adapters Capture System-Wide Traffic and How to Enable Them

DOC-01

The Coverage Limits of System Proxy Mode

Most users first encounter Clash through system proxy mode. It works like this: the client opens a local HTTP/SOCKS5 port, the operating system or browser writes that port into its proxy settings, and when an application sends a request it reads those settings and forwards the traffic to the local port, which Clash then processes. This path depends on two things — the application must support reading system proxy settings, and the protocol it uses must fall within what the proxy supports.

The problem lies exactly in those two prerequisites. Some command-line tools, some game clients, and some apps with their own custom network stacks don't read system proxy configuration at all, or they only support HTTP and not UDP. That traffic bypasses Clash entirely and goes straight out through the physical network adapter. The result: browser traffic routes correctly, but a particular client keeps failing to connect, or it always exposes your real IP — the root cause is usually here.

The blind spots of system proxy mode fall into three categories: processes that ignore system proxy settings, scenarios that rely on UDP where the proxy protocol doesn't support forwarding, and connections initiated by system services or drivers below the application layer. TUN mode exists specifically to close these three gaps.

DOC-02

How TUN Mode Works

TUN is a virtual network device that operates at the interface layer of the operating system's kernel network stack. When Clash Meta (mihomo core) enables TUN mode, it creates a virtual network adapter on the system and modifies the routing table so that the default route, or traffic to specific subnets, is directed to that virtual adapter. The interception point moves from application-layer proxy settings down to network-layer routing rules.

This distinction determines the difference in coverage. System proxy mode requires "the app to actively cooperate to be proxied"; TUN mode means "anything that follows the system route gets intercepted." Whether the connection comes from a browser, a command-line tool, or a background service, as long as its packets pass through the system network stack, they get routed to the virtual adapter and handed to the Clash core for rule matching — direct, proxied, or blocked, using exactly the same decision logic as regular proxy mode, just with a different traffic entry point.

The general flow looks like this:

1. The Clash core creates a virtual network adapter (such as a Meta or utun device) and assigns it a virtual IP range.
2. The core inserts rules into the system routing table pointing the traffic to be intercepted at that virtual adapter.
3. Packets sent by applications go through system routing and land on the virtual adapter instead of the physical one.
4. The Clash core reads data from the virtual adapter in user space and reconstructs the original TCP/UDP connection request.
5. The rule list determines whether the connection goes direct or through a specific proxy node, and the corresponding exit forwards it.

This mechanism requires the client to have system permission to create virtual network adapters and modify the routing table — which is why TUN mode needs extra authorization on every platform, unlike system proxy mode, which works with a simple toggle.

DOC-03

Key Differences Between the Two Modes

Putting system proxy mode and TUN mode side by side in one table makes it easier to decide which one fits a given scenario.

Simple takeaway: if all you need is browser traffic splitting, system proxy mode is enough and simpler to set up. If the goal is to bring all local traffic — including processes that ignore proxy settings — under rule-based control, TUN mode is the necessary option.

DOC-04

Platform-by-Platform Setup Steps

Each platform implements the underlying virtual adapter differently, and authorization methods differ too. The steps below are organized by platform.

Windows

TUN on Windows relies on the Wintun driver. Mainstream clients (such as Clash Verge Rev or Clash for Windows-style desktop clients) already bundle this driver in their installer. The first time you enable TUN, it usually triggers a driver installation confirmation or a UAC elevation prompt — you need to run the client as administrator and allow the driver installation request, or the virtual adapter can't be created.

1. Turn off system proxy mode (to avoid the routing rules of the two modes interfering with each other).
2. Restart the client as administrator.
3. Find the TUN mode toggle in settings and enable it, then click Allow when the driver installation prompt appears.
4. Open the "Network Connections" panel and confirm a virtual adapter named Meta or similar shows up as connected.
5. Visit an IP lookup page in your browser and check whether the exit IP now shows the proxy node's region.

macOS

macOS uses the built-in utun interface family. The client itself doesn't need an extra driver to create a virtual adapter, but it does need helper process privileges. Desktop clients (such as Clash Verge Rev or the ClashX family) will request installation of a privileged helper tool the first time you enable TUN, triggering a system password prompt — enter your current user password to authorize it.

1. Enable the TUN mode toggle in settings.
2. When the system shows an authorization prompt, enter your macOS login password to confirm.
3. If the client indicates it needs to install or update a helper service, follow the one-time installation prompt.
4. Check the system's Network settings panel to see whether a new virtual interface has appeared.

Recent versions of macOS have tightened permissions around system and network extensions considerably. If the authorization prompt never appears, or nothing happens after you click it, check System Settings → Privacy & Security for a blocked background component, allow it manually, and restart the client to try again.

Android

TUN mode on Android is implemented through the system's VPNService interface — the standard mechanism Android exposes to apps for system-wide proxying — and doesn't require root. Enabling it is similar to authorizing any regular VPN app.

1. Open the TUN or "virtual adapter" toggle in the client (such as Clash Meta for Android).
2. The system shows a "Connection request" dialog stating the app will establish a VPN connection; tap OK.
3. A VPN icon appears in the status bar, confirming the virtual adapter is active.
4. If you need certain local apps excluded from the proxy, uncheck them individually in the client's per-app proxy settings.

Note that only one VPNService can be active on the system at a time. If another VPN-type app is installed and running, the two will conflict, and you'll need to disable the other one first.

iOS

The equivalent mechanism on iOS is a personal VPN configuration under the NetworkExtension framework. The first time the client enables the corresponding mode, it requests installation of a VPN configuration profile, which requires confirming trust in the system prompt.

1. Enable the system-wide traffic capture toggle in the client's settings.
2. The system shows an "Allow VPN configuration" prompt; enter your device passcode or confirm with Face ID.
3. Check Settings → VPN to confirm the profile status shows Connected.

Linux

Creating a TUN device on Linux relies on the kernel's built-in tun module, so no separate driver is usually needed, but the client process needs the CAP_NET_ADMIN capability, or must run as root, to create the interface and modify the routing table.

# Run the client as root, or grant the binary network admin capability separately
sudo setcap cap_net_admin,cap_net_raw=eip /path/to/clash-core

Once the capability is granted, you can run the client as a regular user and enable TUN mode without launching the entire program with sudo every time, which reduces unnecessary privilege exposure.

DOC-05

Common Conflicts and Troubleshooting

Because TUN mode involves creating a virtual adapter and rewriting the routing table, problems usually show up as "connected but not working" or "no network at all" rather than a clear error message. Here are the most frequent scenarios.

Conflicts with other VPN or virtual adapter tools

If a corporate VPN client, a security suite's network filter driver, or another proxy tool's TUN component is running at the same time, multiple virtual adapters end up competing for routing priority. This typically shows up as intermittent connectivity after enabling TUN, or some traffic bypassing the expected path. The fix is to disable the other virtual network components first, keep only one running, confirm Clash's TUN works fine on its own, and then decide whether the two need to coexist and how to adjust routing priority.

DNS resolution issues

After enabling TUN mode, if domain resolution still goes through the system's original DNS instead of the Clash core, domains may resolve to the wrong address, or rules that match by domain name may fail to apply. This usually requires enabling the corresponding DNS takeover setting in the configuration so the core handles resolution uniformly, instead of capturing traffic at the network layer while resolution still relies on the system default DNS.

Virtual adapter creation fails

On Windows, this is often caused by a driver that wasn't installed correctly or insufficient permissions; on macOS, it's usually the privileged helper tool being blocked by system security policy; on Linux, it's usually a missing capability. A reasonable troubleshooting order: first confirm the client is running with sufficient privileges, then check system logs or client logs for a clear driver or permission error, and finally confirm no other program is already using a virtual network interface with the same name.

Some apps still aren't captured

A small number of apps bypass the system routing table entirely and send data through a self-specified network interface. TUN mode can't cover these cases either — it's a result of how the app itself is implemented, not a configuration mistake. If you confirm an app is never captured under any mode, check whether that app has its own independent proxy or direct-connection setting.

DOC-06

Should You Leave TUN Mode On All the Time

TUN mode offers more complete coverage, but it also adds another layer of routing rewrites at the system level, which means a longer troubleshooting chain when things go wrong. For everyday browsing with no need for fine-grained routing, system proxy mode is already enough — simpler to configure and less likely to conflict. When you need to cover games, CLI tools, background services, or other cases that don't cooperate with system proxy settings, TUN mode is the more reliable choice.

The two aren't mutually exclusive. Most clients let you switch between them at any time, so you can toggle based on what you're currently doing rather than committing to one mode permanently.