The first launch on macOS triggers Gatekeeper warnings, Network Extension approval requests, and Keychain access prompts in sequence. This walkthrough follows the actual System Settings screens to explain what to click, why the permission is needed, and how to reset a failed approval.
On Windows, the first run of a Clash-based client usually just needs one SmartScreen prompt dismissed. On macOS, the process runs a bit longer, typically hitting three separate layers of system-level blocking in turn: a Gatekeeper "can't be opened" warning, a system extension or Network Extension approval request, and a Keychain access prompt. Each of these three prompts maps to a different macOS mechanism and needs a different response, so mixing up the steps is an easy way to pick the wrong option and end up with a proxy that's "installed but not actually working."
None of these prompts are bugs in the client itself — they reflect security policies macOS has tightened progressively since Catalina: apps not notarized by Apple need to be manually allowed; anything that takes over the system network stack (i.e. TUN mode) must be approved separately through the System Extension framework; and operations that read or write the system Keychain (such as saving proxy configs or local credentials) require the user to confirm each time. The steps below follow the order the prompts actually appear in.
After downloading and unzipping the installer, double-clicking the app icon will most likely trigger a system message saying it "can't be opened" or is "from an unidentified developer." This is Gatekeeper's default behavior for any app that hasn't gone through Apple's notarization process — it doesn't mean anything is wrong with the installer itself. Here's how to handle it:
If you don't see that message under Privacy & Security, you can also right-click the app icon and choose "Open" from the menu, which brings up the same confirmation dialog with the same effect. This manual override is only needed once, on first launch — after that, double-clicking opens the app normally.
Wording in the Security section of Privacy & Security varies slightly across macOS versions, but the location and function of "Open Anyway" stay the same. Just follow the on-screen prompts — no Terminal commands are needed for this step.
Once the Gatekeeper block is cleared, the app launches fine — but turning on TUN mode (which takes over global network traffic to provide combined app-layer and system-layer proxying) triggers another approval request, this time for a "Network Extension" or "System Extension." This step is the one most often mistaken for the app being stuck, because the prompt doesn't always jump straight to System Settings — sometimes it just sits in the client's own window, waiting for you to switch over manually.
Network Extension approval is tied to Apple's NetworkExtension framework: any feature that creates a virtual network interface or intercepts traffic at the system network stack level has to request permission through this framework. It's a system-level security requirement, not an extra step the client added on purpose. Here's the actual path:
Worth noting: on some Macs, even after approval succeeds, a full system restart is still needed before the extension actually loads. If the toggle is already on but TUN mode still fails to start, try restarting before digging into anything else.
If you don't need TUN mode and are only using system proxy settings (set manually or written automatically by the client), you can skip this Network Extension step entirely — rule-based routing and node switching both work fine without it. TUN mode mainly matters for apps that don't respect system proxy settings, like certain CLI tools or game clients.
After Network Extension approval, some clients trigger a Keychain access prompt while saving configs, writing local credentials, or reading system certificates — the message reads something like "app name wants to use your confidential information stored in your keychain." This prompt has nothing to do with network permissions; it's the macOS Keychain service's standard protection for sensitive local data.
The rule of thumb is simple: if you're sure the prompt was triggered by something you just did in the client (saving a config, enabling launch-at-login, importing a subscription), choose "Always Allow" so it doesn't keep popping up on every launch. If you're not sure what triggered it, pick "Allow Once" first, check that everything still works, and switch to "Always Allow" the next time it appears once you're confident it's safe.
If you accidentally click "Deny" on a Keychain prompt, the usual symptom is a saved config reverting to defaults after restarting the client, or the launch-at-login option refusing to stay checked. If this happens, open the built-in Keychain Access app, search the "login" keychain for the client's name, delete the matching entry, and restart the client — it'll trigger a fresh approval prompt, and this time pick "Always Allow."
In rare cases, the Network Extension approval flow gets stuck: the toggle switches on but nothing happens, or the entry in the Network Extensions list keeps appearing and disappearing. This usually means the system extension's registration state is broken. Try resetting it in this order:
If the problem persists after a restart, it's most likely that the installer is an older build that isn't compatible with your current macOS extension framework. Head to the download page, confirm the right build for your Mac's architecture (Apple Silicon or Intel), and reinstall the latest version. Before installing the new build, fully uninstall the old one first to avoid conflicts between old and new extension registrations.
If all three prompts — Gatekeeper, Network Extension, and Keychain — have been handled correctly but the proxy still doesn't work, the issue usually isn't the approval process at all. It's more likely node connectivity, rule configuration, or the system proxy toggle itself. The troubleshooting approach here is the same as on Windows or Linux: first confirm the proxy toggle in the client is actually on, then test connectivity on individual nodes, and finally check whether the rule mode (global proxy / rule-based routing / direct connection) matches what you expect. Approval prompts only affect whether the client can get system-level permissions — they have nothing to do with whether a given node can actually connect.
Also worth checking: some third-party security software or enterprise MDM profiles on macOS impose extra restrictions on system extensions, which can block Network Extension permission from ever being grantable. If this is a company-issued Mac, it's worth checking with IT about the policy rather than repeatedly reinstalling the client.