How to Install Clash on macOS: Network Extension Permissions and Keychain Prompts

Understand the three permission types first: system proxy, helper services, and network extensions

“Set as System Proxy,” “Install Service Mode,” and “Enable TUN” in a macOS client are separate controls. They use different system capabilities and trigger different prompts. Treating them as one often leads to approving a network extension without being able to change the proxy, or installing a TUN service even though the system proxy is already working.

Using common examples such as Clash Verge Rev 2.x, ClashX.Meta 1.4.x, and macOS clients built on the mihomo core, labels may appear as “System Proxy,” “Service Mode,” “Clash Core,” “TUN Mode,” or “Enhanced Mode.” Implementations vary. Enable only what you need during setup; there is no need to approve every feature at once.

The correct first-launch order

Step 1: Move the app to Applications

When the download finishes, open the DMG, drag the client to Applications, and launch it from Finder’s Applications folder. Do not run it long-term from the DMG, Downloads, or a temporary extracted folder. A changing app path can affect login items, helper services, and Keychain access controls; repeated prompts after an upgrade are often linked to path or code-signing changes.

1. Open the downloaded DMG or archive in Finder.
2. Drag the app into Applications.
3. Eject the installer image and close any older copy still running.
4. Open the client from Applications.
5. Confirm that only one client instance appears in the menu bar or Dock.

If macOS says the app was downloaded from the internet, verify the file source and app name, then choose “Open.” If macOS blocks it outright, open System Settings → Privacy & Security, find the recently blocked app in the Security section, and choose “Open Anyway.” On macOS 12 Monterey, the path is System Preferences → Security & Privacy → General.

Step 2: Import a profile and confirm local ports

On the client’s “Profiles” page, import your subscription, wait for it to finish parsing, and select a node in a policy group. A common mixed port in mihomo configurations is 7890; the SOCKS port may be 7891, and the external controller port is often 9090. These are common defaults only—use the values shown in the current configuration and client settings.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

If another proxy tool is already listening on 7890, the Clash core will usually fail to start or keep restarting. Quit other proxy apps, then check which process owns the port in Terminal:

lsof -nP -iTCP:7890 -sTCP:LISTEN
lsof -nP -iTCP:9090 -sTCP:LISTEN

Step 3: Enable the system proxy first

Turn on the “System Proxy” switch in the client. Some clients request a helper service the first time and show an administrator authentication window. Enter the password for the current Mac administrator account, not the Apple ID password. The password field usually shows no character count; this is normal macOS permission behavior.

After enabling it, use Terminal to check the proxy status for the current network service. The wireless service is usually named Wi-Fi, though older systems or custom setups may use a different name:

networksetup -getwebproxy Wi-Fi
networksetup -getsecurewebproxy Wi-Fi
scutil --proxy

If the output shows Enabled: Yes, the server address is 127.0.0.1, and the port matches the client, the system proxy has been applied. If the browser still cannot connect, check the node, rules, and DNS first instead of repeatedly reinstalling the network extension.

Network extension approval paths on macOS 12 through macOS 15

TUN mode may use Network Extension, Packet Tunnel Provider, a system extension, or a privileged helper process. The prompt varies by client, installation method, and macOS version. Open the relevant settings page only when enabling TUN, Enhanced Mode, or a network service triggers a system notification.

macOS 15 Sequoia

macOS 15 moved extension management into “Login Items & Extensions.” After seeing “System Extension Blocked” or a network extension request, open System Settings → General → Login Items & Extensions and check Network Extensions near the bottom. Find the item matching the current client’s developer or app name, turn it on, and authenticate when prompted.

If an “Add VPN Configuration” dialog appears, verify that the request came from the Clash client you just operated, then choose “Allow.” Return to the client and turn TUN off and on again. Some versions require a complete quit and relaunch before macOS reloads the Packet Tunnel Provider.

macOS 13 Ventura and macOS 14 Sonoma

On Ventura 13.7 and Sonoma 14.7, blocked system software usually appears near the bottom of System Settings → Privacy & Security. Click “Allow,” enter the administrator password, and reopen the client or restart the Mac as instructed. If there is no button, do not keep clicking “Install” in the client. Quit the app, trigger the TUN or service-install request once more, and immediately check Privacy & Security.

Check VPN configurations in System Settings → VPN. If several failed configurations from the same client remain, turn off TUN, remove duplicates clearly belonging to an older version, and let the current version create a fresh one. VPN entries on company-managed devices may be deployed by mobile device management and should not be deleted without approval.

macOS 12 Monterey

Monterey 12.7 uses the older System Preferences interface. Open Security & Privacy → General, click the lock in the lower-left corner, authenticate, and approve the blocked system software. Check network services and VPN status in System Preferences → Network. If macOS asks you to restart after approval, save your work and restart normally; do not force-quit the System Preferences process.

Should you choose “Allow” or “Always Allow” in a Keychain prompt?

A Keychain prompt identifies the requesting app and item by name. A Clash client may use Keychain to store subscription credentials, controller keys, service tokens, or secure-storage items. Before responding, verify that the app name at the top matches the client you just launched and that the prompt appeared while importing a subscription, installing a service, or launching after an upgrade.

If the client starts at login and reads the same service key every time, “Always Allow” prevents a prompt from blocking background startup. You still need the password for the current macOS login account. Touch ID availability depends on the macOS version, Keychain item, and authentication policy; when the prompt requests a password, use the local account password.

If you choose only “Allow,” being asked again after the next app restart is expected. If “Always Allow” still produces a prompt every time, check whether the app is running from a DMG, whether an upgrade changed its distribution channel, and whether two clients with the same name remain installed. Keychain access control recognizes the app’s signature; identical names do not mean identical authorized identities.

