Platforms 12-minute read

macOS Clash Permission Issues: Network Extension and Keychain Fixes

Fix macOS installation blocks, Network Extension approvals, and recurring Keychain prompts. Find the right System Settings, Helper installation steps, and clean uninstall leftovers.

Identify the Permission Blocking Setup

A Clash client on macOS may involve app launch permissions, system proxy settings, a privileged Helper, a Network Extension, and the Keychain. Different system components manage each one. When you see a “Permission Required” prompt, note its title and when it appears instead of repeatedly clicking Cancel. An installation may be missing just one permission, or remnants of an older version may coexist with the new one.

Four Prompts, Four Places to Fix Them

  • App cannot be opened or developer cannot be verified: This is a Gatekeeper launch check. Go to “System Settings” → “Privacy & Security.”
  • Installer, Helper, or Service Mode asks for a password: This is a privileged Helper installation. Enter the password for the current Mac administrator account, not your subscription password.
  • System or Network Extension is blocked: Allow the relevant extension under “Network” or “Login Items & Extensions.” Some macOS versions also require a restart.
  • Keychain access is requested every time the app starts: The saved password item's access control may no longer match, or an item created by an older client may still be accessed by the new one.

Check the macOS Version and CPU Architecture

Open the Apple menu in the top-left corner and choose “About This Mac.” Note the macOS version and chip name. Apple M1, M2, M3, M4, and later Apple silicon Macs should use arm64 packages; Intel Macs should use x64 or x86_64 packages. With the wrong architecture, the app may rely on Rosetta or fail while installing its Helper.

This guide uses macOS 13 Ventura, macOS 14 Sonoma, macOS 15 Sequoia, and mihomo-based clients such as Clash Verge Rev 2.x as references. Button labels vary by client—“Service Mode,” “Install Service,” “Helper,” “TUN,” or “Network Extension”—but the system authorization locations are broadly the same.

Handle App Installation and the First Launch Block

Move the App to Applications Before Launching It

  1. Open the downloaded DMG file.
  2. Drag the client icon into the “Applications” folder. Do not keep running it directly from the DMG window.
  3. Wait for the copy to finish, then eject the DMG.
  4. Open the client from Finder’s “Applications” folder.

The Helper typically records the main app’s path and signature. Running the app from Downloads, a mounted DMG, or a temporary folder can change its path after an upgrade and trigger repeated authorization requests. Avoid renaming the app after installation.

“Developer Cannot Be Verified” or “App Was Blocked”

First confirm that the package came from the project’s official release channel and matches your Mac’s architecture. Then try opening the app once so macOS records the block. Go to “System Settings” → “Privacy & Security,” scroll down to the blocked app, click “Open Anyway,” and approve the confirmation dialog.

If “Open Anyway” does not appear, the launch may not have been triggered, or the block record may have expired. Return to Finder, open the app again, and immediately check “Privacy & Security.” On a company-managed Mac, device-management policies may prevent users from allowing the app; an administrator must approve the app or system extension through the management policy.

Install the Privileged Helper and Service Mode

System proxy mode only changes macOS proxy settings, while TUN mode creates a virtual network interface and adjusts routes. Many clients install a privileged Helper to start the mihomo core, write routes, or manage DNS. Seeing an administrator password prompt while installing this service is a normal system authorization step.

Recommended Installation Order

  1. Quit any other running Clash, mihomo, or similar proxy clients.
  2. In the current client, open “Settings” → “Service Mode,” or “Settings” → “System Service.”
  3. Click “Install Service” or “Install Helper.”
  4. Enter the administrator account password in the macOS authorization dialog.
  5. Wait until the status changes to “Installed” or “Running,” then enable the system proxy or TUN.

If the currently signed-in account is not an administrator, enter a valid administrator username and password. Apple ID passwords and the account credentials used for the client subscription are not accepted here.

“Service Not Running” After Installation

Quit the client completely, then open it again. If the issue persists, open “Activity Monitor” and search for the client name, mihomo, or clash to check for an older process. You can also run this read-only command in “Terminal”:

