1. Symptoms and Mental Model
The frustrating pattern is familiar: Clash Verge shows connected, the dashboard lists healthy nodes, and you toggled system proxy—but a speed-test site still reports your residential ISP, or a command-line tool prints a domestic IP. Sometimes only Chromium-based browsers misbehave while Firefox follows the proxy, or the opposite. That scatter does not mean your subscription is fake; it means different subsystems on macOS read proxy settings from different places, and not every application honors the global web proxy fields.
Apple’s networking stack separates “what the OS stores in System Settings” from “what a specific app decides to do.” Games, bespoke SDKs, and electron apps may ignore system proxy entirely. Conversely, Safari and curl usually respect the HTTP and HTTPS proxy entries when they are actually written. Your first job is therefore to verify whether macOS truly contains the host and port you expect, not only whether the client UI claims it applied them.
This guide stays client-focused: it maps the knobs Clash Verge exposes to the checks Apple expects, without drifting into abstract TUN theory—if you want a deep dive on transparent interception, treat that as complementary reading. For everyday “browser still direct” cases, permissions and extension approval beat YAML trivia most of the time. If you need a refresher on how profiles hang together, start with our configuration overview; for picking a desktop client on Windows versus macOS trade-offs, see the Verge versus Clash for Windows comparison.
2. What “System Proxy” Means on macOS
When a Clash-family app toggles system proxy, it typically asks macOS to populate the Web Proxy and Secure Web Proxy fields for the active network service (Wi‑Fi or Ethernet) with something like 127.0.0.1 and your mixed or HTTP port—often 7890 by convention. SOCKS, if exposed separately, may map to another port. The crucial detail is that these values live in the network service configuration that System Settings → Network shows when you inspect details for the interface.
Open System Settings → Network, select the interface you actually use, click Details…, and review the Proxies tab. If the fields are empty while Clash insists it enabled system proxy, the write failed silently—usually because the helper lacked permission, the app quit before committing, or another tool overwrote the profile seconds later. If the fields look correct yet traffic still leaks, scroll down: SOCKS might be off while HTTP is on, or a per-service override exists for a VPN interface you forgot about.
Command-line users can cross-check with scutil --proxy in Terminal; the output lists what the system resolver stack currently advertises for web traffic. Compare that dictionary to the port shown in Clash Verge’s connection panel. A mismatch of even one digit sends browsers to the wrong listener, which often responds with a fast failure or unexpected direct routing depending on fallback rules.
Per-browser overrides
Chrome and Edge can carry their own proxy policies pushed by profiles; Safari generally follows system settings unless a content-filter extension interferes. Before you blame macOS, disable experimental proxy extensions and test in a clean Safari window or a minimal curl through 127.0.0.1:PORT to isolate the OS path from browser policy.
3. Clash Verge: Ports, Mode, and YAML Alignment
Clash Verge sits on top of a modern Mihomo-class core. The GUI exposes high-level switches, but the effective behavior still comes from the merged YAML: mixed-port, discrete port and socks-port, mode (rule, global, direct), and DNS settings. If system proxy points to port 7890 while your running config listens on 7897 because an imported profile changed defaults, every symptom matches “proxy broken” even though the process is healthy.
After you import a subscription, open the live config view and confirm which listener is active. Align the GUI’s system-proxy port field—if editable—with that listener. Mixing HTTP-only and mixed listeners is fine when you know which one macOS references; mixing them accidentally is not. When in doubt, standardize on a single mixed port and point both Web Proxy and SOCKS to it if the OS asks for both.
Rule mode deserves a mention: if your rules send the target domain to DIRECT, the browser will appear “unproxied” relative to your expectation even though the local path works. Tail logs while loading a test URL; if you see DIRECT for that host, adjust rules rather than macOS settings. This article assumes routing decisions are sane and focuses on cases where traffic never reaches the core at all.
4. Network Extension and System Settings
Modern macOS routes advanced packet capture and tunneling through Network Extensions. When you enable TUN or a system-level packet filter inside Clash Verge, Apple may prompt you to approve an extension signed by the developer bundle. If you dismiss the prompt—or if MDM policies block user approvals—the tunnel never attaches, and applications that rely on kernel-level redirection keep behaving as if no VPN exists.
Visit System Settings → Privacy & Security and scroll to the section that lists network-related extensions (wording shifts slightly between macOS versions). Ensure the Clash Verge extension is allowed. If you previously clicked “Don’t Allow,” remove and reinstall the app or toggle the extension off and on after a reboot; macOS caches refusal decisions aggressively.
Some builds expose both a lightweight system proxy helper and a heavier TUN extension. They are not interchangeable: you can have proxy writes succeed while the extension for TUN remains blocked, producing a confusing mix where browsers work partially and UDP-heavy apps fail. Document which feature you enabled when testing; screenshots of Settings panels save time when you revisit the machine weeks later.
Filters and DNS profiles
Apple’s Network page also lists content filters and DNS profiles when installed. A DNS-only profile can steer names away from your Clash DNS pipeline, making it look like “proxy down” when the issue is name resolution. Temporarily disable third-party DNS or filter payloads, then retest.
5. Login Items and Background Execution
macOS aggressively manages background tasks to preserve battery. If Clash Verge is not registered as a login item—or if the helper that applies system proxy is not allowed to launch at startup—the OS may clear proxy fields after sleep, reboot, or user switch. The visible symptom is “worked yesterday, blank today,” which users often misattribute to node quality.
Open System Settings → General → Login Items & Extensions (path may read slightly differently on older releases). Under Login Items, confirm Clash Verge appears and is enabled. Under Allow in the Background, ensure related helpers are not denied. If macOS removed background privileges after an update, re-enable them explicitly; silent denials are common after major OS upgrades.
Test sleep cycles: connect, verify scutil --proxy, close the lid, wake, and re-run the command. If proxy entries vanish, you have a lifecycle bug, not a routing bug. Fixing it through login items and background permissions is more reliable than hammering YAML.
6. Accessibility and Automation Prompts
Some graphical clients automate toggles or inject settings through AppleEvents. macOS will prompt for Accessibility or Automation access when a helper tries to script System Settings or another app. If you deny these prompts, features that “should” flip proxies silently fail while the main window still looks operational.
Check System Settings → Privacy & Security → Accessibility and ensure the Clash Verge components you recognize are listed and checked. Do the same for Automation if the OS shows entries there. Remove stale duplicates after reinstalls—macOS sometimes keeps revoked binaries in the list until you delete them manually.
This is distinct from Full Disk Access, which is rarely needed for proxy injection but may appear in support docs for crash diagnostics. Grant the minimum scope that matches your build’s release notes; over-sharing permissions is a security risk on portable machines.
7. VPNs, Filters, and Third-Party Firewalls
Another VPN or tunnel product—WireGuard, corporate GlobalProtect, consumer “security” suites—may install a kernel extension or user-space tunnel that sets itself as the default route. When that happens, system proxy entries can remain filled while packets bypass your Clash listener because the competing VPN captures interfaces first. The fix is procedural: quit or disable the other VPN, then restart Clash Verge and reapply proxy.
Host-based firewalls such as Little Snitch or Lulu can block localhost forwarding if rules treat loopback connections suspiciously after an update. Review temporary prompts you might have dismissed. Similarly, iCloud Private Relay intercepts DNS and parts of HTTP traffic for Safari; combine it with a local proxy only after you understand precedence—often the pragmatic choice is disabling Relay while testing.
Browser extensions that ship their own VPNs deserve suspicion: they can inject conflicting PAC scripts. Uninstall or disable them during triage. Once baseline behavior returns, reintroduce extensions one at a time.
8. When to Prefer TUN Over System Proxy
System proxy is elegant for browsers and CLI tools that respect OS settings, but it does not cover binaries that open raw sockets or ignore env vars. TUN mode elevates interception to the stack where fewer apps escape—at the cost of requiring network extension approval and occasionally higher battery use.
If you followed every step above, confirmed scutil --proxy, cleared conflicts, and still see stubborn apps phoning home directly, switch your experiment to TUN with a minimal profile. Watch for MDM or SIP-related blocks; school and employer machines may forbid custom tunnels entirely. Document that outcome so you do not loop on YAML tweaks that can never succeed on locked hardware.
Conversely, if corporate policy only allows HTTP proxies on port 3128, forcing TUN might violate rules even when it technically works. Match the strategy to environment constraints, not only to personal preference.
9. Troubleshooting Checklist
Use this ordered list when searches combine Clash Verge, macOS, and “proxy not working” keywords. It is designed to spend minutes, not hours, before you escalate to maintainers.
- Verify listeners. Confirm the mixed or HTTP port in Clash matches System Settings → Network → Proxies and
scutil --proxy. - Re-toggle system proxy. Turn the feature off and on inside Clash Verge; watch for macOS prompts you previously dismissed.
- Approve extensions. In Privacy & Security, allow the network extension tied to your build if you use TUN or enhanced modes.
- Fix login items. Enable startup and background helpers so settings survive sleep and reboot.
- Clear competing VPNs. Quit other tunnel apps; reboot clean if multiple drivers fought.
- Review Accessibility/Automation. Grant only what your version’s documentation requests.
- Read logs. If nothing hits the core, OS integration failed; if DIRECT appears, rules did.
| Symptom | Likely cause | First action |
|---|---|---|
| Proxy fields empty after reboot | Login item / background helper missing | Re-enable in Login Items & Extensions |
| TUN never activates | Network extension denied or MDM block | Privacy & Security → allow extension |
Browser direct, curl via -x works |
Browser policy or extension | Reset browser proxy flags; test Safari |
| Intermittent after sleep | Race with other VPN or power nap | Disable other tunnels; retry wake cycle |
When you open an issue with developers, attach redacted scutil --proxy output, core version, and whether the problem survives a new macOS user account—hardware profile issues surface quickly that way.
10. Summary
Clash Verge on macOS is not harder than other platforms; it is more explicit about consent. System proxy failures usually trace to incomplete OS writes, missing network extension approval, or lifecycle issues around login items—not mysterious packet loss. Work top-down: confirm Settings, then permissions, then conflicts, then YAML. Compared with opaque one-button VPNs, that transparency is an advantage—you can photograph the exact state Apple sees and share it with support.
Compared with other rule-based stacks, Clash rewards users who treat the OS as part of the configuration surface. Keep notes when Apple revamps Settings labels; screenshot your working panels. When you upgrade macOS yearly, replay this checklist before assuming your subscription degraded overnight.
When you install or refresh the client, use the official site’s download page so binaries match published artifacts—then apply proxies on a clean baseline you can reproduce.
