How to Configure and Troubleshoot TUN Mode in Clash Verge Rev

Enable TUN mode by toggling the system switch in Clash Verge Rev, ensure Service Mode is active, then configure the virtual NIC parameters through the TUN Settings dialog to capture all system traffic.

Clash Verge Rev implements TUN mode (virtual network interface) through a combination of the Clash core's tun configuration section and a UI-level flag called enable_tun_mode. When active, this mode intercepts all traffic at the network layer, bypassing system proxy settings that some applications ignore. This guide covers how to properly configure and troubleshoot TUN mode using the actual source implementation from the clash-verge-rev/clash-verge-rev repository.

Understanding TUN Mode Architecture

The TUN implementation spans three distinct layers in the codebase:

• State Layer: Stores the enable_tun_mode boolean and the detailed tun configuration object (including stack, device, auto-route, etc.) in the IConfigData interface defined in src/types/global.d.ts.
• Backend API: Handles runtime configuration updates through the useClash hook (src/hooks/use-clash.ts), exposing patchClash and patchVerge functions to modify settings.
• Frontend UI: Provides the toggle switch in src/components/shared/proxy-control-switches.tsx and the detailed configuration dialog in src/components/setting/mods/tun-viewer.tsx.

Critical Requirement: TUN mode requires Service Mode (Clash running as a background service) or Administrator privileges on Windows and macOS. On Linux, the auto-redirect option is only available when auto-route is enabled.

Enabling TUN Mode in the UI

Follow these steps to activate TUN mode through the interface:

1. Verify Service Mode: Check the system tray icon to confirm the Clash service is running. Without this, TUN mode will automatically disable itself.

2. Toggle the Switch: Navigate to the home page or system settings and enable the TUN mode switch. This component is implemented in src/components/shared/proxy-control-switches.tsx (lines 125-190) and calls patchVerge({ enable_tun_mode: true }).

3. Confirm Activation: Once enabled, the ProxyTunCard component (src/components/home/proxy-tun-card.tsx, lines 148-209) displays a TUN indicator on the home page and activates the "TUN Settings" button for detailed configuration.

Configuring TUN Parameters

Click TUN Settings to open the TunViewer dialog (src/components/setting/mods/tun-viewer.tsx), which exposes all Clash core TUN options.

Core TUN Settings

UI Field	Config Property	Default Value	Description
Stack	stack	"gvisor"	Packet processing stack (gvisor, mixed, etc.). Controlled by StackModeSwitch.
Device	device	"utun1024" (macOS) / "Mihomo" (others)	Virtual NIC name.
Auto-Route	"auto-route"	true	Automatically routes all IPs through the TUN device.
Auto-Detect Interface	"auto-detect-interface"	true	Detects correct outbound interface per packet.
DNS Hijack	"dns-hijack"	["any:53"]	DNS queries to capture via TUN.
Strict-Route	"strict-route"	false	Disables fallback routes, forcing all traffic through TUN.
MTU	mtu	1500	Maximum Transmission Unit (≥1280 required on macOS).
Route-Exclude-Address	"route-exclude-address"	[]	CIDR list to bypass TUN (comma/newline separated).

Platform-Specific Options

• Auto-Redirect ("auto-redirect"): Only visible on Linux (src/utils/get-system.ts detection). When enabled alongside auto-route, it redirects traffic that would otherwise use the system proxy. Default is false.

When you click Save, TunViewer constructs the payload (lines 80-104) and calls patchClash({ tun }) to apply changes immediately. The Reset button (lines 31-66) restores the default configuration shown in the table above.

Troubleshooting Common TUN Issues

Symptom	Likely Cause	Diagnostic Steps	Fix
TUN mode automatically disables	Service mode not running or insufficient privileges.	Check system tray for Service status. Review logs for autoDisabled messages.	Install/start the Clash service or run with Administrator rights.
auto-redirect checkbox missing	Running on Windows or macOS.	Verify OS value in get-system.ts.	No action needed; this feature is Linux-only.
Changes not applied after Save	patchClash request failed or core rejected config.	Inspect Network tab for /patch request errors. Check clash.log for validation errors.	Ensure MTU ≥ 1280 on macOS. Use Reset to restore valid defaults.
Traffic still uses system proxy	auto-route disabled or strict-route false with route exclusions.	Open TUN Settings, verify Auto-Route is enabled.	Enable Auto-Route or adjust Route-Exclude-Address to not capture the traffic.
"tun device not found" error	Incorrect device name for platform.	Check TUN Settings device field. Run ifconfig (macOS) or ip link (Linux).	Use utun1024 on macOS, Mihomo on Windows/Linux, or leave empty for auto-selection.
High latency or packet loss	MTU mismatch with underlying network.	Test with ping -s <size> <host> to find optimal packet size.	Reduce MTU value (e.g., to 1400) in TUN Settings and save.