ps aux | grep -E '[m]ihomo|[c]lash'
lsof -nP -iTCP:7890 -sTCP:LISTEN
lsof -nP -iTCP:7897 -sTCP:LISTEN

Port 7890 is common in traditional Clash configurations, while some mihomo clients use 7897 by default. If another process is using the port, quit the corresponding old client or change mixed-port under “Settings” → “Port Settings.” Do not let two clients control the system proxy at the same time.

If the service installation button spins indefinitely, use the client’s built-in “Uninstall Service” option, quit the app, restart the Mac, and install it again. Deleting the app in Finder does not automatically remove a system-level Helper, so “delete and reinstall” may not fix the issue.

Allow the Network Extension and Enable TUN

A Network Extension, network filter, and TUN virtual interface are different things. A client may provide a tunnel through Apple’s Network Extension API or have its privileged service create a utun interface. Whether a “Network Extension” switch appears depends on the implementation; the presence of a TUN button alone is not enough.

Check Paths on macOS 13 and 14

  • Open “System Settings” → “Network” → “VPN & Filters” and check whether the current client has a filter or VPN configuration.
  • Open “System Settings” → “General” → “Login Items” and check whether the relevant item is disabled under “Allow in the Background.”
  • Open “System Settings” → “Privacy & Security” and check the bottom of the page for a notice that system software or an extension was blocked.

Check Paths on macOS 15 and Later

In macOS 15 Sequoia, extension management is under “System Settings” → “General” → “Login Items & Extensions.” Click the details button next to “Network Extensions” and allow the extension belonging to the current client. If the client created a VPN or content filter, return to “System Settings” → “Network” → “VPN & Filters” and confirm that the item is allowed.

After an extension is allowed, macOS may require a restart. Save your work and restart when prompted. Simply quitting the client is usually not enough to complete the extension’s first registration.

Verify That TUN Was Actually Created

After enabling TUN, run this in Terminal:

ifconfig | grep -A 4 '^utun'
route -n get default
scutil --proxy

macOS itself creates multiple utun interfaces, so seeing utun0 or utun1 does not by itself prove that Clash is working. A better test is to compare the interface count before and after enabling TUN, check the client log for listener and route initialization messages, and verify that apps that ignore system proxy settings can still connect according to the rules after the system proxy is turned off.

Stop Repeated Keychain Prompts

A client may store subscription credentials, service authorization data, or system-proxy passwords in the login Keychain. After an app upgrade, signature change, path change, or migration from an older project, the Keychain access control list may no longer match. The result is an access prompt every time the app starts, updates a subscription, or enables the service.

Check What the Prompt Is Requesting

Do not rely only on the client name at the top of the dialog. Expand the details and confirm that the requester path points to the current client in “Applications.” Note the name of the Keychain item it wants to access. If the path points to Downloads, a deleted old app, or an unfamiliar program, choose Deny and close that program before cleaning it up.

If the path matches the current client, enter your Mac login password and choose “Always Allow.” If the same prompt returns at the next launch, repeatedly choosing “Always Allow” usually will not help; fix the specific Keychain item instead.

Delete One Old Item and Let the Client Recreate It

  1. Quit the client and confirm that its menu bar icon has disappeared.
  2. Open “Applications” → “Utilities” → “Keychain Access.” On newer systems, you can also search for “Keychain Access” with Spotlight.
  3. Select the “login” Keychain on the left, then choose “All Items” or “Passwords.”
  4. Search for the item name shown in the prompt. You can also search separately for the client name, Clash, mihomo, or the old client name.
  5. Open the item and check “Account,” “Location,” and “Access Control.” Delete only the individual item you have confirmed belongs to the old client.
  6. Open the client again and follow the prompts to save the credentials or install the service again.

If the login Keychain is locked, select “login” in Keychain Access and unlock it from the menu. Its password is usually the same as the current account login password. If the account password was changed without updating the Keychain, macOS may ask for the old password. Repair the login Keychain first instead of repeatedly reinstalling the client.

