Clash TUN Mode Setup Guide: How Virtual Adapters Route Traffic

TUN vs. System Proxy: Different Traffic Entry Points, Same Routing Rules

A browser can reach a website while a terminal, game, or desktop app cannot. A common reason is that the app doesn't use the system proxy. System proxy settings expose an HTTP or SOCKS proxy, but each app decides whether to use them. TUN creates a virtual network adapter and routes IP packets to the proxy core, so individual apps don't need proxy support.

“Routing all traffic” describes the scope of the entry point; it doesn't mean every connection uses a proxy node. With mode: rule, connections entering TUN still match rules and can be routed to DIRECT, a proxy group, or REJECT. LAN traffic, excluded routes, other VPNs, and IPv6 paths can also affect what TUN actually captures.

Before You Start: Check Nodes, Permissions, and Configuration Overrides

First, verify your subscription and nodes using the system proxy, then enable TUN. If something breaks, you can focus on the virtual adapter, routes, and DNS instead of also questioning your subscription or node connectivity. Note your current mode, selected proxy group, and DNS settings, and keep a backup of a configuration that connects successfully.

1. Verify basic connectivity: Use rule mode, select a known-working node, and open a site that requires a proxy. A successful latency test only shows that its test target is reachable; it doesn't guarantee that a webpage will load.
2. Check core permissions: On desktop, check the service mode or helper service status. On Android, check VPN authorization. A core launched as a regular user may not be able to create a virtual adapter.
3. Temporarily disconnect other VPNs: Corporate VPNs, game boosters, and other TUN clients can all modify routes. Establish a baseline with just one client before testing whether they can coexist.
4. Choose where to edit: Prefer the client's override or configuration merge feature. Direct edits to a cached subscription file may be overwritten the next time it updates.
5. Check the active configuration: UI toggles may rewrite tun.enable, stack, or DNS settings. After saving, inspect the running configuration—not just the text in the editor.

The local proxy port and TUN are separate entry points. In this example, mixed-port: 7890 accepts HTTP/SOCKS proxy connections from apps, while DNS listens on 1053. Changing port 7890 won't fix a virtual adapter creation failure. Don't enter the DNS listening port in your browser's proxy settings.

How to Enable TUN on Windows, macOS, Linux, and Android

Windows: Start the Service Before Enabling TUN

Using the common Clash Verge Rev interface as an example, go to Settings → Service Mode, install the service as prompted, and grant the required system permissions. Once the service is running, enable TUN Mode. Options may appear in a settings card in different versions, and labels or groupings can vary. Make sure the service is running—not just that the toggle is on.

After enabling TUN, check the adapters under Windows Settings → Network & internet → Advanced network settings, or run the PowerShell command below. The virtual adapter name can be set in the configuration and may not include “Clash.” Seeing the adapter is only the first step; check the logs to confirm that route and DNS initialization succeeded.

Get-NetAdapter
Get-NetRoute -AddressFamily IPv4
route print

If the logs show insufficient permissions or device creation failures, first check that the service is installed correctly. Running as administrator can help with diagnosis, but for regular use, run the core through a service mechanism supported by the client. Configure firewall access for the specific app or service; don't leave the entire system firewall disabled.

macOS: Check the Helper Service and Network Permissions

Choose a client that supports mihomo TUN, install its helper service as directed in Settings, and then enable TUN. When macOS prompts you for authorization, verify the app's source before granting access. If the service installs but the toggle won't stay on, check the client logs and the network service status under System Settings → Network. Some permission prompts also appear under System Settings → Privacy & Security.

ifconfig
netstat -rn -f inet
route -n get 1.1.1.1

On macOS, virtual interfaces are commonly named utun followed by a number, but the system and other VPNs can create them too. The appearance of a utun interface alone doesn't prove that this client is routing traffic. Check the startup logs and the route for the destination address.

Linux: Check the TUN Device and Service Permissions

Linux usually requires an accessible /dev/net/tun, along with permission to create interfaces and modify routes. Authorization methods differ across distribution packages, desktop clients, and standalone core services, so follow the service installation instructions for your project. Containers also need additional device mappings and network permissions; don't assume the standard desktop steps apply.

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

When checking routes, include policy routing and all routing tables. Some implementations don't simply replace the default route in the main table, so ip route alone may miss the path handling your traffic. Don't run long-lived services with elevated privileges just to save a step.

Android and iOS: Understand How Each Platform Routes Traffic

Android GUI clients typically route traffic through the system VPN interface and request VPN authorization the first time they connect. With a mihomo-compatible client, import your configuration, enable its VPN/TUN mode, and check for the VPN icon in the status bar. Android usually allows only one active VPN service for regular users, so starting another VPN may disconnect the current one.

If only some apps can't connect, check the client's app access controls or per-app proxy settings. Excluded apps may fall outside the traffic capture scope. iOS clients often use Network Extension for traffic routing, but supported configuration formats and fields depend on the client. Don't assume a desktop mihomo YAML snippet will work as-is in every iOS app.

TUN Configuration: stack, auto-route, and DNS Hijacking

The following is a top-level snippet to merge into an existing mihomo configuration, not a complete configuration. It doesn't include nodes, proxy providers, proxy groups, or rules; keep those from your existing configuration. If the file already has dns or tun, merge the fields instead of adding another top-level key with the same name.

mode: rule
mixed-port: 7890

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

dns:
  enable: true
  listen: 127.0.0.1:1053
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  default-nameserver:
    - 223.5.5.5
  proxy-server-nameserver:
    - 223.5.5.5
  nameserver:
    - https://dns.cloudflare.com/dns-query

Choosing a stack

