Network Guide Featured Tags: Clash Verge Rev macOS TUN mode Mihomo

Turn On TUN in Clash Verge Rev on macOS:System Extension Setup

This guide answers the practical “how do I turn it on?” question for Clash Verge Rev on macOS: where TUN mode lives, why Apple forces a system extension approval path, how YAML tun settings line up with Mihomo, and what to check in routing after permissions succeed. It deliberately stays on the Apple stack—if you need Windows-specific blackout recovery, treat that as a different playbook because the firewall and driver choreography there is not interchangeable with Network Extension prompts on a Mac.

Approx. 20 min read
Clash Editorial
Table of Contents

1. Why TUN on macOS With Clash Verge Rev

System proxy mode is excellent for browsers and many GUI apps that honor the macOS “Web Proxy” and “Secure Web Proxy” fields. It is also the fastest way to prove that your subscription import, outbound health, and basic rule mode selection behave before you ask the kernel for anything fancier. The limitation shows up as soon as you meet binaries that bypass those settings: some games, bespoke updaters, certain Go or Rust CLIs, and plenty of language package managers unless you export proxy environment variables everywhere.

TUN mode addresses that gap by presenting a virtual interface so packets can enter Mihomo before user-space apps make irreversible socket choices. On Apple platforms the privilege boundary is strict: enabling that path almost always means loading a Network Extension-style component and walking through Privacy & Security dialogs that read scarier than they are if you downloaded Verge from a trustworthy channel. The upside is consistency—once macOS trusts the extension and your merged profile enables tun, you spend less time arguing with apps that pretend proxies do not exist.

If you are still installing the app or importing your first profile, start with our Apple Silicon focused install walk-through; it covers downloads, Gatekeeper hygiene, and the moment you choose between proxy and tunneling. This article assumes Verge launches, a profile activates, and you can browse through a conventional listener—then we layer TUN mode on top.

Tip: Treat TUN as a macOS contract between three parties: Clash Verge Rev’s helper, Mihomo’s merged YAML, and Apple’s extension approval state. If any one leg is missing, you will see “enabled” chrome in a UI while packets stubbornly exit the regular interface.

2. Prerequisites Before You Touch TUN

Work through four inexpensive checks so you are not debugging subscription TLS errors and extension policy at the same time.

  1. Profile health. Update the remote YAML, open the logs pane, and confirm proxy groups show latency instead of wall-to-wall timeouts. If every node fails, fix the upstream before TUN amplifies the confusion.
  2. Listener sanity. Note the mixed or SOCKS port your template exposes—often something like 7890 in community snippets—and verify a browser session succeeds with system proxy first.
  3. Competing tunnels. Quit other commercial VPNs, “Internet security” filters, or experimental firewall tools that already registered a network extension. macOS rarely tolerates two aggressive stacks politely wrestling for the default route.
  4. Administrative reality. Managed Macs may block user-approved system extensions entirely. If you live under MDM, read internal policy before expecting Personal VPN or System Extension toggles to appear.

Readers who already enabled system proxy yet Safari still behaves oddly should keep the macOS system proxy and network extension repair guide handy; it focuses on permission pathologies, whereas this piece assumes you now want the tunnel specifically.

What we are not covering

Windows users hunting blackout fixes after TUN misfires should open our Windows TUN routing and firewall article. That environment leans on different APIs and recovery rituals; mixing the playbooks wastes time.

3. YAML tun Block Mihomo Actually Reads

Clash Verge Rev is a control plane. The data plane still obeys the merged configuration Mihomo loads, which means your effective profile must contain a tun map the core understands. GUI toggles are convenient, yet they cannot override a remote template that hard-codes enable: false or strips auto-route semantics unless a mixin override repairs it.

A pragmatic starter shape—always cross-check against your exact Mihomo release notes—looks like the following snippet. Values vary by operator; treat this as structural guidance, not a copy-paste law:

tun:
  enable: true
  stack: system
  auto-route: true
  strict-route: false
  dns-hijack:
    - any:53

Field-by-field intuition for macOS readers:

  • enable. Must be true after merges; otherwise the UI toggle is theatrical.
  • stack. system leans on the host’s native facilities; some users experiment with userspace stacks when maintainers document compatibility. Follow the pairing guidance your Verge bundle ships with.
  • auto-route. When true, Mihomo participates in default-route steering for matched traffic. Turning it off while expecting global capture is a common “nothing happens” trap.
  • strict-route. Tightens admirably to avoid leaks yet can surprise multi-homed setups. Begin slightly looser, prove success, then tighten while watching for captive portals or corporate Wi-Fi quirks.
  • dns-hijack. Directs resolver traffic into the tunnel so split-DNS plans actually execute. If domestic recursion must stay untouched, align this list with the resolver strategy your operator documents rather than cargo-culting a random snippet.

