1. What “Clash for macOS” actually means

The name may refer to the original ClashX, ClashX Pro with enhanced mode, the mihomo-based ClashX Meta, the discontinued macOS build of Clash for Windows, or independent community forks. Their cores, menus and configuration fields are not identical.

At the time of verification, the latest MetaCubeX ClashX Meta release is v1.4.46, published on October 1, 2026. Its release README explicitly says the project has no official website. Download only from MetaCubeX/ClashX.Meta Releases rather than a similarly named download site.

The default master branch may contain older code, while releases use the meta branch and version tags. Use a release rather than judging features from the default branch or compiling old code. This guide focuses on ClashX Meta v1.4.46, with legacy ClashX and CFW distinctions only where necessary.

2. System Proxy, TUN, routing modes and DNS are separate layers

  • System Proxy covers only applications that honor macOS proxy settings. Terminals, UDP apps, games, Docker, virtual machines and background services may ignore it.
  • TUN captures more applications, but the result still depends on auto-route, rules, UDP, IPv6, DNS and other VPN or virtual interfaces.
  • Global only handles traffic that reaches the core; it cannot capture applications bypassing Clash.
  • DoH is encryption, not anonymity, and TUN is a capture mechanism, not anonymity. The proxy provider can still see the original public IP.
  • Accounts, cookies, language, time zone, browser fingerprints, macOS Location Services and Wi-Fi-based location can still provide identity or location clues.
Application
   │
   │  1. System Proxy: the app connects to a local Clash proxy port
   │  2. TUN: a utun interface captures network-layer traffic
   ▼
ClashX Meta / mihomo
   │
   │  3. Rule / Global / Direct: chooses the outbound
   │  4. DNS: determines how and through which path names resolve
   ▼
DIRECT / Proxy node / REJECT
   │
   ▼
Destination

3. Installation and beginner quick start

  • Download the release ZIP only from MetaCubeX/ClashX.Meta Releases, extract it and move the app to Applications. Do not globally disable Gatekeeper or casually remove quarantine attributes from an unknown app.
  • Approve the privileged helper on first launch only after verifying the source. It manages system proxy, TUN and DNS settings.
  • The default configuration directory is ~/.config/clash.meta/. Open it through Config → Open config folder and back it up before editing.
  • Add a trusted HTTPS profile under Config → Remote Config → Manage, or place a local YAML file in the configuration directory and select it.
  • Choose Rule mode and a real node, enable Set as system proxy, verify in a browser, and only then decide whether TUN is necessary.
  • Start at login only launches the app. It does not validate the node, profile or DNS state.
  • Set as system proxy writes macOS HTTP/HTTPS/SOCKS settings. Wi-Fi, Ethernet and other services may need separate checks, and another VPN may overwrite them.
  • TUN Mode captures applications that ignore system proxy settings. A checked menu item does not prove healthy routing; verify DNS, Connections and the actual exit.
  • Outbound modes: Rule for normal split routing, Global for controlled tests and Direct for bypassing proxy nodes.
  • Allow LAN lets other devices use the Mac’s proxy ports. Keep it off; local 127.0.0.1 use does not require it, especially on public Wi-Fi.
  • Copy shell command copies HTTP/HTTPS/SOCKS environment variables for compatible shells and child processes. The external-IP variant also involves LAN exposure.
  • Remote profiles and automatic updates may overwrite manual edits. Keep a local copy for long-term customization.
  • Proxy bypass list: localhost, 127.0.0.1, private ranges and *.local usually belong there. Do not add public destinations that should use the proxy.
  • iCloud configuration sync can include subscription URLs, node credentials and rules. Enable it only if those data may sync to other devices.
  • SSID suspend can restore direct connectivity on selected Wi-Fi networks. It is a convenience feature, not a privacy feature, so review the list.
  • Dashboard and Connections show processes, destinations, TCP/UDP, matching rules and chains. Close stale connections after changing nodes.
  • Sniffer recovers domains from HTTP, TLS and QUIC handshakes to assist routing. It is not full TLS decryption or anonymity.
  • Fake IP and caches manage domain mappings. Clear stale entries after DNS or TUN changes; Fake IP is not encryption.
  • GEO and Providers supply GeoIP/GeoSite data, remote nodes and remote rules. Provider sources must be trusted.
  • Remote controller and API: keep them local with a secret, never expose an unauthenticated API, and do not give the secret to an untrusted hosted dashboard.
  • Alpha core is for testing. Ordinary users should not run unverified cores with elevated privileges.