• system: Uses the system network stack. A useful option for compatibility testing; behavior depends on the operating system and environment.
• gvisor: Uses a userspace network stack. Try it for comparison when you encounter a specific issue with the system stack, but don't expect it to be faster on every device.
• mixed: Uses the system stack for TCP and gVisor for UDP. Start here, then adjust based on logs and app behavior.

Change one field at a time, then reconnect and test the same app. If game voice chat fails, also check whether the node protocol, server, and egress network support UDP. Changing the stack can't make up for UDP support that the outbound node lacks.

default-nameserver resolves hostnames for upstream DNS servers, while proxy-server-nameserver resolves proxy server hostnames. The example lists these separately to reduce DNS dependency loops at startup. Choose resolvers that are reachable on your current network and meet your privacy requirements. Whether an HTTPS connection to a DoH upstream goes through a proxy also depends on your DNS routing settings; a URL containing https alone doesn't tell you where the connection exits.

After Enabling TUN: Check Traffic Capture, Rules, and DNS

For testing, temporarily turn off the system proxy while leaving TUN enabled. This prevents the browser from continuing to use the local proxy port and masking a TUN capture failure. Also clear any proxy settings in the test app itself. Test a regular webpage first, then an app that doesn't normally use the system proxy, and watch for the destination in the client's Connections or Logs page.

1. Confirm the connection reaches the core: Start a new connection and check whether the destination domain or IP appears on the Connections page. Browsers may reuse an existing connection without creating a new entry right away; close the page and try again.
2. Confirm the rule match: Check the matched rule and final policy. A mainland China site matching DIRECT while a service outside China matches a proxy group is consistent with TUN capturing the traffic.
3. Confirm DNS resolution: If the client provides a DNS lookup tool, use it first. You can also query the local DNS listening port to verify that the built-in DNS responds.
4. Confirm UDP: Test with voice chat, a game, or another UDP app. A successful HTTP webpage load doesn't prove that UDP works.

# macOS / Linux: Test the local DNS listening port shown in the example
dig @127.0.0.1 -p 1053 example.com A

# Check whether the domain is reachable
curl -I https://example.com

With Fake-IP, an address in the 198.18.0.0/16 range may be an expected mapping result, not a DNS error. Domains on a filter list may also resolve to their real addresses. Don't use whether a mapped address responds to ping as the only test of webpage connectivity.

Public IP and DNS test sites only report the requests they can observe. An expected exit IP doesn't prove that every app, DNS request, or IPv6 connection is being captured. Also check app connection records, rule matches, and system routes.

No Internet After Enabling TUN? Troubleshoot Step by Step

Step 1: Turn Off TUN and Check the Basic Network

If you still can't connect with TUN off, troubleshoot Wi-Fi, your gateway, subscription, or node first. If connectivity returns as soon as TUN is disabled, keep a backup of the current configuration and focus on permission, interface, route, and DNS errors in the TUN startup logs. Temporarily set the log level to log-level: debug, reproduce the issue once, then restore your usual level to avoid logging excessive connection details over time.

Step 2: Check Adapter Creation and the Outbound Route

Messages such as permission denied or operation not permitted usually mean you should recheck service permissions. On systems with multiple adapters, check the automatically detected outbound interface. It should be the interface that actually connects to the internet—not another VPN or the current virtual adapter. Specify an outbound interface only after confirming that automatic detection chose the wrong one, and use a method supported by your core.

Step 3: Determine Whether the Problem Is DNS or Connectivity

If built-in DNS queries time out, check dns.enable, whether port 1053 is in use, upstream DNS reachability, and whether the configuration took effect. If queries succeed but websites won't connect, check the proxy node, rules, and TLS connection logs. “IP works, domain doesn't” can be a useful clue, but many sites require the correct Host and TLS SNI; direct IP access may fail normally too.

Step 4: Rule Out Conflicts with VPNs, IPv6, and Custom Routes

Disconnect other VPNs and test again. If the issue only affects IPv6 connections, check that IPv6 DNS responses, system routes, and node egress support are consistent. Temporarily restricting IPv6 can help isolate the cause, but treat it as a diagnostic step—not a permanent fix without explanation. If corporate or LAN devices are unreachable, check whether their subnets are being captured and whether existing rules route them directly.

Step 5: Adjust the stack and MTU as a Last Resort

If connections establish but large transfers stall, some pages load indefinitely, or a particular UDP app misbehaves, test different stacks one at a time. If you suspect a path MTU issue, try tun.mtu: 1400 in your existing configuration and note whether it helps. 1400 is a troubleshooting starting point, not the best value for every network. Don't change DNS, MTU, rules, and nodes all at once, or you won't know which change fixed the issue.

Restore Connectivity and Keep a Reliable Fallback

To roll back, turn off TUN first, wait for the core to exit or reload, then enable the system proxy if needed. A normal shutdown usually cleans up automatically created routes. If the network doesn't recover after the client exits unexpectedly, restart the service or client, then check for leftover interfaces and routes. If you're unfamiliar with routing tables, don't delete system routes in bulk.

• Only need proxy access in a browser? The system proxy is usually enough, with a smaller configuration scope and simpler troubleshooting.
• Need to route terminal or desktop apps? TUN is a better fit, but make sure permissions, DNS, and rules are all working.
• Need games or voice chat? In addition to TUN, verify UDP support on the node, the egress network, and the actual app connection.
• Use a corporate VPN regularly? Test startup order, outbound interfaces, and LAN access separately. One successful connection doesn't guarantee ongoing compatibility.

After setup, keep a record of the client name, core information, OS version, enabled fields, and steps to reproduce the issue. After switching clients or updating a subscription, check that your overrides are still present in the active configuration. For proxy entry points and common fields, see the user guide. For ports and configuration structure, see the advanced guide to ports.