Install Clash on macOS: Network Extension Permissions, Keychain Prompts, and “App Is Damaged” Errors

First, identify whether it’s an installation block, a network permission, or a credential request

macOS apps with Clash in their names don’t all use the same installation and authorization methods. The user interface, proxy core, privileged helper, and Network Extension may come from separate components. Clash Meta is now called mihomo; using the mihomo core doesn’t necessarily mean the client uses Apple’s Network Extension for TUN. Before responding to a prompt, note the client name, version, macOS version, and exact message. Don’t assume every password prompt is asking for the same permission.

Check your Mac’s processor and app location before installing

Choose arm64 for Apple silicon and x64 for Intel Macs

Open the Apple menu → About This Mac. If it shows an Apple M-series chip, choose the macOS arm64 or Apple silicon build. If it shows an Intel processor, choose the x64 or x86_64 build. A Universal build may include both architectures; check the release notes. Rosetta can run some Intel apps on Apple silicon, but that doesn’t guarantee their helper tools are compatible.

1. Quit any running copy of the client with the same name to prevent an old process from holding the local proxy port.
2. Open the DMG and drag the app to Applications. Don’t keep running it from the disk image or Downloads folder.
3. Eject the DMG, then launch the client from Applications. Any subsequent authorization should apply to this copy in its permanent location.
4. First import a configuration and test the system proxy. Enable TUN only after confirming the basic connection works.

Keeping multiple copies with the same name can make login items, Keychain access records, and the actual launch path inconsistent. To update, quit the app first, then replace the existing copy in Applications. Don’t authorize a newly downloaded copy while an older version is still running.

“App is damaged and can’t be opened”: check before allowing it

“App is damaged” doesn’t necessarily mean the download was incomplete. It can also indicate an invalid signature, modified app contents, or a failed system assessment. Another common message is “Apple cannot check it for malicious software.” These errors aren’t interchangeable, and you shouldn’t disable system security checks just because a warning appears.

Use macOS’s per-app approval option first

1. Confirm the installer came from the project’s official release channel, and check the system requirements and processor architecture.
2. Download the installer again, replace the old copy completely, and try launching it once.
3. Open System Settings → Privacy & Security and check the Security section for a block notice for the app.
4. Only after confirming the app’s identity, use the system’s Open Anyway option or similar, then authenticate as prompted.

macOS 15 changed how some improperly signed or notarized apps can be approved. Don’t rely on older guides claiming that Control-click → Open will always bypass the warning. If macOS explicitly reports malware or says the app will damage your computer, stop and verify the source. The approval steps for ordinary apps don’t apply to that warning.

Use Terminal checks only for a specific, verified app

The example below uses a client installed at /Applications/Clash Verge.app. If the app has a different name, use its actual Finder path; you can drag the app into Terminal to insert the path. These three commands check the quarantine attribute, verify code-signing integrity, and request a system assessment, respectively. They do not grant network permissions.

xattr -p com.apple.quarantine "/Applications/Clash Verge.app"
codesign --verify --deep --strict --verbose=2 "/Applications/Clash Verge.app"
spctl --assess --type execute --verbose=4 "/Applications/Clash Verge.app"

If the first command returns “No such xattr,” the attribute isn’t present; this doesn’t mean the installation failed. A successful signature check alone doesn’t prove the publisher is trustworthy—you still need to verify the source and signing identity. If signature verification fails, download the app again or contact its maintainers. Don’t re-sign it to conceal the reason for the failure.

Only consider removing the app’s quarantine attribute after verifying its source and integrity and understanding the risks of bypassing quarantine:

xattr -d com.apple.quarantine "/Applications/Clash Verge.app"

This command won’t repair a damaged app, restore a signature, or notarize it, and may not fix a launch failure. Don’t target the entire Applications folder, routinely add recursive flags or administrator privileges, or disable Gatekeeper globally. If the problem persists, save the error and check the project’s installation instructions.

Enabling TUN for the first time: handle Network Extensions and helper services separately

TUN routes traffic through a virtual network interface and can cover some apps that ignore the system proxy, though its actual reach still depends on routes, exclusions, and protocol support. A system proxy mainly provides apps with HTTP, HTTPS, or SOCKS proxy settings and usually doesn’t require a Network Extension. Authorization for one mode doesn’t imply authorization for the other.

First, find out which implementation the client uses

• Privileged helper or service mode: The client may ask to install a helper so the core can create a TUN interface and adjust routes and DNS. This type of implementation may not appear in the Network Extensions list.
• Network Extension: A client using Apple’s Network Extension may request a VPN configuration, run a tunnel provider, or ask you to approve an extension. Approve only the item associated with the app you just installed.
• Content filter: If macOS separately asks to filter network content, check the project documentation to see whether it’s actually required. This isn’t a universal prerequisite for enabling TUN in Clash clients.