5. Choosing between System Proxy and TUN

  • For ordinary browsing, System Proxy plus Rule mode and an audited bypass list is enough; TUN is not mandatory.
  • For multiple desktop apps, terminals or UDP, use TUN and explicitly verify DNS, IPv6 and UDP behavior.
  • Using System Proxy and TUN together does not create double encryption and may complicate diagnosis.
  • For a controlled single-exit test, temporarily use Global and confirm that GLOBAL selects a real node, then return to the appropriate Rule mode.
  • Close old connections after changing nodes or profiles so old TCP connections cannot keep using the previous exit.
  • Use scutil --proxy to inspect system proxy settings and networksetup -listallnetworkservices to list network services.

6. Why ClashX Meta’s TUN DNS is easy to misunderstand

The current release source uses 8.8.8.8 as the default Meta TUN DNS. The privileged helper applies DNS settings when TUN starts, while mihomo’s dns-hijack redirects matching requests into its internal resolver. Therefore, Meta TUN DNS is not necessarily the final upstream resolver.

The mihomo documentation explicitly states that macOS and Windows cannot automatically hijack DNS requests sent to LAN addresses. Do not casually change Meta TUN DNS to 192.168.1.1 or another router address, because that may bypass the internal resolver.

  • Ensure dns-hijack covers both UDP and TCP port 53.
  • Seeing 8.8.8.8 in scutil --dns proves neither a leak nor a safe configuration. Check internal nameserver settings and actual DNS connections.
  • After TUN stops or crashes, check whether the original DNS settings were restored. If necessary, restore them under Network → Details → DNS.
  • Some upgrades may leave the menu state inconsistent with actual TUN/DNS state. Toggle TUN off and on and perform real tests rather than trusting the checkmark.

7. A current mihomo DNS/TUN example

Merge this fragment into a copy of an existing profile. Do not replace the entire subscription or copy it into legacy ClashX or CFW.

  • respect-rules makes DNS connections follow routing rules. If the resolver’s own address matches DIRECT, its queries can still go direct.
  • proxy-server-nameserver resolves proxy-server hostnames and avoids bootstrap dependency problems. Bootstrap resolution may still require a directly reachable resolver.
  • A nameserver can use #GroupName to select an outbound, such as https://1.1.1.1/dns-query#Proxy, but Proxy must be replaced with a real group name.
  • dns.ipv6: false suppresses AAAA answers; it does not disable macOS IPv6.
  • auto-redirect is primarily for Linux. strict-route is documented mainly in Windows/Linux terms and is not a universal macOS leak-prevention switch.
dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "*.local"
  respect-rules: true
  proxy-server-nameserver:
    - "https://1.1.1.1/dns-query"
  nameserver:
    - "https://1.1.1.1/dns-query"
    - "https://8.8.8.8/dns-query"

tun:
  enable: true
  stack: gvisor
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - "any:53"
    - "tcp://any:53"

8. Browser DoH, IPv6, WebRTC, QUIC and Private Relay

  • Browser-managed DoH can bypass the internal resolver and Fake IP. Only consider disabling it after TUN and DNS hijacking have been verified, then retest.
  • The IPv6 switch is not a global macOS switch. With public IPv6 on the physical network and an IPv4-only tunnel, IPv6 destinations may still see the original address.
  • WebRTC may expose additional addresses through STUN. Chromium’s disable_non_proxied_udp is an option for strict scenarios, but it can impair real-time communication.
  • QUIC uses UDP. Both the node and TUN must have a defined UDP path; do not assume a safe TCP fallback.
  • iCloud Private Relay changes the path for Safari and some unencrypted traffic. When combined with Clash, Safari may show a different exit from other apps, so test one clearly defined path at a time.
  • macOS Location Services can use nearby Wi-Fi networks to determine location. Review per-app permission under System Settings → Privacy & Security → Location Services rather than looking only at the node IP.
  • TUN is not automatically a kill switch. The built-in macOS firewall primarily controls inbound connections and is not a complete outbound fail-closed design.

