Enable TUN Mode on macOS: Route Terminal and All Traffic Through Clash for Mac

System Proxy vs. TUN: Where Traffic Is Captured

With the system proxy enabled on a Mac, your browser may connect normally while Terminal commands time out. Usually, the two apps are taking different network paths—not sharing a broken setting. A system proxy provides an HTTP, HTTPS, or SOCKS proxy address that an app must detect and use. TUN routes matching IP traffic through a virtual network interface and into the proxy core.

Comparison	System proxy	TUN mode
What it takes to capture traffic	The app must use the system proxy settings or have a proxy configured separately	The connection must match a route associated with the virtual interface
Typical use cases	Browsers and apps that follow system settings	Terminal tools, some games, and other apps that connect directly
Permissions	May require permission to change network proxy settings	Usually requires a privileged helper to create the interface and routes
UDP traffic	A standard HTTP system proxy cannot capture UDP traffic universally	Requires support from the core, outbound protocol, and proxy node
How traffic exits	Determined by the core's operating mode and rules	Also determined by the core's operating mode and rules

“All traffic” is not an absolute guarantee of coverage. LAN exclusions, apps bound to a specific interface, routes from other VPNs, and system traffic can all affect what gets captured. Check the connection from the app you want to test rather than relying on the menu bar toggle.

Before You Enable TUN: Check the Core, Proxy Node, and Network

Check which core the client is running

Clash is a familiar name across the configuration and client ecosystem, but not every app uses the same core. Clash Meta continued development under the name mihomo. Check the running core version and its documentation to confirm support for a given TUN field. First, note the client version, core name, and core version from the client's About page, core manager, or startup logs. The GUI version and core version are separate details; one cannot stand in for the other.

Establish a working baseline first

Update your subscription and select a working node. With only the system proxy enabled, confirm that your browser can reach the sites you need to test.
Make sure the client is in Rule mode and check which policy group matches the domain you want to test. A successful latency test does not prove that HTTPS or UDP works.
Temporarily disconnect other personal VPNs, network accelerators, and proxy clients. If your organization manages a VPN, don't remove it without permission; check your organization's network requirements first.
Note the current system proxy status and local listening port, and back up your existing configuration so you can restore it if something goes wrong.

Check the port in your client settings. For example, 127.0.0.1:7890 is a valid proxy endpoint only if the local mixed port is actually set to 7890; this is not a universal default. TUN does not work by changing the system proxy to a different port.

Authorize and Enable TUN: Install the Service Before Routing Traffic

Menu names vary between clients. In Clash Verge Rev, for example, open Settings → Clash Settings and check whether Service Mode is installed and running, then enable TUN Mode. If the menus have moved in your version, look for the Service Mode and TUN Mode options in the interface. Don't assume another client's menu path applies.

Install the privileged helper service. Click the install button for Service Mode. When macOS asks for authorization, make sure the request comes from the client you just opened, then follow the prompts to authenticate as an administrator. Don't launch the entire GUI app as an administrator from Terminal.
Confirm that the service is running. After installation, the interface should show that the service is ready. If it still says the service is missing or can't connect, resolve the service issue before toggling TUN repeatedly.
Enable TUN Mode. Wait for the core to reload its configuration, then check the logs for errors such as failure to create a virtual interface or add routes. Success messages vary by version.
Keep Rule mode for your first test. Test your existing rules first. Don't change nodes, switch to Global mode, and edit DNS settings all at once, or you won't know which change affected the result.
Test TUN on its own. Once the service is stable, temporarily turn off the system proxy and test again. This helps confirm that the connection is reaching the core through TUN rather than through an HTTP proxy used by the browser.

On Apple silicon Macs, choose a client built for Apple silicon; on Intel Macs, choose the Intel version. Architecture mainly affects whether the app and helper run correctly. The fundamentals of TUN, routing, and rule-based traffic splitting are the same on both architectures.

Configuration Fields: Routing, Network Stack, and DNS Capture

If your GUI client has a TUN toggle, manage TUN through the interface first. Some clients merge GUI options into the runtime configuration, and direct edits to the original subscription file may be overwritten on update. For custom settings, use the client's override or configuration merge feature, then check that the final runtime configuration includes them.

This partial mihomo configuration example shows only TUN-related fields; it is not a complete, standalone subscription. It assumes you already have a working proxy, rules, and built-in DNS enabled:

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

enable: Enables TUN. The client may regenerate this value when the GUI toggle is off.
stack: mixed: Selects the mixed network stack. Check the current core's supported values and behavior; don't keep switching options at random just because the network is slow.
auto-route: Lets the core configure the relevant routes automatically. Custom routes, other VPNs, and network management policies can still affect the actual path.
auto-detect-interface: Attempts to identify the outbound interface. If connections fail after switching from Wi-Fi to Ethernet, restart the core and check which interface it detected.
dns-hijack: Sends matching traditional DNS requests to the built-in DNS handler. any:53 in this example does not mean “capture all encrypted DNS.”

Why Domain-Based Rules Depend on DNS

