On this page
After the menu bar icon appears, confirm that the core is stable
On macOS, Clash clients commonly remain in the menu bar and continue running after the main window closes. Before first-time setup, open settings or logs and verify stable core status with no repeated core failed or permission denied messages.
Quit the old ClashX instance, other Mihomo clients, and VPN software so several programs do not modify the system proxy together.
This guide uses the common labels Profiles, Proxies, System Proxy, and TUN. Chinese labels may vary slightly among clients, but the sequence does not: first update the configuration, then complete a request through a node, and only afterward add system-level traffic-capture permissions.
After a subscription update succeeds, set it as the current configuration
Import a remote configuration on macOS
Open Profiles / Configurations
Paste the Clash- or Mihomo-compatible HTTPS link supplied by the provider.
Update manually
Wait for a new update time and watch for 401, 403, timeout, or parse error.
Select the Profile
Ensure that the current marker is not on an old configuration or sample file.
Open Proxies
Confirm that policy groups and nodes are not empty.
macOS network permissions cannot repair subscription errors. For update responses of 401/403, address the token or account. For YAML parsing errors, verify the core and format. The system proxy and TUN have something to run only after the Profile loads.
If the menu bar says running but has no traffic, verify System Proxy first
A lit menu bar icon means only that the client is running, not that the browser uses it. Pin one node in the primary group under Proxies and keep the mode on Rule. When you enable System Proxy, macOS may ask permission for the app to change network proxies. Confirm that the prompt comes from the current client, then enter system credentials or use Touch ID.
Open a familiar site in Safari or Chrome and find the domain in Connections. If the record shows its rule and outbound route, the configuration, node, and system proxy all work. Only when the browser works but the terminal has no record should you conclude that the latter may ignore the system proxy.
Evidence that the system proxy works
- macOS network settings shows the current client's local proxy port
- The browser request enters Connections
- Rule and the final outbound route match expectations
- After disabling System Proxy, the same request no longer passes through Clash
Only missed apps need TUN and additional permissions
TUN creates a virtual network interface and sends more TCP and UDP connections to Mihomo. If a terminal tool, game launcher, or software that ignores the system proxy has no Connections record, compare with TUN. A request that already enters Clash but matches the wrong rule does not need broader capture.
When enabling TUN, macOS may ask you to install or allow a network extension, helper service, or VPN configuration. System settings names the specific item; its developer and app should match the current client.
If the toggle immediately switches back or the log says permission denied, open the VPN, Filters, or Network Extensions page in system settings and grant permission. Return to the client, enable it again, and wait for the virtual interface.
Permission prompt and purpose
| macOS prompt | What it enables |
|---|---|
| Modify the system proxy | Allows apps that honor the system proxy to connect to the local port |
| Network extension / VPN configuration | Creates or runs the TUN capture path |
| Administrator privileges / helper service | Performs networking operations that require system privileges |
| Local network access | Discovers or connects to local-network devices; whether it is needed depends on the scenario |
Return to the app that was missed and see whether it appears in Connections
Compare only one action before and after TUN
Reproduce with TUN disabled
Confirm that the program has no connection record under the system proxy.
Enable TUN
Keep the same Profile, Rule mode, and fixed node.
Repeat the exact same action
For example, run the same terminal command or open the same launcher page.
Inspect the new connection
Record the process, domain, matched rule, and outbound route.
If a record appears and succeeds after enabling it, TUN supplied the missing traffic entry. If it appears but shows DIRECT, address the rule. If it uses a node and then shows timeout, compare the node and network. If no record appears, inspect network-extension status, the firewall, and other VPN software instead of changing the subscription again.
If connectivity fails after closing and reopening the lid, have the core detect the current outbound interface again
After a Mac wakes from sleep or switches from corporate Wi-Fi to a mobile hotspot, the real outbound adapter has changed while the TUN virtual interface may retain old state. Wait a few seconds and repeat the same request first. If Connections has no new record, reload the core or disable and reenable TUN; this is usually more direct than restarting the computer.
Under the system proxy, also check for stale proxy values. If the client interface is closed but macOS network settings still points to a port on 127.0.0.1, all pages fail. Clear the stale values or restart the current client.
Connections is empty after wake
Reload the core so the client detects Wi-Fi and the default outbound route again.
Only TUN fails after changing networks
Recreate the TUN interface and inspect whether another VPN took over the route.
The browser loses all connectivity after the client exits
Check whether the macOS HTTP, HTTPS, and SOCKS proxies still point to the old port.
If TUN works but the NAS disappears, preserve a direct path for local addresses
If a printer, NAS device, router admin page, or corporate internal domain becomes unreachable with TUN enabled, the likely issue is private addresses entering the proxy path, not the node. If local devices return immediately after disabling TUN, narrow the scope to local-network rules, internal DNS, or routing.
Check whether the IP matches DIRECT in Connections. Common home private ranges usually already have rules, while corporate custom ranges and split DNS must be added based on real settings. Do not copy a “global bypass list” containing unfamiliar ranges; handle only addresses you can verify.
- The IP opens, but the internal domain does not
- Internal DNS likely did not resolve through the original network.
- Both the IP and domain enter the proxy group
- Place the exact local subnet or domain rule before broader rules.
- It remains unreachable with every proxy disabled
- The issue is outside Clash; inspect the current Wi-Fi network and device.
Use one restart and one sleep/wake cycle to confirm that permissions persist
After configuring the subscription, System Proxy, and TUN permissions, restart the client once, then let the Mac sleep and wake. If the Profile remains current, browser requests enter Connections, and the program that required TUN continues producing records, permissions and background services were not temporary to this session.
If the system proxy works but TUN is denied again after restart, return to network-extension permissions. If no request appears after sleep, reload the core and inspect the menu bar process. Healthy behavior is straightforward: the subscription updates, the browser has records through the system proxy, programs that require TUN also appear, and macOS does not request the same permission on every launch.