Clash for macOS: Network Extension and Keychain Permissions After Installation

Start by identifying the four types of approval: opening the app, privileged helpers, Network Extensions, and Keychain access

Clash clients on macOS don't all handle network traffic the same way. A graphical client may use the mihomo core, a privileged helper, or Apple's Network Extension framework. Before following another client's authorization screenshots, check the app name, version, and operating mode to see whether the same steps apply.

First, note your macOS version and chip type from Apple menu → About This Mac. Then check the client version in its About screen; if it has a core information page, note the mihomo version too. Choose the installer for your Apple Silicon or Intel Mac. A mismatched build is usually a launch compatibility issue—not something approving a Network Extension will fix.

Prompt or feature	Permission involved	When to address it
“Cannot verify developer” or “app is damaged”	Gatekeeper, code signing, and download quarantine attributes	Before opening the app for the first time
Install helper tool; administrator authentication required	Privileged helper or service mode	When the client explicitly asks to install a service
Approve system extension or add VPN configuration	System extension, Network Extension, or VPN configuration	When enabling the relevant feature for the first time
Access an item in Keychain	Read access to a specific credential	When the app reads a saved credential

First launch: distinguish developer verification from “app is damaged” warnings

Check the installation location and download source first

Quit any running older copy, then drag the app from the disk image into Applications. Don't keep running it directly from the installer image.
Eject the installer image, then open the app from Applications. This avoids later approvals applying to a copy in a temporary mounted location.
Verify the download source, app name, and processor architecture. If macOS explicitly warns that the app contains malware, don't run it; check the source again.

For warnings such as “Apple cannot verify the developer,” macOS 13 Ventura, macOS 14 Sonoma, and later versions generally show an “Open Anyway” option in the Security section of System Settings → Privacy & Security for the most recent blocked app. In macOS 12 Monterey, go to System Preferences → Security & Privacy → General. The button appears only after a relevant block and when macOS allows an override.

macOS 15 Sequoia changed the opening flow for some unsigned or non-notarized apps. Don't rely on older guides that say to Control-click and choose Open. Follow the current system prompt to Security settings, verify the app, and confirm. Work-managed Macs may block overrides; contact your device administrator.

“App is damaged” is not a routine permissions setting

This warning can indicate damaged app contents, an invalid signature, or an issue involving download quarantine. First delete the current copy and download a release compatible with your macOS version. Don't disable system security checks. To investigate further, type each command prefix below in Terminal, then drag the actual app from Applications into Terminal to complete the path. Run each command separately:

Terminal · Read-only checks

spctl --assess --type execute --verbose=4
codesign --verify --deep --strict --verbose=2
xattr -l

Each command above needs an app path; the three lines aren't complete diagnostics that you can paste and run together. The first checks the system's execution assessment, the second verifies the existing signature, and the third lists extended attributes. Seeing com.apple.quarantine means the app has a quarantine attribute—it doesn't prove the app is harmful or trustworthy. A successful signature check also doesn't mean the app is notarized.

Approve Network Extensions: find the right settings for your macOS version

Trigger a feature that needs the extension from the client, then check for a system prompt. A system extension usually appears for approval only after the app requests activation; copying the app into Applications may not create a pending item. Before approving, verify the developer name and the client's release notes. Don't identify the source based only on when the prompt appeared.

macOS version	Where to look	What to check
12 Monterey	System Preferences → Security & Privacy → General	If macOS says system software was blocked, unlock the settings, verify the developer, and allow it
13 Ventura / 14 Sonoma	System Settings → Privacy & Security	Look for an extension approval prompt in the Security section
15 Sequoia	System Settings → General → Login Items & Extensions → Network Extensions	Open the details, verify the app's Network Extension, and enable it

The exact location also depends on how the extension is packaged and on your macOS point release. If you see an “Add VPN Configurations” prompt, check which app requested it before allowing. You can review VPN configurations in the system's VPN or Network settings. VPN configuration approval and system extension approval are separate settings; a content filter is not the same as a TUN tunnel.

Keep the client open and enable the network feature that needs the extension.
Follow the system prompt to Settings, approve the matching developer or extension, and complete any required authentication.
Return to the client and toggle the feature off and on. Restart your Mac only if macOS explicitly asks you to.
If there's no pending item, check the client logs, extension installation instructions, and service status. Don't keep looking for approval that the app hasn't requested.

Run systemextensionsctl list to see items registered through the system extension mechanism and their status. This isn't a complete list of network components: not every type of Network Extension necessarily appears here, and a TUN setup using a privileged helper can't be judged by whether it has an entry.

Keychain prompts: verify the requesting process, item name, and password type

A Keychain Access prompt usually identifies two things: the process requesting access and the item it wants to read. The item might store subscription credentials, proxy authentication details, or an app access token; its purpose depends on the client. Expand the details and verify them before choosing Allow or Always Allow.

What each option does

Deny: Don't provide credentials for this request. The app may ask you to sign in again, re-enter authentication details, or report that it couldn't read the credentials.
Allow: Approve this access request only. You may be asked again the next time the app tries to read the item.
Always Allow: Save permission for this app identity to access the item. Use this for a verified app that needs ongoing access.

If a prompt asks you to unlock the “login” keychain, it usually needs your current macOS account password—not your subscription password or Apple Account password. If you reset your login password another way, the keychain may still use the old password; repeatedly entering the new one may not unlock it.