Advanced IPv6 topologies deserve their own treatment—if you run dual-stack interfaces, pair this article with IPv6 dual-stack routing guidance before blaming TUN alone for odd path selection.

Warning: Never paste giant YAML blobs from forums without version control. A single indentation error prevents Mihomo from parsing the profile, and the failure mode often masquerades as “macOS blocked TUN” when the core never restarted cleanly.

4. Enable TUN From the Clash Verge Rev UI

Exact menu labels shift between releases, but the ergonomic story is stable: open the settings or service panel, locate the TUN switch, and flip it after your YAML permits tun.enable: true. Expect a sequence of prompts—helper installation, administrator password, or firewall allowances—when Verge wires its child process to the packet path.

Watch for these practical signals:

  • Core restart. Mihomo may reload when TUN toggles. Give the restart a few seconds before launching connectivity tests; racing the reload invites false negatives.
  • Login items. Some builds register background helpers so the tunnel can resurrect after sleep. If macOS later revokes that login item, TUN may fail silently until you re-authorize.
  • Permission loops. If the UI returns to “off” immediately, read the toast or log line—often it is an extension rejection rather than a mystery crash.

When experimenting with both proxy modes, disable system proxy cleanly before judging TUN outcomes; overlapping captures confuse both humans and whichever automation script tests your routes.

5. System Extension and Privacy & Security

Apple gates packet-tunnel capabilities behind system extension approval. After you toggle TUN, macOS may display a notification that a system extension was blocked. Treat that as expected paperwork, not a verdict on Clash itself—provided you installed the authentic build.

  1. Open System Settings → Privacy & Security.
  2. Scroll to the section that lists blocked or pending extensions from Clash Verge Rev or its developer team.
  3. Click Allow, authenticate with Touch ID or password, and confirm you meant to approve the helper tied to the app bundle you launched from /Applications.
  4. If the OS demands a restart, schedule it; some macOS versions refuse to finalize route programming until the reboot completes.

Corporate laptops sometimes lack the Allow affordance entirely—MDM profiles preempt user consent. In that scenario, no amount of YAML tweaking enables TUN; you need IT to bless the extension or supply an approved client.

Security-conscious readers should double-check code signatures in Activity Monitor or the firewall prompt: the executable path must match your known-good install. Malware occasionally mimics proxy UIs, and TUN capability hands attackers a dangerously capable foothold if you approve the wrong bundle.

Local firewall interactions

macOS Application Firewall prompts may appear when Mihomo listens on localhost or when the tunnel adapter comes online. Allow connections for the signed Verge components on trusted networks; denying them produces “TUN works occasionally” heisenbugs tied to sleep/wake cycles.

6. Confirm Routes and the Virtual Interface

Once permissions succeed, prove the operating system sees a tunnel rather than trusting a green LED in the UI.

  • Interface inventory. Open Terminal and run ifconfig. Look for a utun entry whose MTU and flags resemble other VPN products you trust. Absence strongly suggests the extension never attached.
  • Routing table. Run netstat -rn and scan default routes. Depending on policy, you may observe gateway shifts that align with your auto-route intent. If defaults look untouched while TUN claims enabled, revisit the YAML auto-route pairings.
  • VPN flags via scutil. scutil --nc list occasionally surfaces the Personal VPN entry Verge registers. It is a secondary signal, not a replacement for packet traces, yet it helps when debugging menu-bar confusion.
Observation Likely meaning Next step
No new utun after toggling Extension blocked or core never restarted Revisit Privacy & Security, read Mihomo logs, reboot once
utun appears but IP checks show ISP Rule sends traffic DIRECT or DNS leaks around tunnel Tail logs while loading test hosts, audit DNS hijack lists
Routes flap after sleep Helper or login item suspended Reallow firewall, confirm login items, toggle TUN off/on

If numeric tooling feels opaque, bookmark one HTTPS diagnostics site you trust and run it before and after TUN. The delta should match your expectation for the proxy group you selected, modulo intentional domestic DIRECT rules.

