Clash macOS Permissions: Network Extension and Keychain Prompts Explained

What macOS Permissions Control in Clash

A Clash graphical client on macOS typically consists of the interface, the Clash or mihomo core, a system proxy controller, and an optional TUN interception module. The prompts shown on first launch vary depending on the client’s implementation, macOS version, and enabled features. Standard rule-based proxying, the system proxy, and TUN mode do not require the same level of access.

When using only the system proxy, the client mainly points the current macOS network service’s HTTP, HTTPS, or SOCKS proxy to a local listening port. Browsers and apps that follow system proxy settings pass connections to the Clash core, which then uses rules to select a direct connection, proxy node, or another policy group. The client may need administrator authorization to install a helper service or change network settings, but it may not register a network extension.

After TUN mode is enabled, the client creates a virtual network interface and adjusts system routes so applications that ignore system proxy settings can also enter Clash. Some clients use Apple’s Network Extension framework, while others create the virtual interface through a privileged background service. As a result, different clients may show prompts such as “Allow Network Extension,” “Add VPN Configuration,” “Install Helper,” or an administrator account verification dialog for the same TUN feature.

Keychain stores or retrieves protected credentials. A client may save helper-service authorization data, proxy credentials, or other sensitive settings in the login Keychain. Distinguish a Keychain access prompt from a standard administrator verification dialog: the former usually mentions “Keychain” or a specific Keychain item, while the latter confirms a system-level change. The two should not be considered identical based solely on where the dialog appears.

Clash macOS First-Launch Setup Order

After installation, move the app to the “Applications” folder and launch it from there. Running it directly from the Downloads folder or a disk image can change the helper-service path, break automatic startup, and leave old components behind during upgrades. If macOS warns that the app was downloaded from the internet, verify its source before continuing.

1. Launch the client first, without enabling TUN.

   Wait until the interface shows that the core is running, then confirm that no local proxy port is already in use. Common ports are defined by port, socks-port, or mixed-port in the configuration; use the values in the active configuration.

2. Import a valid configuration or subscription.

   A subscription usually provides nodes, policy groups, and rules. After importing it, run one manual update, confirm there are no YAML parsing errors, and select an available node in the policy group. Network permissions only route traffic into the core; they cannot repair an expired node or a broken subscription.

3. Test the standard system proxy first.

   After enabling “System Proxy,” open a test page and watch the client’s connection log. If the log shows the domain, rule, and policy group, the app’s traffic has entered Clash. If the connection fails at this point, check the node and rules before granting additional system permissions.

4. Install service mode or enable TUN only when needed.

   Enable TUN only when you need to intercept traffic from command-line tools, games, virtual machines, or apps that ignore system proxy settings. When macOS displays a network extension, VPN configuration, or helper prompt, follow the steps shown by the client to complete authorization.

5. Restart the client and verify the switches.

   After the helper service installs successfully, quit the client completely and reopen it. Do not only close the main window, because a menu bar app may still be running in the background. After reopening, check that System Proxy, TUN, and the policy mode remain as expected.

How to Re-enable a Denied Network Extension

Selecting “Don’t Allow” when the network extension request first appears usually does not damage the Clash configuration, but the related TUN or VPN interception feature remains unavailable. The reauthorization path has changed across macOS versions, and labels may differ slightly, so use the search function in System Settings to locate it.

Find the extension status in System Settings

On newer versions of macOS, open “System Settings” and search for “network extension,” “VPN,” or “filter.” Common locations include “VPN & Filters” under “Network” and “Network Extensions” under “Login Items & Extensions” in “General.” If the current Clash client or its helper component appears in the list, enable the relevant item and return to the client to retry TUN.

Some versions show blocked system software or extensions at the bottom of “Privacy & Security.” This notice may appear only for a limited time after installation. After clicking Allow, macOS may request administrator verification or ask you to quit the app or restart macOS. Save your work before restarting and quit other programs normally.

The corresponding item is missing from System Settings

If the network extension list contains no related entry, the client may not have actually started registration, the app may still be on a disk image, the helper component may have failed to install, or the client may not use the Network Extension framework at all. Do not keep searching for a switch that does not exist. Work through the following steps in order:

