macOS Clash Client Permissions: Network Extension Approval & Keychain Prompts

Know the four types of permission prompts

Seeing the client window open on macOS doesn’t mean the services it needs for proxying are running. First-run prompts can come from Gatekeeper, administrator authentication, a network extension, or Keychain. Each serves a different purpose, and each has a different recovery path if you decline.

Mihomo is the core; the client provides the configuration interface, system integration, and permission requests. TUN implementations vary by client: some use a privileged helper to start the core, while others use Network Extension. The presence of a “TUN” switch alone doesn’t mean you need to find a network extension in System Settings.

First launch: install location and security checks

Check your Mac’s processor, then launch from Applications

1. Open the Apple menu → About This Mac. If it shows an “Apple M…” chip, choose the Apple Silicon or arm64 build; if it shows an Intel processor, choose the x64 build. Follow the client’s instructions if it offers a universal build.
2. For apps distributed as DMGs, drag the app to Applications, then eject the disk image. Don’t run the app from the DMG long-term.
3. Quit any older instance, then launch the app from Finder → Applications. Running old and new versions at the same time can cause port conflicts or mismatched helper versions.
4. For the first run, import your configuration and confirm the core starts. Then enable system proxy or TUN one at a time to pinpoint where a problem begins.

Tell routine blocks from security warnings

On macOS 13 Ventura, 14 Sonoma, and 15 Sequoia, the relevant controls are usually under System Settings → Privacy & Security. After you try to open an app, this page may show a record of the block. Choose “Open Anyway” only after confirming the app came from a trusted source and macOS offers that option. Button names and locations may vary slightly by version.

“App is damaged” isn’t the same as a routine first-launch confirmation. It can indicate an incomplete download, an invalid signature, or a modified app bundle. Delete the current copy, download it again from the client maintainer’s official release channel, and check the system requirements. If macOS warns that the app will damage your computer or contains malware, stop—don’t bypass the warning.

• Don’t disable Gatekeeper as a routine installation step.
• Don’t remove quarantine attributes from your entire Downloads folder.
• Company-managed Macs may be restricted by device management policies. Ask your administrator which clients and extensions are approved.

Helper services: administrator approval and retrying after a denial

System proxy and TUN have different permission requirements. A system proxy mainly changes proxy settings for the current network service; TUN typically also configures a virtual interface, routes, and DNS. The client may use a background helper to make these changes, which can trigger an administrator prompt to install or update the helper.

Check these three details before approving

• Requester: It should match the client you just used or a helper you recognize—not an unknown script process.
• Action: Confirm the request is to install or update a service, or change network settings—not to do something unrelated to proxying.
• Account: Standard users typically need administrator credentials. Enter the administrator password only in the macOS authentication dialog—never paste it into a subscription page or chat.

If you clicked Cancel, you usually don’t need to reinstall the whole client. Go back to its service management option and run the install or repair again. It may be called “Service Mode,” “Helper,” or “Install Service”; use the label shown in your client. When it’s done, quit and relaunch the client, then check the logs.

Helper installed, but TUN still won’t start

Check the logs for permission denied, helper connection failures, or port conflicts. After a client upgrade, an older helper may still be running; use the client’s built-in service update or reinstall option first. Don’t delete files from /Library/LaunchDaemons based on generic online commands—the service identifiers vary by client.

On macOS 13 and later, you can also check background activity under System Settings → General → Login Items or Login Items & Extensions. Background items and network extensions are separate controls. If the client appears here, check its documentation to see what the item does.

Network extension and VPN configuration approval

Only clients that use the relevant macOS mechanisms request a network extension or add a VPN configuration. A client that runs Mihomo TUN through a privileged helper may never show this prompt. In that case, check the helper and core logs instead of searching repeatedly for an extension that isn’t there.

Find the right setting for your macOS version

• macOS 15 Sequoia: Go to System Settings → General → Login Items & Extensions. Under Extensions, find Network Extensions and use its details view to check the client’s entry.
• macOS 13 Ventura and 14 Sonoma: Search System Settings for “VPN” or “Filters” to find network-related configurations. If macOS says an extension was blocked, also check the corresponding entry under Privacy & Security.
• Other versions: Search System Settings for “Network Extensions,” “VPN,” or “Filters.” Different extension types may appear in different places, so don’t assume a menu path from one version applies to every version.

“Allow VPN configurations” lets the client create a system network configuration. It doesn’t mean your subscription imported successfully or that a proxy node is reachable. After approving, return to the client, select a configuration, start the core, and test the connection. A VPN status in System Settings also doesn’t confirm rule matches or the exit route.

What to do after declining

1. Turn off TUN or disconnect in the client to stop repeated background retries.
2. In System Settings, check whether the extension is disabled or has a record showing it was blocked.
3. Return to the client and try connecting or installing the extension again, then follow the macOS prompt. Restart only if macOS explicitly asks you to.
4. If you have multiple old VPN configurations, check which app owns each one before removing it with that app’s removal option. Don’t delete a company VPN that’s still in use.