If prompts keep appearing, troubleshoot in this order

In Finder, choose Go → Utilities → Keychain Access. You can also open it with Spotlight Search.
Select the “login” keychain and search for the item name shown in the prompt. Don't bulk-delete unrelated passwords.
Open the matching item and check which apps are allowed under Access Control. Some items don't offer the same editing options, so follow what's available in the interface.
Check whether two copies of the app are installed or its signing identity changed after an update. Keep one known installation location, then trigger access again.

Resetting the default keychain affects other saved credentials, so it shouldn't be your first troubleshooting step. Before deleting an item used only by the client, make sure you can re-enter the relevant credentials and note the item's name. Let the client save it again afterward; don't change another app's access controls to bypass a prompt.

TUN permissions: test the system proxy before enabling a virtual interface

The system proxy provides HTTP, HTTPS, and other proxy endpoints to apps that follow macOS proxy settings. TUN takes over traffic through a virtual network interface and routes. Whether command-line tools use the system proxy depends on each tool, so “the browser works but the command line doesn't” doesn't by itself prove a permissions issue.

Turn off TUN first and test the local proxy listener and rules before routing traffic through TUN. The example below uses 127.0.0.1:7890; use the HTTP or mixed port shown in your client instead. Port 7890 is not a default shared by all clients.

Terminal · Check the example port and explicit proxy

lsof -nP -iTCP:7890 -sTCP:LISTEN
scutil --proxy
curl --proxy http://127.0.0.1:7890 --connect-timeout 10 --max-time 20 -I https://example.com/

If lsof shows a listener, check that the process belongs to the client you're using. If there's no output, check whether the core started and confirm the actual port.
scutil --proxy: Show the system proxy settings currently in effect. This doesn't confirm that TUN routes are in place.
If curl returns response headers, the explicit proxy request received a response. Check the status code and the client's connection log to determine whether the request succeeded.

Verify the service and runtime configuration

If the client uses a mihomo privileged helper, use the service installation option in its settings and authenticate as an administrator before enabling TUN. The menu may be called “Service Mode,” “Helper Service,” or “Install Service,” depending on the version. Don't run the entire graphical app as an administrator.

mihomo runtime fields · merge as needed

tun:
  enable: true
  stack: system
  auto-route: true
  auto-detect-interface: true

These are TUN-related fields, not a complete, standalone configuration. Check the current core version for supported stack values and behavior; these fields don't replace system permissions. A client may override matching subscription fields at startup, so inspect the effective configuration rather than only the downloaded YAML file.

After enabling TUN, use ifconfig to inspect interfaces, netstat -rn -f inet for IPv4 routes, and scutil --dns for resolver status. macOS and other VPNs also create utun interfaces, so seeing utun0 or another numbered interface doesn't prove it belongs to this client. Compare the changes before and after enabling TUN, along with the client logs and actual connection records.

Permissions are approved but traffic still fails: narrow down the cause

What you see	Check first	Next step
The app opens, but no local port is listening	Core startup logs, configuration parsing errors, port conflicts	Fix startup errors, then reload the configuration
Explicit proxy works, but the browser bypasses it	System proxy status and the browser's own proxy settings	Check the current network service and browser extension settings
System proxy works, but TUN won't start	Privileged service, extension status, interface, or routing errors	Follow the permissions required by the client's actual implementation
Domains fail after enabling TUN	DNS configuration and resolver logs; DNS settings from other VPNs	Disable other traffic interception components and test one at a time
Keychain keeps prompting after an update	App copies, signing identity, and item access controls	Verify the requester, then grant access to the relevant item again

Successfully importing a subscription only means the client received the configuration. It doesn't confirm node authentication, DNS, proxy group selection, or system routing. During testing, check which rule matches the destination domain and which outbound is used in the connection view. If it matches DIRECT, check the rule order before approving more system extensions.

To troubleshoot conflicts, pause other VPNs, content filters, or packet capture tools, then test the current client on its own. Change one thing at a time and note the log timestamps before and after. Don't reinstall the app, delete Keychain items, and change DNS all at once; even if connectivity returns, you won't know which change fixed it.

Upgrade and uninstall: check service status and preserve recoverable network settings

Before upgrading: Note the client version, core version, and current operating mode. Save any local rules you want to keep so an overwrite doesn't erase your changes.
After upgrading: Open the app first, then check whether its service needs an update. Review and approve again only if a new authorization prompt appears.
Before uninstalling: Turn off TUN and the system proxy in the client. Use its built-in option to uninstall the helper service or disable the extension, then quit the app.
After uninstalling: In macOS 13 and later, check for leftover settings at System Settings → Network → current network service → Details → Proxies. In macOS 12, go to System Preferences → Network → current service → Advanced → Proxies.

Don't remove configurations for other VPNs, and don't clear every setting just because you see 127.0.0.1. First confirm that the uninstalled client set that address and port; your work network may have a proxy configured by its administrator. If your Mac is managed, ask the administrator to verify the settings.

After troubleshooting, you should be able to answer four separate questions: Does the app start normally? Does its current mode need an extension? Is the Keychain request from a verified app? Are proxy or TUN connections matching the expected rules? Checking each one is more useful than repeatedly entering passwords or restarting your Mac.