1. Quit the client and use “Activity Monitor” to confirm that its related interface processes have ended.
2. Confirm that the app is in the “Applications” folder and that multiple versions are not being launched alternately.
3. Reopen the client, then turn TUN or service mode off and on in Settings to trigger the installation flow again.
4. If the client offers “Install Service,” “Repair Service,” or “Reinstall Helper,” use its built-in entry point.
5. If no prompt appears, inspect the client log to determine whether the issue is a permission error, a missing service, or a configuration field preventing the core from starting.

Some mihomo-based clients manage TUN through a privileged helper service rather than displaying a separate network extension in System Settings. In that case, administrator verification and service status matter more. Use the client documentation, the service startup result in the logs, and whether the system created the corresponding virtual interface as evidence. Do not equate a missing network extension entry with installation failure.

Handling Keychain Password Prompts and Repeated Dialogs

The macOS “login” Keychain is normally unlocked automatically when the user signs in. When a Clash client or its helper component reads a protected item, macOS may ask for access. The dialog usually shows the requesting app and Keychain item name, with options such as Deny, Allow Once, or Always Allow. Verify the app path and name before choosing the authorization scope.

If this is the first launch or the client was just upgraded, choose Allow Once to observe what happens next. Consider persistent authorization only when the source, signature, and purpose are clear and the item genuinely needs ongoing background access. The requested password is usually the current macOS user login password—not a subscription password, proxy-node password, or Apple Account password.

The login password is correct, but Keychain access is still denied

After changing the macOS login password, the old password for the login Keychain may not have been updated. System login can succeed while the old Keychain still expects the previous password. Open the built-in “Keychain Access” app, check whether the “login” Keychain is locked, and try unlocking it with the old login password. If you remember it, update the Keychain password in its settings so it matches the current account.

If the old password cannot be recovered, first assess the other account credentials stored in the Keychain. Resetting the default Keychain affects more applications and should not be the first response to a single Clash prompt. A safer approach is to identify items clearly associated with the current client, quit the client, back up essential information, then delete that item and restart so the client can recreate its authorization record.

Authorization is requested every time the client starts

• Check whether the app is launched from different paths each time, such as the Downloads folder, a disk image, and the “Applications” folder.
• Check whether the app signature or component name changed after a client upgrade; the old Keychain access control may no longer match the new program.
• Check whether the “login” Keychain unlocks automatically after sign-in and whether a security policy locks it prematurely.
• Avoid deleting the entire Keychain. Handle only client items whose name and ownership you can verify.
• If the dialog names an unfamiliar program, deny the request and inspect Login Items, background items, and currently running processes.

How to Troubleshoot a System Proxy That Has No Effect

A successful system proxy toggle does not mean the node is usable. The right order is to confirm that the proxy settings were written, the core is listening, traffic appears in the log, and the correct policy is selected before checking the remote node. Separating these stages prevents repeated permission-component installs just because one webpage failed to open.

Check the current macOS proxy status

In Terminal, use the built-in command below to inspect proxy settings in the dynamic store:

scutil --proxy

The enabled states and ports for HTTP, HTTPS, or SOCKS in the output should match the local listening details shown by the Clash client. If the client has enabled the system proxy but the command still reports it as disabled, turn the switch off, wait a few seconds, turn it on again, and check whether another network tool immediately overwrites the setting.

You can also inspect settings for a specific network service. The service may be named “Wi-Fi,” after a USB network adapter, or by an enterprise profile, so first confirm its exact name in Network settings:

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

Confirm that the local ports match the configuration

A Clash configuration may use separate HTTP and SOCKS ports, or expose a combined entry through mixed-port. If the system proxy points to an old port while the new configuration listens on another, the switch may look normal but connections will still be refused. Check the client overview and active configuration rather than only the raw subscription file, because the client may merge or override fields at runtime.

If the log shows no new connections at all, the problem is usually with writing the system proxy, an app bypassing the proxy, or the path before the local port. If connections appear but show timeout, continue by checking the node, DNS, and remote reachability. If the log explicitly shows DIRECT, review the rule order and current mode. Clash rules are matched from top to bottom and usually stop after the first match.

Restore the proxy after quitting the client

