ClashX Permissions on macOS: Network Extensions, System Extensions & Keychain Prompts

Identify the client and the type of permission

When you first open ClashX, you may see prompts for an administrator password, network settings, and Keychain access. These are separate permissions. Before troubleshooting, open About from the app menu in the menu bar and note the client name, version, and macOS version. Traditional ClashX, its derivatives, and other clients powered by mihomo may install helper tools and route traffic in different ways, so their prompts won't necessarily match step for step.

Keep in mind: enabling the system proxy does not install a network extension, and TUN mode does not necessarily use Apple's Network Extension framework. Traditional ClashX often uses a privileged helper to change system proxy settings. Some other clients use a privileged service to create a TUN interface, while others use Network Extension. If no extension prompt appears, that doesn't mean a permission is missing.

First launch and security approval

Move it to Applications before launching

1. Choose a client for Apple silicon or Intel from the download page. To check your chip or processor, open About This Mac from the Apple menu.
2. If you downloaded a disk image, open it and drag the app to Applications, then launch it from there. Don't keep running it from a mounted disk image or your Downloads folder.
3. If macOS asks whether to open an app downloaded from the internet, verify the app name and select Open. This is a first-launch confirmation, not a network extension approval.
4. If macOS says the developer can't be verified, first confirm the download source and check whether the client is still maintained. Then look for a notice about this launch under System Settings → Privacy & Security.

On macOS 13 Ventura, macOS 14 Sonoma, and later versions, an eligible block may show an Open Anyway button near the bottom of Privacy & Security. Whether it appears depends on the reason for the block and your macOS version; it isn't a universal fix. macOS 15 Sequoia changed how some unsigned or unnotarized apps are opened, so don't assume right-clicking and choosing Open will always bypass the block.

Helper tools and administrator passwords

Some versions of ClashX ask to install a helper tool the first time you set up the system proxy. GUI apps usually run with the current user's permissions; a helper tool performs operations that require elevated privileges. Enter the credentials for an administrator account on this Mac—not a subscription password, node password, or Apple Account password.

Check these three things before approving

• What triggered it: Did you just choose to install a helper tool, repair a service, or enable the system proxy? If a request appears without one of these actions, cancel it and check which process made the request.
• Dialog name: Confirm that the requester belongs to the client you installed. A helper tool's name may differ from the main app, so check the documentation for your version.
• Install location: Make sure the app is in Applications. Avoid moving it repeatedly or leaving multiple old copies that you might launch by mistake.

If you accidentally click Cancel, it usually only stops the current installation. Reopen the client and trigger the helper installation or repair again. If it asks to reinstall on every launch, quit all copies of the client, keep only the version you're using, and check the logs for service installation errors. Don't delete similarly named files in /Library/PrivilegedHelperTools or remove system services in bulk.

A Mac managed by your company or school may restrict privileged service installations. If you don't have administrator access, ask your device administrator to handle it; repeatedly entering a standard user's password won't grant additional privileges.

Network extensions, system extensions, and VPN configurations

Only handle extension approvals if the client actually uses the relevant mechanism. Network Extension is an Apple framework for networking features, and some extensions can be distributed as system extensions. “Network extension” and “system extension” aren't necessarily separate steps that both need approval. A prompt to add a VPN configuration isn't the same as installing a kernel extension.

Find the right settings for your macOS version

• macOS 13 and 14: First check for an extension-block notice under System Settings → Privacy & Security. To review VPN configurations, search for “VPN” in System Settings.
• macOS 15: Check for network extensions under System Settings → General → Login Items & Extensions → Network Extensions. The list and available controls depend on the extensions installed.
• Later macOS versions: Settings may move or be renamed. Search System Settings for “Network Extensions” or “VPN,” and follow the labels shown on your Mac.

If macOS asks you to allow system software from a developer, compare the developer information with the details provided by the client. Restart only if macOS explicitly asks you to. If the setting doesn't list the relevant extension, don't approve an extension from another app or install extra components just to “complete” the permissions.

If you've approved the extension but TUN still won't start, check the client logs. Routing failures, DNS listener conflicts, or another VPN taking over the connection can all cause the same “connection unavailable” symptom. An enabled extension only means macOS allows it to load; it doesn't confirm that your subscription, DNS, and outbound rules are configured correctly.

Keychain prompts: check the item before granting access

A Keychain prompt usually identifies the process requesting access and the item it wants to use. Not every version of ClashX requests Keychain access on first launch; the prompt appears only when the client or a related component needs to save or read credentials. Don't grant an app access to your entire Keychain just because a guide includes this step.

