Install Clash on macOS: Network Extension and Keychain Permissions

1. Check your Mac’s architecture, macOS version, and app location

Choose the right Apple silicon or Intel build—not just by filename

Open the Apple menu → About This Mac and check the Chip or Processor field. For Apple M-series Macs, choose an Apple silicon, ARM64, or aarch64 build. For Intel Macs, choose x64 or x86_64. Universal builds typically include both architectures, but must still meet the client’s minimum macOS version.

• Note the full macOS version, such as macOS 14.7, rather than just writing “Mac.”
• Verify the download source, project name, and package architecture. Don’t install repackaged files from unknown sources.
• Open the DMG, drag the app to Applications, eject the disk image, then launch the app from Applications.
• Quit any older client before launching for the first time to prevent multiple apps from changing system proxy settings or competing for the same listening port.

Don’t keep running the app from a DMG or Downloads. A consistent install location helps keep the updater, helper tool, and permission records in sync. Launching copies from different locations can cause Keychain access to be granted to a different copy than the one actually running. On Apple silicon, an Intel build may prompt you to install Rosetta; that’s unrelated to proxy permissions.

2. Gatekeeper alerts: decide whether it’s safe to proceed

Gatekeeper checks run when an app launches. The core may not be running yet, so changing subscriptions, DNS, or rules usually won’t help. Alert wording varies across macOS versions; respond according to the type of warning.

Allow a trusted app to open once

1. Try opening the app once from Applications and read the macOS alert.
2. Go to the Apple menu → System Settings → Privacy & Security.
3. Under Security, look for the app that was just blocked. Choose Open Anyway only if the option appears and you’ve verified the source is trustworthy.
4. Complete any authentication macOS requires, confirm the app name, then open it.

In macOS 13, 14, and 15, the location and availability of these controls may differ. Managed devices may also prevent users from approving apps. If there’s no button, investigate the signature, system compatibility, or device policy rather than repeatedly trying to launch the app.

3. System proxy, TUN, and Network Extension permissions

System proxy: route traffic from apps that honor system settings to a local port

A system proxy typically directs HTTP, HTTPS, or SOCKS requests to the client’s local listening address. It doesn’t automatically capture traffic from every process or create a TUN interface. Some clients can update proxy settings directly; others require administrator authentication to install a helper tool or change network settings.

On macOS 13 and later, go to System Settings → Network → your active Wi-Fi or Ethernet service → Details → Proxies to check the settings. You can also search for “proxy” in System Settings to find the relevant panel.

• The local address is usually 127.0.0.1, but use the port specified by your client.
• With mixed-port: 7890, the port can accept both HTTP and SOCKS connections. This is only an example; not every client uses port 7890.
• If the proxy is configured but the core isn’t listening on that port, your browser may immediately report a connection failure.

TUN: find out how your client implements it

TUN mode routes traffic through a virtual network interface, then passes it to the core for processing. Creating the interface and configuring routes or DNS may require elevated permissions. Common implementations include launching the core with a privileged helper tool or using a Network Extension integrated into the client. Their installation and approval steps aren’t interchangeable.

In macOS 15, check Network Extensions under System Settings → General → Login Items & Extensions. Which items appear depends on what the client actually installed. Earlier macOS versions may require you to allow blocked system software under Privacy & Security. Follow the location shown in the current system prompt, and verify the developer’s name.

If the client only installed a privileged helper tool, it’s normal not to see a Network Extension toggle. Enabling standard TUN doesn’t mean you need to enter Recovery and lower startup security. Follow the client’s documentation only when it explicitly says a particular extension is required. Don’t apply legacy kernel extension instructions to every mihomo client.

4. Keychain prompts: Keychain password vs. administrator password

Keychain stores sensitive data such as passwords and tokens. A client may save subscription credentials or other account information there, but not all clients do. When a prompt appears, check the requesting app and the name of the Keychain item instead of entering a password just because you see a password field.

Identify the prompt first

• “Wants to make changes” and asks for administrator authentication: This usually involves installing a helper tool or changing system settings; it doesn’t mean the app is accessing Keychain.
• “Wants to use confidential information stored in your keychain”: This is an access request for a specific item. Check what the item is used for.
• Asks to unlock the “login” keychain: You usually need the password for that keychain, which may not match your current account login password.

If you reset your macOS login password through account recovery or another method, the old login keychain may still use the previous password. Repeatedly entering the new password may not unlock it. Don’t enter your subscription account password in the system’s Keychain unlock prompt; they’re separate credentials.

Choosing “Allow Once” or “Always Allow”