Many traffic-splitting rules rely on domain names, while TUN initially receives IP packets. The core needs to identify domains through DNS mappings, connection metadata, or configured sniffing. With fake-IP, the built-in DNS returns a mapped address that the core later associates with the real destination. Other DNS modes may associate domains with connections differently.

Browsers typically use HTTPS for secure DNS, sending traffic over port 443. Hijacking port 53 does not automatically turn that into plaintext DNS visible to the core. If rules match unexpectedly, check the browser's DNS settings, the core's DNS logs, and the rules that actually matched. Don't change a single field and assume domain detection is now complete.

Test TUN: Cross-Check the Interface, Terminal Connections, and Rules

Step 1: Check Network Status Without Treating an Interface Name as Proof

Open Terminal and run these read-only commands. The first displays system proxy settings, the second lists network interfaces, and the third looks up the route to a specified address:

scutil --proxy
ifconfig
route -n get 1.1.1.1

macOS virtual interfaces are often named utun followed by a number, but system services and other VPNs can create them too. Seeing utun3 doesn't prove it belongs to your client. Compare the interface list before and after enabling TUN, then check the client logs and routing results. A route lookup for one destination does not represent every destination.

Step 2: Tell Terminal Not to Use an App-Level Proxy

Test with the built-in `curl` command and use --noproxy '*' to bypass curl's application-level proxy. This option does not bypass TUN, making it useful for distinguishing the two traffic capture paths:

/usr/bin/curl --noproxy '*' --connect-timeout 10 --max-time 20 -I https://example.com

The example sets a 10-second connection timeout and a 20-second total timeout. An HTTP response only proves that the destination is reachable; on some networks, this site may connect directly anyway. While running the command, open the client's connection list and find the example.com connection. Check the matched rule, policy group, and final outbound.

Step 3: Compare What Happens When TUN Is Off

Keep the node, rules, and test URL unchanged. Record the connection logs with TUN enabled.
Turn off TUN, leave the system proxy off, and run the same command again.
Compare whether the client still sees the connection, whether the same rule matches, and how the request result changes.
Restore the settings you need. If the result is unchanged, check whether the destination was direct already, whether another VPN is still active, or whether the test app reused an existing connection.

When testing a game, also check the UDP sessions it actually opens. A webpage loading or a successful TCP test does not prove that a node supports the UDP traffic the game needs. Game login, asset downloads, and gameplay may use different domains and ports, so inspect each separately instead of testing only the launcher.

Common TUN Issues: Check Permissions, Routes, DNS, and Outbound Traffic in Order

TUN Turns Off Immediately or Fails to Create an Interface

First check whether the helper service is running and the core started successfully. Then check the runtime configuration for YAML indentation errors or fields unsupported by the current core. After an installer update, the client and older helper service may need to be brought back into sync. Use the client's service management options to repair them; don't manually delete system files you don't recognize.

No Websites Connect After TUN Is Enabled

Turn off TUN first and confirm that the basic network connection recovers. Then check node connectivity, whether the upstream DNS server is reachable, and which outbound interface appears in the logs. If a VPN is also running, pause one of them for a retest if you are authorized to do so. Overlapping routes can send connections into the wrong tunnel or prevent DNS requests from reaching the upstream server.

IP Addresses Connect, but Domain Names Fail to Resolve

Check whether built-in DNS is enabled, whether the upstream resolver is reachable, and whether DNS requests are being captured correctly. Don't replace a domain test by “opening the HTTPS IP address”: certificates and virtual hosts usually depend on the domain name. Run macOS scutil --dns to inspect resolver status, but also check how the specific app handles DNS.

Terminal Traffic Is Captured, but One App Still Connects Directly

First, distinguish between traffic that enters the core and matches a DIRECT rule, and traffic that never reaches the core. For the former, check rule order, policy group selection, and LAN exclusions. For the latter, check whether the app is bound to a specific interface, another network extension is capturing traffic, or the connection was already established before TUN was enabled. Quit and reopen the app to test a new connection; simply refreshing a window is less reliable.

TUN Stops Working After Sleep or a Wi-Fi Change

Disconnect any app that's retrying, then restart the core so it can detect the interface and rebuild routes. If the issue keeps happening, record the network type before and after the change, the core version, and relevant logs before reporting it. Before sharing logs, remove subscription URLs, proxy credentials, and other personal network information.

Turn TUN Off and Restore Network Settings in a Repeatable Order

When you no longer need TUN, turn it off in the client, confirm that your regular network connection is back, and then quit the app. If you enabled the system proxy, turn it off too if you no longer need it. Apps that follow system proxy settings may lose network access if the proxy still points to a local process that has exited.

Check Wi-Fi proxy settings: System Settings → Network → Wi-Fi → Details → Proxies. For a wired connection, select the corresponding network service.
Check VPN settings: System Settings → VPN. A client's underlying TUN interface may not appear here as a separate VPN entry, so no entry does not mean there is no virtual interface.
If your network doesn't recover after an unexpected quit, reopen the original client first, then turn off TUN and the system proxy normally. Restart your Mac if needed; don't clear the entire routing table.