7. Verify Traffic, DNS, and Logs

Browser-only checks are necessary but insufficient. After TUN succeeds, open Terminal and run a few commands without manually exporting ALL_PROXY; they should ride the tunnel automatically when auto-route behaves. If CLI tools still escape, you either have a residual environment variable forcing direct connectivity or a process-specific bypass—both show up quickly in Mihomo’s live log if you increase verbosity responsibly.

DNS deserves an explicit pass because many profiles combine Fake-IP, redir-host, or multiple upstream resolvers. Mis-aligned dns-hijack entries produce “site loads in Browser A but not Browser B” symptoms that feel like routing bugs. Read the DNS section of your YAML alongside resolver test commands such as dscacheutil -q host -name example.com (interpret results cautiously; caching layers abound). When in doubt, simplify DNS temporarily to isolate whether TUN or resolver policy is the variable.

For developers juggling npm, git, and language mirrors, keep terminal proxy guidance nearby. TUN should reduce manual exports, yet some stacks still honor stale env vars until you unset them.

Tip: Capture a short Mihomo log excerpt the moment you toggle TUN on a clean network. That timeline becomes priceless when a later OS update reorders extensions and you need to diff “last known good.”

8. TUN vs System Proxy on macOS

Use the matrix mentally whenever someone insists “just enable everything simultaneously.”

  • System proxy wins on setup friction: fewer prompts, trivial rollback, ideal for Safari and Chrome pilots.
  • TUN mode wins on coverage: default-route-friendly capture for stubborn binaries, closer to how full-tunnel VPN products feel without abandoning rule semantics.
  • Operational cost tilts toward TUN because macOS will ask for meaningful permissions and occasional reboots; budget that time when onboarding a new machine.

Neither mode replaces thoughtful rules. A perfect tunnel with sloppy DOMAIN lists still sends the wrong domains direct. TUN only enforces the plumbing; Mihomo still decides moral outcomes via YAML policy.

9. Frequently Asked Questions

Why does macOS block Clash Verge Rev TUN until I approve a system extension?

Packet tunneling crosses a trust boundary. Apple requires explicit user consent so random bundles cannot silently redirect traffic. The Allow button in Privacy & Security is the handshake that lets the helper attach.

Do I need to edit YAML to use TUN in Clash Verge Rev?

The UI can flip operational state, but Mihomo still reads YAML. If merges disable tun or neuter auto-route, you will chase ghosts in System Settings that actually live in configuration.

Should I start with system proxy or TUN on macOS?

Start with system proxy to validate your subscription and ports. Promote yourself to TUN once a real app proves it ignores proxies—accepting the extension workflow that comes with it.

Is this guide the same as Windows TUN outage troubleshooting?

No. Windows articles focus on driver installs, Defenders, and service recovery. Here we stay inside Apple’s Network Extension ergonomics and Mihomo YAML—allergic readers can still peek at Windows docs, just do not expect identical menus.

For vocabulary beyond this walk-through, the documentation hub links deeper dives on rule providers, DNS modes, and mixin patching once TUN basics feel boring rather than intimidating.

10. Summary

Turning on TUN mode in Clash Verge Rev on macOS is less about memorizing a single toggle and more about lining up four layers: a healthy Mihomo profile whose YAML tun stanza truly sets enable: true, a GUI switch that survives core reloads, a completed system extension approval under Privacy & Security, and routing evidence from interfaces plus tests that packets follow your intended proxy groups. Skip any step and you will mis-blame Apple—or worse, paste random firewall hacks—from a posture that is actually just an unmerged mixin.

Document your working trio: Verge version, Mihomo build string, and the minimal tun snippet that survived reboots. Future you will thank present you after macOS increments its minor version and politely disables a helper until you reallow it.

Many newcomers still download glossy “one-click VPN” clients that hide routing behind impenetrable blobs. Those apps economize on the first afternoon yet suffocate anyone who needs transparent YAML, streaming-aware split rules, resilient URL-test groups, or DNS plans that cooperate with platform updates. Legacy GUI forks also struggle to track modern cores, which means security fixes and Mihomo features arrive late or never. Within the maintained ecosystem, Clash Verge Rev pairs approachable macOS chrome with the expressiveness of community rule sets—once TUN mode and Apple’s Network Extension consent path are squared away, you keep fine-grained steering without surrendering to opaque tunnels.

Download Clash for free and pair Verge-class control with rule-aware routing on macOS