Keychain prompts: password, Allow, and Always Allow

A client may store subscription credentials, access tokens, or other sensitive settings in Keychain; exactly what it stores depends on the implementation. Starting the core, opening the window, and accessing Keychain are separate events. When a prompt appears, check which process wants access to which item rather than assuming it’s related to whether the client is open.

What the three buttons authorize

• Deny: Blocks this access request. The related feature may be unable to read the credential, but the Keychain item usually remains intact.
• Allow: Approves the current request, which is useful for checking whether the feature works again. You may be asked again next time.
• Always Allow: Saves permission for this app to access the item. Use this only after confirming the app’s identity and the item’s purpose; never grant it to an unknown process.

Your login Keychain password is usually the same as your current macOS login password, but not always. If an administrator reset your account password or you restored an older Keychain during migration, the Keychain may still use its previous password. If your current password keeps failing, check for this before trying it repeatedly.

Find the specific item in Keychain Access

1. Press Command + Space, search for “Keychain Access,” and open it. The newer Passwords app doesn’t replace all Keychain management features.
2. Select the “login” Keychain and search for the item named in the prompt. Check only that entry; don’t select and delete everything.
3. Open the item’s details and review its type and access control. Editing options vary by item type.
4. If you confirm the item contains an outdated credential saved by the client, sign in again or update the credential in the client first. Before deleting a single item, make sure you can obtain the account details again.

A Keychain prompt after a client update doesn’t necessarily mean the password is wrong. A changed app path, signing identity, or access control can trigger a new approval request. Check the update source and process name in the prompt before deciding whether to grant access again.

Verify the connection after granting permissions

Once permissions are sorted out, test in this order: core listener → system proxy → TUN. Don’t change DNS, rules, and proxy ports all at once, or it’ll be hard to tell what fixed the issue. Save your original configuration and note the log time for each step.

Step 1: Check that the core is listening on its port

This example assumes the client is configured with mixed-port: 7890. Port 7890 is only an example—not a default for every client. If your client shows a different port, update the command accordingly. Open Terminal and run:

lsof -nP -iTCP:7890 -sTCP:LISTEN

If you get output, confirm the listening process belongs to the client you’re troubleshooting. If there’s no output, check whether the core started, the configuration parsed successfully, and the client uses a different port. Administrator approval alone doesn’t mean the core is listening.

Step 2: Test the proxy directly, then check system settings

curl -I --connect-timeout 10 --max-time 20 \
  --proxy http://127.0.0.1:7890 https://example.com/

scutil --proxy

The first command explicitly uses the local proxy, with a 10-second connection timeout and a 20-second total timeout. This helps distinguish a proxy problem from a system proxy settings issue. An HTTP response means the request received a response; check its status code, the client’s connection log, and the matched policy to determine the result.

The second command shows the system proxy status. For a standard HTTP/HTTPS proxy, check that HTTPEnable, HTTPSEnable, the server, and the port match the client settings. For PAC, check the automatic proxy fields. TUN doesn’t require these switches to be set to 1, so they can’t be used to diagnose a TUN failure.

Step 3: Enable TUN on its own and check the logs

• Make sure the helper or required extension is ready before enabling TUN.
• Check the logs for virtual interface, route, or DNS initialization failures—not just the switch’s color.
• Confirm that regular web traffic and sites that should use the proxy match the expected rules. In Rule mode, different requests can use different routes.
• Quit the client, then check the network and system proxy status again to make sure no proxy setting still points to a stopped port.

Quick checks for common problems

No prompt appears after you denied permission

First identify which type of request you denied. Reinstall the helper from the client; check the extension’s status in System Settings; or repeat the action that needs Keychain credentials. Reimporting a subscription isn’t a universal permission fix—subscription contents can’t change macOS authorization.

System proxy works, but TUN disconnects the network

Switch back to the working system proxy first, then check TUN logs, conflicts with other VPNs, and DNS settings. A working system proxy shows that part of the route is available; it doesn’t prove TUN has the required routes or permissions. Keep a way to restore your settings, and don’t download repair tools while your network is down.

Asked for a password every time the client starts

First check whether the prompt is for system authentication or Keychain access. For system authentication, check that the helper installed successfully and isn’t being updated on every launch. For Keychain, check the item’s access controls, whether the app launches from a consistent location, and whether multiple copies of the client remain. Don’t save an administrator password in a script to bypass authentication.

What to include when reporting an issue

• Your full macOS version, available under About This Mac, and whether your Mac uses Apple Silicon or Intel.
• The client version and core version, listed separately.
• The steps that trigger the issue, the exact prompt text, and relevant logs from the seconds before and after it occurs.
• Whether you’re using system proxy or TUN, the actual listening port, and whether another network-routing tool is running.

Before sharing screenshots or logs, redact the full subscription URL, account tokens, proxy passwords, and other personal information. Evidence relevant to the permission type is more useful than repeated reinstalls. Change one setting at a time so you can tell whether the fix worked.