9. Terminal, Git, curl and SSH setup

Terminal applications do not necessarily read macOS system proxy settings. Set environment variables only in the current shell first, and make them permanent in ~/.zshrc only after confirming stable ports and startup behavior.

  • Git’s HTTP(S) proxy does not automatically configure SSH. Use TUN or ProxyCommand for SSH connections.
  • Homebrew and its download tools commonly honor proxy environment variables, but set and verify them in the same terminal session.
  • The socks5h variant allows the hostname to be resolved through the proxy rather than locally.
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export all_proxy=socks5://127.0.0.1:7890

# curl through the HTTP proxy
curl --proxy http://127.0.0.1:7890 https://example.com/

# SOCKS with remote hostname resolution
curl --proxy socks5h://127.0.0.1:7890 https://example.com/

# Configure and remove Git's HTTP(S) proxy
git config --global http.proxy http://127.0.0.1:7890
git config --global --unset http.proxy

# Clear proxy variables in the current shell
unset http_proxy https_proxy all_proxy
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY

# An SSH ProxyCommand for one specific host
Host example.com
    ProxyCommand nc -X 5 -x 127.0.0.1:7890 %h %p

10. Browsers, IDEs, Docker, virtual machines and games

  • Safari generally follows system proxy settings, but also check Private Relay, DIRECT rules, location permission and Connections.
  • Chrome and Edge require checks for proxy extensions, secure DNS, WebRTC and QUIC. Firefox can use manual SOCKS v5 with remote DNS.
  • An IDE, its plugins, language servers, package managers and integrated terminal may have separate network settings. Success in one component proves nothing about the others.
  • Inside a Docker container, 127.0.0.1 normally refers to the container itself. host.docker.internal can reach the host, but using it with Clash may require Allow LAN, binding and firewall changes. Never expose an unauthenticated proxy on public Wi-Fi.
  • Parallels, VMware and emulators may use NAT, bridging or independent virtual interfaces. Host TUN does not guarantee capture in every topology, so verify routing and DNS inside each environment.
  • Games and real-time voice often require TUN with UDP support, and launchers may be separate processes. ping and traceroute do not reliably prove proxy coverage because ICMP differs from proxied TCP and UDP.

11. Verifying effectiveness and common bypasses

  • Use scutil --proxy to confirm HTTP/HTTPS/SOCKS endpoints and scutil --dns to inspect configured resolvers.
  • In Connections and logs, verify the process, rule, chain and UDP records. A chain ending in DIRECT bypasses the node.
  • Test IPv4 and IPv6 separately using two independent services. An incorrect geolocation city alone does not prove a leak.
  • DNS tests should look for ISP, router or unexpected local resolvers and browser-specific DoH. A public resolver’s IP does not have to match the node IP.
  • For WebRTC, focus on original public IPv4/IPv6. A .local mDNS candidate is not automatically a public-IP leak.
  • Retest after sleep, Wi-Fi changes, node changes, profile updates, ClashX Meta restarts and unexpected TUN shutdowns.
  • If applications regain direct Internet access when Clash stops, the setup is not fail-closed.

12. Troubleshooting and final recommendations

  • Safari works but the terminal does not: use environment variables, application-specific proxy settings or TUN.
  • System Proxy is enabled but the original IP remains visible: check DIRECT rules, bypass entries, IPv6, other VPNs, Private Relay and stale connections.
  • TUN breaks connectivity: check the helper, system DNS, dns-hijack, internal DNS, competing VPNs and the TUN stack. Restore a known-good configuration first.
  • TUN appears enabled but terminal traffic remains direct: verify runtime state rather than only the menu indicator, then toggle and inspect scutil --dns and logs.
  • Fake IP breaks a particular service: add a targeted fake-ip-filter entry instead of disabling the entire DNS module.
  • DNS remains wrong after disabling TUN: check whether the original configuration was restored and repair it through Apple’s Network settings if necessary.
  • Profile updates erase local changes: keep long-term customizations in a local copy rather than editing remotely managed files.
  • For higher-risk privacy needs, use maintained software, verify DNS, WebRTC, Private Relay, location and account identifiers, and use a verified outbound fail-closed design where required.