Find the approval settings for your macOS version

On macOS 13 and 14, check the bottom of System Settings → Privacy & Security for a blocked system software or extension notice, and look for VPN or filter items under Network. On macOS 15, check System Settings → General → Login Items & Extensions → Network Extensions. Find VPN configurations on the VPN page in System Settings. Whether an item appears depends on the client’s implementation and installation progress.

1. Turn off other VPNs, TUN in other proxy clients, and test tools that may change routes.
2. Install the helper service required by the client’s documentation, and check the program name in the system authentication dialog.
3. Enable TUN and respond to the configuration or extension request triggered by this action. Restart only if macOS asks you to.
4. Check the client logs to distinguish permission errors, interface creation failures, and route conflicts. Don’t rely only on whether the toggle is on.

Work-managed Macs may have device management policies that restrict extensions or VPN configurations. Contact your administrator rather than lowering startup security or disabling System Integrity Protection. Disabling these protections should not be a general prerequisite for installing this type of client.

Repeated Keychain prompts: check the password, app identity, and item permissions

A typical Keychain dialog says that an app wants to use confidential information stored in Keychain and names the specific item. This is different from the “Allow” authentication prompt shown when installing a helper. Read the request carefully before choosing Allow Once, Always Allow, or Deny.

Your login Keychain password may differ from your current account password

Normally, the login Keychain unlocks automatically when you sign in. If your login password was reset through account recovery or by another administrator, the old Keychain may still use your previous password. Repeatedly entering your new login password may not work. Open Keychain Access using Spotlight, check whether the login Keychain is locked, and determine whether you need the old password to unlock it.

If you don’t know the old password, don’t reset the Keychain just to dismiss the prompt. Resetting it may make passwords, certificates, or tokens in the old Keychain inaccessible. Read the system warning and confirm your backups and account recovery options before deciding what to do.

An app identity change after an update may trigger a new approval request

Switching release channels, moving to a different branch, using a build signed differently, or running copies of the same app from multiple locations can invalidate existing access approvals. The same appearance and name don’t guarantee that macOS recognizes the same code identity.

1. Quit all similar clients and run only one copy—the one in Applications.
2. In Keychain Access, search for the exact item name shown in the prompt. Don’t bulk-delete items with Clash in their names.
3. Open the item’s details. For password items with an Access Control option, check whether the allowed app points to an old copy.
4. Once you’ve confirmed the current app needs this credential, grant access in the system prompt. Don’t allow access for all apps.

Still can’t open websites after approval? Check ports, proxy settings, and TUN logs

If the app launches and Keychain prompts stop, that only means the installation or credential issue has been addressed—not that the proxy connection works. Verify the core listener, local proxy endpoint, node connection, and system traffic routing separately.

Test the local endpoint on a specific port

If the client’s active configuration explicitly shows mixed-port: 7890, you can use the command below. 7890 is just an example, not a standard port for every client. Use the port in the configuration that’s currently active.

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

• No listening process: Check whether the core is running, whether the configuration parsed successfully, and whether the port was changed to a different number.
• The listening process belongs to an old client: Quit the old process normally, then start the current client. Don’t force-quit unfamiliar system processes.
• The explicit proxy test receives an HTTP response: This shows that this request reached the local endpoint, but doesn’t guarantee that every website or rule is working.
• The explicit proxy works, but the browser still fails: Check the system proxy for the active network service, the browser’s own proxy settings, and DNS configuration.

scutil --proxy shows the system proxy status. If you’re using TUN alone, it may be normal to see no HTTP proxy entries. To test TUN, check the logs for interface, route, and DNS errors, then make a request without --proxy. The presence of a utun interface doesn’t prove Clash is routing traffic; system services and other VPNs can create these interfaces too.

Quit and roll back: restore your connection before further troubleshooting

If you lose network access, follow this order: turn off TUN → turn off the system proxy → quit the client normally. If the client has crashed, open System Settings → Network → your current Wi-Fi or Ethernet service → Details → Proxies. Check for settings pointing to 127.0.0.1 and remove only those added by this client.

Then check whether the VPN page in System Settings still has a connection enabled by this client. Don’t remove work profiles, Network Extensions for other VPNs, or certificates you installed yourself. Once the connection is restored, reopen the client and test the system proxy first, then TUN separately. Avoid changing multiple settings at once so you can identify the cause.

When reporting a problem, include your macOS version, processor architecture, client and core versions, when the error occurred, and logs with sensitive information removed. Clearly distinguish “failed on first launch,” “helper installation failed,” “Keychain access denied,” and “TUN routing failed.” This is usually more useful for diagnosing the problem than repeatedly reinstalling the app.