On a normal exit, the client usually removes the system proxy settings it wrote. If the app terminated unexpectedly and the browser cannot connect, restart the same client, turn the system proxy on and off, then quit normally. You can also manually disable HTTP, HTTPS, and SOCKS proxies in the details for the current network service in “System Settings.” Do not run bulk modification commands without knowing the service name and existing enterprise configuration.

TUN Mode Permissions, DNS, and Virtual Interfaces

TUN mode receives IP traffic through a virtual network interface and passes it to the Clash or mihomo core. It is useful for apps that ignore system proxy settings, but it is also more likely to conflict with other VPNs, virtual machine networks, container tools, and security filters. When a standard web proxy meets your needs, there is no reason to enable TUN simply to obtain “more complete” permissions.

After TUN is enabled, the client may request administrator access to install a daemon or ask to add a VPN configuration. Once authorized, macOS may show a VPN or filter item in Network settings, and the list of network interfaces in Terminal may include a utun interface. macOS itself and other apps can also create utun interfaces, so seeing the name alone does not prove that it belongs to Clash. Compare the state before and after enabling TUN and check the client log.

Common TUN fields in a mihomo configuration include enable, stack, auto-route, and auto-detect-interface. A graphical client may generate these fields automatically or override subscription values through interface switches. Before editing YAML, determine whether the client uses the raw subscription, an override configuration, or a runtime-merged configuration, so an update does not overwrite manual changes.

DNS is a key part of TUN troubleshooting. A domain must be resolved before the connection can be routed by domain or IP rules. If only domain access fails after enabling TUN while a known IP responds directly, check whether the Clash DNS module is running, whether the upstream DNS is reachable, and whether another VPN is forcing DNS interception. If the log shows a DNS loop or repeated query timeouts, temporarily quit other network interception tools and test Clash by itself.

Clash Still Cannot Connect After Permission Is Granted

System permissions are only one part of the local connection path. Even after the network extension is allowed and Keychain prompts stop, connections can still be affected by an expired subscription, unreachable nodes, an incorrect system clock, port conflicts, or rule settings. Check from the local system outward to the remote endpoint.

1. Check the core status.

   Confirm that the client does not report a stopped core, configuration parse failure, or repeated startup loop. YAML indentation errors, duplicate ports, and fields unsupported by the current core can all prevent it from running even after permissions are granted.

2. Update the subscription and check its timestamp.

   Update the configuration manually once and record the returned error. An expired subscription URL, intercepted network request, and malformed configuration require different fixes; repeatedly clicking Update will not change the type of error.

3. Test multiple nodes.

   Latency tests are only a reachability reference and do not fully represent connection quality. Test nodes from different regions and using different protocols, then check whether the log shows a connection timeout, handshake failure, or DNS failure.

4. Correct the system date and time zone.

   A clearly incorrect date, time, or time zone can cause TLS verification to fail. Open macOS Date & Time settings, enable automatic time setting, and confirm that the current time zone is correct.

5. Quit other network interception tools.

   Other VPNs, proxy clients, content filters, and enterprise security software may modify the default route or DNS. Quit them temporarily and test again, while following organizational requirements for security components on managed devices.

6. Review the current mode and policy group.

   Rule mode depends on the rule order and policy selection in the configuration; Global mode usually sends traffic to the selected global policy; Direct mode does not use proxy nodes. With the wrong mode selected, the result can differ from expectations even when permissions and nodes are working.

TUN Suddenly Stops Working After a Client Upgrade

An upgrade may replace the graphical app, core, and helper service at the same time. Fully quit old processes, then launch the new version from the “Applications” folder. If the interface reports a service-version mismatch, use the client’s uninstall or repair-service entry point to reinstall the helper component. After administrator verification, restart the client and check that the network extension or VPN item is still enabled.

Do not launch the old and new versions repeatedly from different folders. System authorization may be tied to the app identifier, signature, and component path, making Keychain access and background-service state harder to diagnose when versions are alternated. After confirming the new configuration works, remove old components using the client’s recommended method.

Diagnostic Information Worth Sharing

When reporting an issue to the client maintainer, provide the macOS major version, Mac chip type, client version, core type, reproduction steps, and sanitized log excerpts. Do not publish subscription URLs, node server addresses, authentication details, or local account information. Logs should include context before and after the error, not just a single “connection failed” line.