macOS Clash Client Permissions Setup: Network Extension Approval & Keychain Authorization Steps
On first launch, macOS pops up a series of system authorization prompts for network extensions, keychain access, and more. This guide explains each prompt, where to approve it correctly, and how to manually fix authorization failures in System Settings.
Why the Clash client triggers multiple prompts in a row on macOS
Since fairly early versions, macOS has tightly sandboxed low-level networking capabilities. Any app that needs to take over system traffic — whether through a virtual TUN interface or the system proxy — must be explicitly approved by the user before it can take effect. When a Clash client (whether built on the original Clash core or the Clash Meta/mihomo core) launches for the first time, the system throws up a sequence of prompts: network extension approval, keychain access authorization, and sometimes local network discovery or input monitoring permissions as well. These prompts are independent of one another — approving one doesn't automatically enable the rest. Missing any one of them can leave a node showing as "connected" while traffic never actually passes through the proxy, or cause the connection to fail outright.
Below is a walkthrough of each prompt in the order it typically appears, along with the manual fix path in System Settings for cases where authorization fails, so you can avoid endlessly reinstalling the client while still having no internet access through it.
Network extension approval: what the prompt says and what to do
When the client switches to TUN mode (also called enhanced mode or virtual interface mode), the system shows a dialog along the lines of "A new network extension has been added," typically stating the extension's source and the scope of permissions requested. This isn't an optional confirmation — it's a one-time authorization gate. If you miss it or accidentally click "Don't Allow," the app can't trigger the same dialog again, and you'll need to fix it manually through System Settings.
-
Check the source before clicking
The prompt shows the name of the extension's signer. Once you confirm it matches the client vendor, click "Allow" or "Open System Settings." If the dialog disappears before you can respond, don't relaunch the client hoping it reappears — go straight to the next step and enable it manually.
-
Go to the Network Extensions list in System Settings
Open System Settings. On newer macOS versions the path is Privacy & Security → Network Extensions (some versions have a separate "VPN & Network" section; naming varies slightly by system version, but it's always under the Privacy & Security category). Find the entry for the Clash client and switch it on.
-
Confirm the toggle took effect, then restart the client connection
Flipping the switch doesn't take effect immediately. Fully quit the client process (not just close the window), reopen it, try enabling TUN mode again, and check whether the node status changes from "Disconnected" to "Running."
Keychain access authorization: which button to pick each time
Once the network extension is approved, macOS usually shows one or more "Keychain" access requests, typically worded something like "The client wants to use a key in your keychain" or "Do you want to allow this?" These prompts let the client read system certificates or local credentials needed for the local verification behind traffic interception — a completely different function from the network extension prompt, and one can't substitute for the other.
- Always Allow: choose this and you won't be asked again on subsequent launches — good for regular, long-term use.
- Allow Once: you'll be asked again every time the client restarts — useful when troubleshooting temporarily or if you're not yet sure you trust the app.
- Deny: click this and the client will keep throwing errors for the rest of the session about failing to read a certificate or key; you'll need to trigger the authorization flow again to recover.
For regular use, "Always Allow" is recommended so you don't have to deal with repeated prompts on every launch. If you accidentally click Deny, there's no need to reinstall the client — just clear the leftover old entry from Keychain and restart the app; the system will present the authorization request again.
If the prompt keeps reappearing even after repeatedly clicking "Always Allow," it's usually caused by a stale credential with the same name sitting in Keychain in a broken state. Manually delete the conflicting entry first, then trigger authorization again — don't just keep dismissing the prompt.
How to manually fix things when authorization fails or the prompt never appears
After a system upgrade or a client update, some users stop seeing the network extension or keychain prompts entirely, yet the connection still keeps failing. This usually means an old authorization state is lingering from a previous record and needs to be manually cleared before re-triggering the flow.
-
Open Keychain Access and check for leftover entries
Use the built-in Keychain Access app to search for entries related to the client's name. If you find multiple duplicate entries or ones marked as invalid, select and delete them, leaving room for the system to regenerate a clean one.
-
Recheck the permission groups in Privacy & Security settings
Network extensions, local network access, and input monitoring live under separate permission groups. Check the toggle state for the client entry in each one — anything showing as off needs to be manually switched on.
-
Fully quit the client and log out/back into the system
Some permission changes only fully take effect on the next login session. If flipping the toggle and immediately retrying doesn't help, log out of your current account, log back in, and then launch the client to verify.
-
Verify the node's connection status and actual traffic path
Once authorization is fixed, don't just trust the "Connected" label in the client UI. Open a browser and visit any page that shows your exit IP, and confirm the exit address actually changes when you switch nodes — that's the real confirmation the whole authorization flow is working.
Details that are easy to confuse between different permission prompts
The most common source of confusion in practice is mixing up network extension approval with the ordinary system proxy setup prompt. If the client only uses system proxy mode (without enabling TUN), macOS generally won't show a network extension request at all — it will just create a proxy configuration entry under Network settings, which doesn't need any extra keychain authorization on its own. Only enabling TUN mode to take over global traffic triggers both the network extension and keychain prompts together. To check which mode is currently active, look at the "Mode" or "Network" toggle labels in the client's settings — anything labeled "TUN" or "virtual interface" indicates enhanced mode.
It's also worth noting that macOS system updates sometimes reset previously granted network extension authorizations. This isn't a bug in the client — it's normal behavior driven by the system's security policy. If the client suddenly can't connect after a major macOS update, redo the network extension approval steps above first, then move on to checking whether the configuration file or subscription link has an issue — don't mistake a system permission problem for a broken node or rule configuration.
Approving network extensions and keychain access are both one-time system-level actions, unrelated to which subscription or proxy rule set you're using. If the connection still fails after completing the authorization flow, check whether the subscription link is valid and the nodes are online first, rather than repeatedly reinstalling the client.
Get the Clash Client
Granting permissions is only the first step — pick the client for your platform and import your subscription correctly to make rule-based routing actually work.