The Prompt Appears Only When Updating a Subscription

This usually points to a problem with subscription credentials, not TUN permissions. Remove the affected subscription and import it again so the client can recreate its storage item. Save the subscription URL first. After reimporting, manually run “Configuration” → “Update Subscription” once, then quit and reopen the client to verify.

Clean Up Uninstall Leftovers and Reinstall

An older Clash client and a new one may share ports, configuration directories, or background services. Typical symptoms include: the client has been deleted but the system proxy still points to 127.0.0.1:7890; the TUN switch immediately turns off; the old core starts even after the service installs successfully; or a Keychain prompt shows the old app name.

Turn Off the Proxy and Uninstall the Service First

  1. Open the old client and turn off TUN and the system proxy.
  2. Go to “Settings” → “Service Mode” and choose “Uninstall Service” or “Remove Helper.”
  3. Quit the client completely.
  4. Open “System Settings” → “Network” → your current network → “Details” → “Proxies.” Confirm that Web Proxy, Secure Web Proxy, and SOCKS Proxy do not retain local ports.
  5. Remove disabled old items under “VPN & Filters” or “Login Items & Extensions.”

If the old client will no longer open, reinstall the same version and use its built-in uninstall function. The client knows the exact identifier of its own Helper, making this safer than guessing at files in system directories.

Check User-Level Configuration Directories

In Finder, press Command + Shift + G and inspect these locations one by one:

~/Library/Application Support/
~/Library/Preferences/
~/Library/Caches/
~/Library/Logs/
~/Library/LaunchAgents/

Handle only directories or files whose names clearly identify the old client. Configuration directories may contain subscriptions, rule overrides, scripts, and logs. If you need to migrate them, copy them to a separate backup directory before deleting the originals. Do not use wildcard Terminal commands to bulk-delete every item containing clash or mihomo; other clients still in use may use those names too.

Confirm That the System Proxy Has Been Restored

Run scutil --proxy and check HTTPEnable, HTTPSEnable, and SOCKSEnable. After the system proxy is turned off, these values should normally be 0. If any remains 1, open the proxy settings for the current network service and turn it off manually. Wi-Fi and Ethernet are separate services, so check both.

Finish Troubleshooting by Symptom

System Proxy Works, but TUN Does Not

  • Confirm that Service Mode or the Helper is installed and running.
  • Check the Network Extension status under “VPN & Filters” and “Login Items & Extensions.”
  • Temporarily quit other VPNs, content filters, and similar proxy clients, then enable TUN again.
  • Check the client log for permission denied, route-write failures, or a DNS listener port conflict.
  • After restarting the Mac, launch only one client first to prevent multiple apps from creating competing default routes.

TUN Starts, but Some Websites Do Not Open

Permissions are usually working at this point, so troubleshoot DNS and rules instead. Check dns.enable, enhanced-mode, rule order, and the final matching policy in the configuration. Add LAN domains, corporate intranet hosts, and printer addresses to direct rules as appropriate. Reinstalling the Network Extension will not fix a rule configuration problem.

Authorization Is Required After Every Upgrade

Make sure the client is always installed at the same path and comes from the same official release channel. Quit the app before upgrading, then launch the upgraded version from “Applications.” When crossing several major versions—for example, migrating from an older ClashX series release to Clash Verge Rev 2.x—uninstall the old service first, then let the new client install its own service. Do not reuse the old Helper directly.

A Reproducible Verification Sequence

  1. Restart the Mac and open only the current client.
  2. Import the subscription and run one manual update.
  3. Choose a working node and enable the system proxy first.
  4. Confirm that the browser connects normally and check that the local port is listening.
  5. Turn off the system proxy, install the service, and enable TUN.
  6. Check changes to the utun interfaces and review the client log.
  7. Quit and reopen the client, then confirm that Keychain access is no longer requested repeatedly.

After these seven steps, app launch, subscription access, system proxy, Helper, Network Extension, and Keychain access have each been verified separately. If a problem returns, identify it by the failed step instead of deleting every configuration from scratch.

Download the Latest Clash Version