How to reset a failed network extension approval

Start with a minimal retry

1. Turn off TUN, the system proxy, and launch at login in the client.
2. Choose “Quit” from the menu bar, then open Activity Monitor and confirm that the client process has ended.
3. Go to System Settings → Network → VPN and remove old configurations clearly belonging to the current client if they are in an error state.
4. On macOS 15, open General → Login Items & Extensions → Network Extensions, turn off the old item, and then enable it again.
5. Restart the Mac and launch the client from Applications.
6. Test with the system proxy first, then enable TUN separately.

You can use a system command to list registered system extensions. This confirms that an extension exists; it does not prove that Clash traffic is passing through it:

systemextensionsctl list
scutil --nwi
ifconfig | grep -E "utun[0-9]"

Interfaces such as utun0 and utun1 do not by themselves prove that they belong to Clash, because iCloud Private Relay, corporate VPNs, and other network software can also create utun interfaces. A more reliable method is to compare interfaces, routes, and client logs before and after disabling Clash TUN, and confirm that the logs contain none of “permission denied,” “operation not permitted,” or “route setup failed.”

Reinstall the helper service

Many clients provide uninstall and reinstall controls under Settings → Service Mode or Settings → Clash Core. Uninstall first, fully quit the client, relaunch it, and install again. After authentication succeeds, return to the client and confirm that the service status says it is running; do not rely only on the administrator password window disappearing.

Do not copy unfamiliar sudo rm commands from the internet to bulk-delete LaunchDaemons, system extensions, or network settings. Bundle identifiers and helper-service names differ between clients, and deleting the wrong item can affect other VPNs. Use the client’s built-in uninstall option first; if the client will not start, consult its project documentation and verify the exact service name.

Safe reset steps for recurring Keychain prompts

Open Applications → Utilities → Keychain Access. Select the “login” Keychain on the left, then choose “All Items.” Search by the client name, developer name, or item name shown in the prompt. Double-click the target item and open Access Control to see which apps are allowed to access it.

1. Record the full Keychain item name shown in the prompt.
2. Quit the Clash client and its menu bar process.
3. In Keychain Access, locate only the matching item; do not delete the entire “login” Keychain.
4. If the access list points to an old path, remove the old app entry and save.
5. If the item clearly belongs to an uninstalled older client, delete that single item.
6. Relaunch the current client from Applications so it can recreate the item or request access again.
7. After verifying the app name, choose “Allow”; once everything is stable, decide whether “Always Allow” is appropriate.

After deleting a subscription-credential item, the client may ask you to sign in again or reimport the subscription. Confirm that the subscription link is still accessible first. Do not delete certificates, Wi-Fi passwords, browser secure-storage items, or generic password items whose ownership you cannot verify.

What to check when internet access still fails after approval

A network extension showing as enabled only means macOS accepted it. It does not confirm that the node works, the rules are correct, or DNS resolution succeeds. Follow the order below to avoid attributing every problem to system permissions.

1. Core status: Confirm that the mihomo or Clash Meta core is running and that the logs show no port conflicts or configuration parsing errors.
2. Subscription status: Update the configuration manually, confirm that the subscription has not expired, and select a specific node in the policy group rather than an unavailable placeholder policy.
3. System proxy: Run scutil --proxy to check the address and port, making sure they match the client’s mixed-port.
4. Operating mode: Rule is the best choice for everyday use. Global sends more requests through one policy, while Direct bypasses proxy-rule routing.
5. DNS: Check the configuration’s nameserver, fallback, and fake-ip settings. Restart the core after changes instead of only toggling the system proxy.
6. TUN conflicts: Quit other VPNs, packet-capture tools, and similar proxy clients before enabling Clash TUN by itself.
7. Firewall and filters: Open System Settings → Network → VPN & Filters and check for content filters that are enabled at the same time.

If the system proxy works but the connection fails as soon as TUN is enabled, the problem is usually related to routing, DNS interception, MTU, or another VPN conflict. Temporarily disable automatic routing and DNS takeover in TUN, testing each option separately. With Fake-IP enabled, also check whether LAN devices, corporate domains, and local domains need to be added to fake-ip-filter. Do not change every domain to Direct without understanding the rule behavior.

Conversely, if TUN works but the browser fails after TUN is disabled, check whether the system proxy was actually applied. After a failed Service Mode installation, some clients briefly light up the UI switch without changing the system proxy. Reinstall the helper service, then verify again with networksetup or scutil.

Avoid leaving behind permissions when upgrading or uninstalling

Before upgrading, turn off the system proxy and TUN, then quit the client. For in-app updates, keep the app in Applications; when replacing it manually, quit the old version first and overwrite it with the new one. Do not keep “Client,” “Client 2,” and a copy in Downloads at the same time. When switching branches or distributions, export the local configuration first and use the old client’s service-uninstall function.

Deleting the app does not automatically clear the system proxy. If the proxy still points to 127.0.0.1:7890 when you quit, the browser may lose internet access after the client is removed. Open System Settings → Network → Wi-Fi → Details → Proxies and disable the web proxy, secure web proxy, and SOCKS proxy. Alternatively, reinstall the client, enable the proxy, and then turn it off normally.

After uninstalling, check System Settings → General → Login Items & Extensions, System Settings → Network → VPN, and Keychain Access. Remove only items you can confirm belong to the old client. If you plan to keep using the same client, there is no need to delete all configuration during an upgrade; preserving subscription and rule files is usually safer.