Install Clash on macOS: Allow Network Extensions and Handle Keychain Prompts

First, identify which prompt you’re seeing

When you first launch a Clash client on macOS, installing the app, routing network traffic, and saving credentials are separate steps. If the app won’t open, you likely haven’t reached network setup yet. A blocked network extension may affect only features that rely on it. A Keychain prompt means the app is requesting access to system-protected credentials. Troubleshoot based on when the prompt appears—it’s more effective than repeatedly reinstalling the app.

First, verify the client name, developer information, and download source. If a prompt refers to an unfamiliar app or helper process, cancel it. Don’t keep clicking “Allow” just to complete the setup.

App blocked? Start with the download source

Move the app to Applications before opening it

1. Download an installer for your Mac from a trusted project release page, and choose the build for Apple silicon or Intel. Check your Mac’s chip under Apple menu → About This Mac.
2. If you downloaded a DMG, open the disk image and drag the app into Applications. Don’t keep running it from the mounted disk image; this can make future updates and helper component permissions harder to verify.
3. Open the client from Finder → Applications, and check the app name and developer information shown by macOS. The first launch may require one extra confirmation.

If macOS says “Developer cannot be verified” or shows a similar warning, confirm the file’s source, then go to System Settings → Privacy & Security. Find the recently blocked app and follow the “Open Anyway” prompt. This option usually appears only after you’ve tried to open the app. Button labels and locations may vary slightly across macOS versions.

If the warning says the app is damaged, or its name doesn’t match what you expected, don’t treat it as a routine first-launch confirmation. Delete the file, download it again from a trusted source, and check that it matches your Mac’s processor and macOS version. Changing global security settings is not a standard way to troubleshoot a first launch.

Allowing network extensions: follow each system prompt

Clash clients often offer different ways to route traffic, such as System Proxy and TUN mode. System Proxy sends traffic from apps that honor macOS proxy settings to a local listening port. TUN mode routes a wider range of traffic through a virtual network interface. The exact implementation depends on the client and its core, so seeing “TUN” in the interface doesn’t mean every version will show the same network extension prompt.

What to check the first time you enable it

1. Import a working configuration, choose a node and routing mode, then start the client core. Don’t run multiple proxy clients at the same time, as they may overwrite each other’s system proxy or VPN settings.
2. If you only need apps that honor system settings, such as browsers, to use the proxy, turn on System Proxy in the client first. Then check the current proxy or VPN status under System Settings → Network and confirm it matches what you just changed.
3. To use TUN mode, turn on the corresponding option in the client. If macOS asks to add a VPN configuration, allow a network extension, or install a helper component, verify the app name, then follow the on-screen instructions and enter your Mac administrator credentials.
4. After granting permission, return to the client and make sure TUN is still enabled. Some setup processes require you to quit and reopen the client before the newly approved component loads.

On macOS 15 and later, check System Settings → General → Login Items & Extensions for Network Extensions. Some clients use a VPN configuration or another helper component instead, so not seeing an item there doesn’t necessarily mean installation failed. On some macOS 13 and 14 systems, you can also check System Settings → Network → VPN & Filters for the relevant VPN or filter status. Use the items actually shown on your Mac, and don’t approve unrelated extensions.

Allowing a network extension doesn’t import a subscription or activate proxy rules. Check permissions, configuration, nodes, and routing mode separately.

Keychain prompts: verify the request before granting access

Keychain Access is macOS’s credential protection system. When a client or helper process reads a saved password, certificate, or authorization detail, it may request access to an item in the “login” Keychain. An app name in the prompt doesn’t mean every process with that name should be allowed access. Check whether the requesting process, the item, and the action you just took all make sense together.

Check these four things when a prompt appears

• What triggered it: Did you just enable TUN, install a helper component, update a subscription, or change a setting that requires administrator access? If the prompt keeps appearing when you haven’t done anything, cancel it and investigate first.
• Requesting process: Does the name match the client you’re using or a helper component it explicitly documents? Don’t approve an unfamiliar process.
• Requested item: Is the Keychain item related to the feature you’re using? Open the built-in Keychain Access app to check the item name and access control details.
• Password requested: To unlock the “login” Keychain, macOS usually needs your current Mac login password—not your subscription password, and not necessarily your Apple Account password.

If the request makes sense, choose “Allow” to grant access this time. Choose “Always Allow” only if you trust the process and item, and have a good reason to allow repeated access. If your Keychain password differs from your current login password, you may have changed your Mac password without updating the old Keychain password. Follow Apple’s macOS Keychain recovery guidance; don’t keep entering your password into an unfamiliar prompt.

Don’t delete the entire “login” Keychain just to get rid of a prompt. It may contain credentials for your browser, email, and other apps. If only one item keeps causing errors, note its name, quit the client, and check the item’s access controls and whether the associated app is still installed.

Still can’t connect after granting permission? Troubleshoot the connection

If permissions are granted but websites still won’t load, figure out whether the issue is with the core, the local proxy, the subscription node, or rule matching. Work through these checks in order, changing one setting at a time so you can tell what made a difference.

1. Check the core status. The client should show that the core is running. If startup fails, check the client log for a port conflict, configuration parsing error, or helper component issue. Don’t assume a core startup failure is caused by a network extension.
2. Check the configuration and node. Make sure the subscription has updated and the active Profile contains a working node. Check that the selected proxy group has an outbound selected. A successful subscription update only confirms that the configuration was fetched; it doesn’t mean every node is reachable.
3. Check local ports. Many sample configurations use HTTP port 7890 and SOCKS port 7891, but check the active configuration’s port, socks-port, or mixed-port values. The port set in System Proxy must match the port the client is listening on.
4. Check the routing mode. Rule mode routes traffic according to rules. Global mode typically sends all intercepted traffic through the selected proxy. Direct mode sends traffic out without a proxy. Note the mode you’re testing so you don’t mistake the result of Direct mode for a permissions problem.
5. Check what’s being routed. With only System Proxy enabled, some apps that ignore system proxy settings may still connect directly; check TUN only if you need to route that traffic too. Before switching to TUN, turn off other VPNs to avoid conflicts over routes or DNS settings.

If the issue affects only local network device discovery, printers, or a particular game, review TUN routing, DNS, and bypass settings instead of repeatedly approving Keychain requests. If those features work again when TUN is off, keep using System Proxy for now and adjust bypass rules by following the client documentation. Preserve YAML indentation when editing a configuration file, then check the client for parsing errors after saving.

Post-install checklist

Before wrapping up, note the client version, macOS version, and current routing method. These details can help you tell whether you’ll need to grant permissions again after an upgrade or when moving to a new Mac. Keep only the client version you use in Applications, and check that the enabled network items in System Settings belong to it. When you quit the client, the system proxy or VPN status should return to the expected state.

• The app opens normally from Applications, with no unexpected prompts about an unknown source.
• With System Proxy or TUN enabled, the client core stays running; when you turn it off, the corresponding system network setting is cleared.
• Keychain requests refer only to identifiable items and processes. Unverified requests have been canceled and their names recorded.
• The active configuration, nodes, routing mode, and listening ports have all been checked, so connection issues can be diagnosed separately from permission issues.