Programmatic TUN Configuration

You can manipulate TUN settings programmatically using the React hooks exposed by the application.

Enabling TUN Mode via Hooks

import { useClash } from "@/hooks/use-clash";
import { useVerge } from "@/hooks/use-verge";
import { getSystem } from "@/utils/get-system";

async function enableTunMode() {
  const { patchVerge } = useVerge();
  const { patchClash, mutateClash } = useClash();
  const OS = getSystem();

  // Activate the global TUN flag
  await patchVerge({ enable_tun_mode: true });

  // Configure the TUN interface
  const tunConfig = {
    stack: "gvisor",
    device: OS === "macos" ? "utun1024" : "Mihomo",
    "auto-route": true,
    "auto-detect-interface": true,
    "dns-hijack": ["any:53"],
    "strict-route": false,
    mtu: 1500,
    "route-exclude-address": [],
    ...(OS === "linux" ? { "auto-redirect": false } : {}),
  };

  await patchClash({ tun: tunConfig });
  
  // Update local cache without refetching
  mutateClash(old => ({ ...old!, tun: tunConfig }), false);
}

This implementation mirrors the logic in proxy-control-switches.tsx (lines 138-140) and tun-viewer.tsx (lines 84-104).

Resetting to Default Configuration

import { patchClash, mutateClash } from "@/hooks/use-clash";
import { getSystem } from "@/utils/get-system";

async function resetTunToDefaults() {
  const OS = getSystem();
  
  const defaultTun = {
    stack: "gvisor",
    device: OS === "macos" ? "utun1024" : "Mihomo",
    "auto-route": true,
    "auto-detect-interface": true,
    "dns-hijack": ["any:53"],
    "strict-route": false,
    mtu: 1500,
    "route-exclude-address": [],
    ...(OS === "linux" ? { "auto-redirect": false } : {}),
  };

  await patchClash({ tun: defaultTun });
  mutateClash(old => ({ ...old!, tun: defaultTun }), false);
}

This matches the Reset button behavior in tun-viewer.tsx (lines 31-66).

Summary

• TUN mode in Clash Verge Rev creates a virtual network interface that captures all system traffic, bypassing applications that ignore system proxy settings.
• Enable the feature via the system toggle in proxy-control-switches.tsx, which sets enable_tun_mode: true through patchVerge.
• Configure detailed parameters through the TunViewer dialog (tun-viewer.tsx), including stack mode (gvisor), device names (utun1024 on macOS, Mihomo on others), and routing options (auto-route, strict-route).
• Require Service Mode or Administrator privileges; without these, TUN mode automatically disables itself.
• Troubleshoot common issues by checking Service status, verifying MTU values (≥1280 on macOS), and ensuring auto-route is enabled for traffic capture.

Frequently Asked Questions

Why does TUN mode automatically turn off after I enable it?

TUN mode requires elevated privileges to create and manage virtual network interfaces. If the Clash service is not running or the application lacks Administrator rights on Windows/macOS, the backend automatically disables the flag and logs an autoDisabled message. Verify the system tray shows "Service" status, or restart the application with elevated permissions.

What is the difference between Auto-Route and Strict-Route?

Auto-Route ("auto-route": true) automatically adds routing table entries to direct all IP traffic through the TUN device. Strict-Route ("strict-route": true) removes the fallback route, ensuring that all traffic must pass through the TUN stack with no bypass. Enable Strict-Route only when you need to force every packet through the proxy, but be aware that misconfiguration can cause complete network loss.

Why is the Auto-Redirect option missing on my system?

The Auto-Redirect ("auto-redirect") setting only appears on Linux systems. According to the OS detection logic in src/utils/get-system.ts, this checkbox is conditionally rendered in tun-viewer.tsx (lines 25-48) only when OS === "linux". This feature redirects traffic that would otherwise use the system proxy, and has no effect on Windows or macOS.

How do I exclude specific subnets from TUN routing?

Use the Route-Exclude-Address field in the TUN Settings dialog. This maps to the "route-exclude-address" array in the configuration. Enter CIDR ranges separated by commas or newlines (e.g., 10.0.0.0/8, 192.168.1.0/24). The UI uses BaseSplitChipEditor to parse these entries, and the backend adds these routes to bypass the TUN interface, allowing direct access to local corporate or home networks.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}