When checking the request for the first time, you can allow it once and see whether the client can access the relevant configuration again. Consider ongoing access only after confirming the app’s source, the item’s purpose, and the timing of the request. If the prompt appeared after an update, the app signature or access control may have changed; an update alone doesn’t prove the request is trustworthy.

1. Press Command + Space, search for and open Keychain Access. Don’t confuse it with the Passwords app in newer macOS versions.
2. Select the login keychain, then search for the client name or the service shown in the prompt.
3. Double-click the relevant item to inspect it. If it has an Access Control option, check that the allowed app still points to the currently installed copy.
4. Don’t set an item to allow access to all apps just for convenience. Only change items you can confirm belong to this client.

5. Targeted permission resets and network recovery

Repeated helper tool installs: check for duplicate app copies first

Quit all similar clients. Make sure Applications contains only the copy you intend to use, then relaunch it. If the client offers options such as uninstall service, install service, or repair service, use its own maintenance controls. Menu names vary by product, so don’t follow another client’s button path.

After maintaining the service, check the startup log once, then restart your Mac if needed. Don’t manually delete files in bulk from /Library/PrivilegedHelperTools or /Library/LaunchDaemons; those folders also contain services for other software. If your work Mac is restricted by policy, ask your administrator what’s allowed.

No internet after quitting the client: check for a leftover system proxy

If the app quits unexpectedly, the system proxy may still point to a local port that’s no longer listening. First, turn off the proxy enabled by this client for your current network service in System Settings, then test a direct connection. These Terminal commands are read-only: the first lists network service names, and the next two are examples for a service named Wi-Fi.

networksetup -listallnetworkservices
networksetup -getwebproxy "Wi-Fi"
networksetup -getsecurewebproxy "Wi-Fi"
networksetup -getsocksfirewallproxy "Wi-Fi"

If your service has a different name, use its full name from the first command’s output. Check Enabled, Server, and Port in the results. A local address still being listed doesn’t necessarily mean the proxy is active; check whether it’s enabled.

Only use the commands below to turn off proxies if you’ve confirmed they belong to the client you quit and aren’t part of a company network configuration. You may need administrator authentication. Automatic proxy configuration and automatic proxy discovery are separate settings and aren’t affected by these three commands.

networksetup -setwebproxystate "Wi-Fi" off
networksetup -setsecurewebproxystate "Wi-Fi" off
networksetup -setsocksfirewallproxystate "Wi-Fi" off

Persistent Keychain access failures: recreate only the confirmed credential item

Quit the client, back up your configuration, and make sure you can retrieve your subscription URL and account credentials again. In Keychain Access, locate the confirmed client item. If needed, delete only that item, then relaunch the client and import the configuration or sign in again. Deleting a Keychain item won’t repair a configuration file or recover a lost subscription URL.

Don’t grant Full Disk Access as a generic fix. Normal proxy forwarding shouldn’t require broader file access just because of a network issue. Consider granting it only when a specific feature requires it and the client’s documentation explains why.

6. Post-install checks and troubleshooting notes

1. Check startup: Launch the client from Applications and confirm the core is running normally, with no recurring crash or port conflict errors in the logs.
2. Check configuration: Import a trusted configuration and confirm that policy groups and outbound entries are present. An open window doesn’t mean the subscription loaded successfully.
3. Check the system proxy: Turn off TUN and enable the system proxy. Visit a page that needs to be routed, then check the connection log for the domain, matched rule, and actual outbound.
4. Check TUN: Enable it only if you need it, then check the logs for interface setup, routing, and DNS. If it fails, turn TUN off first and confirm the system proxy path still works.
5. Check recovery on exit: Quit the client normally and check whether the system proxy has been restored. If not, check the current network service as described above.

If a page won’t load and there’s no matching connection in the logs, first check how traffic is being routed. If a connection appears with a matched rule and outbound but times out, investigate the proxy node, DNS, and destination service. An approved Network Extension only means macOS can load that component; it doesn’t prove the subscription works or that a destination website is reachable.

Include these details when reporting an issue

• Full macOS version and whether your Mac uses Apple silicon or Intel.
• Client version and core version, listed separately.
• The complete prompt text, what triggered it, and whether you were using the system proxy or TUN at the time.
• Logs from about 30 seconds before and after the issue, and whether any other VPN, proxy, or network filtering software was running.

Before sharing screenshots or logs, redact subscription URLs, tokens, account information, and proxy node credentials. Check each layer in turn—launch checks, system proxy, TUN or extensions, then Keychain. This usually preserves more useful clues than reinstalling everything and reduces the impact on existing network settings.