“Allow,” “Always Allow,” and “Deny”

• Allow: Approves access this time. Use it when you've verified the request but don't want to grant ongoing access.
• Always Allow: Records ongoing access for this item. Future access is still subject to the app's identity and Keychain access controls. Choose this only after verifying the requester and the item.
• Deny: Withholds the credentials for this request. The app may not be able to read the saved information, but you can usually still view its other settings.

If you're asked to unlock the “login” Keychain, the required password is usually the Keychain's password. It often starts out matching your Mac login password. If you reset your account password using a recovery process, the old Keychain password may not have changed with it. Repeatedly entering the new password will still fail, which doesn't necessarily mean the client is at fault.

Use Spotlight to find and open Keychain Access, then search the “login” Keychain for the item named in the prompt. For items that support it, open the details and check Access Control. Change settings only for the specific item clearly associated with the client. Don't delete the entire login Keychain or allow all apps to access the item. The Passwords app in newer macOS versions doesn't replace these general Keychain access controls.

How to diagnose repeated prompts after an update

An app update, a change in signing identity, or launching another copy from a different location can make an existing access permission stop matching. Quit any old copies, launch the current version from Applications, and check the process name in the prompt. If the request is for an unfamiliar browser password or another app's credentials, deny it and check the source. Don't approve it just because the name includes Clash.

Recover after denying a request: fix the step that failed

Change one thing at a time during recovery. First turn off the system proxy and TUN, keeping a regular network connection available. Once you've completed the relevant approval, re-enable only the features you need. Don't switch cores, reinstall the app, delete the configuration, and change DNS all at once, or it will be hard to tell what fixed—or caused—the problem.

If a configuration profile manages the device, some settings may be locked. Note the exact prompt, macOS version, and client version, then ask your administrator to investigate. Subscription URLs may contain access tokens; hide the full URL and account details before sharing screenshots or logs.

After approval, check the port and test real traffic

Approval is only one part of setup. Next, import a working configuration, confirm that the core is running, and then enable the system proxy. The system proxy mainly affects apps that honor system proxy settings; TUN routes more traffic through a virtual interface. A webpage loading in your browser doesn't mean terminal commands, games, and every background process use the same route.

Diagnose the setup with three read-only commands

Run these commands in Terminal. The examples use 7890 as the HTTP or mixed proxy port. Check your current port or mixed-port setting first, then replace the example with its actual value. This is an example port, not a fixed default for every ClashX version.

# Check the current macOS system proxy settings
scutil --proxy

# Check whether the example port is listening for TCP connections
lsof -nP -iTCP:7890 -sTCP:LISTEN

# Send a request explicitly through the local HTTP proxy
curl --proxy http://127.0.0.1:7890 --connect-timeout 10 --max-time 20 -I https://example.com

• With scutil --proxy, an enabled HTTP proxy typically shows HTTPEnable : 1, along with its address and port. HTTPS uses fields such as HTTPSEnable. Check the protocols that are actually enabled instead of looking for one fixed field.
• If lsof returns no output, first check whether the core is running, whether the port is correct, and whether you're using a separate SOCKS port. If a port is listening, also verify which process owns it.
• The curl example explicitly uses the specified proxy, regardless of whether Terminal reads the system proxy settings. If the connection is refused, check the listening port first. If it connects but times out, check the node, DNS, and outbound rules.

The curl command-line tool usually doesn't automatically use the macOS system proxy settings configured in the GUI. So “the browser works, but Terminal doesn't” doesn't necessarily point to a permissions problem. To test a SOCKS endpoint, use the actual port in a URL like socks5h://127.0.0.1:port, replacing the address and port as needed.

Confirm your network works before quitting the client

When you finish the initial setup, turn off the system proxy and TUN, then quit the client and confirm that your regular connection still works. If you're offline after quitting, open System Settings → Network → your active Wi-Fi or Ethernet connection → Details → Proxies. Check for HTTP, HTTPS, SOCKS, or automatic proxy settings that still point to 127.0.0.1. Turn off only the settings changed by this client; leave any required by your organization's network.

If you're using a VPN or network extension, also check that its connection has been disconnected. Don't remove all network services to restore connectivity. Once you've checked the settings above, start the client in this order: confirm the core is running, verify the configuration, then enable the proxy features you need. Revisit the relevant permission only if you see a specific permissions error.