Install Clash on macOS: Network Extensions, VPN Authorization, and Keychain Prompts

Check the chip architecture and client type before installing

On macOS, “Clash” may refer to a graphical client or a command-line core such as mihomo. The graphical client handles subscription imports, proxy-group selection, the system-proxy toggle, and log viewing; the core reads the configuration, listens on local ports, and applies rules. When you install a graphical client, any request to authorize a network extension, VPN configuration, or helper tool comes from the client’s traffic-interception method. It does not mean the subscription service has received the same system access.

Apple Silicon and Intel builds are not interchangeable

Macs with M1, M2, M3, or M4 chips use Apple Silicon. Their installers are commonly labeled arm64, aarch64, or Apple Silicon. Older Intel Macs use builds labeled x64, x86_64, or Intel. Click the Apple menu in the upper-left corner, open “About This Mac,” and check the “Chip” or “Processor” field. You can also run this command in Terminal:

uname -m

• Output arm64: choose the macOS ARM64 or Apple Silicon build.
• Output x86_64: choose the macOS x64 or Intel build.
• Apple Silicon Macs can sometimes run Intel apps through Rosetta 2, but a native ARM64 build is usually the better choice for long-term use.

The download page should also distinguish application installers from standalone cores. A typical .dmg file opens as a disk image; drag the app into Applications. A .pkg file runs through the system installer. An archive that extracts to a single executable is usually a core, so do not expect to find a menu-bar icon using the steps for a graphical client.

Move the app to Applications before launching it for the first time

1. Open the downloaded .dmg.
2. Drag the client icon into the Applications folder. Do not keep running it from the disk image or Downloads.
3. Eject the disk image, then launch the client from Applications in Finder.
4. After the first launch, check whether the client appears in the menu bar, Dock, or main window.

Keeping the app in Applications prevents path changes after upgrades and helps macOS associate login items, helper tools, and network extensions with their host app. Running directly from a read-only disk image may prevent the client from writing update files. Launching from a randomly extracted folder can also leave multiple copies with the same name but different versions.

Handle “Cannot Open” and developer security alerts

macOS installation security alerts are mainly triggered by Gatekeeper, app signing, notarization status, and download quarantine attributes. Different messages require different responses. Do not treat “cannot verify the developer,” “the app is damaged,” and “the app needs to be updated” as the same problem.

Use a one-time override for “cannot verify the developer”

If you have confirmed that the installer came from the selected client’s upstream release page, locate the app in Finder, hold Control while clicking it, choose “Open,” and click “Open” again in the confirmation dialog. On macOS 13 and later, you can also open System Settings → Privacy & Security, find the recently blocked app in the Security section, and choose “Open Anyway.” This is a one-time confirmation for that app; it does not change the Mac’s global security level.

macOS 12 and earlier generally use System Preferences → Security & Privacy → General. The menu names differ, but the principle is the same: launch the app once so macOS records the block, then verify its name and source in the security settings.

“The app is damaged” is not the same as an ordinary unidentified-developer warning

“The app is damaged and can’t be opened” may indicate an incomplete download, an invalid signing state, a modified app, or an older build that is incompatible with the current macOS version. Delete the current copy, download a build matching your chip architecture, and make sure the app has been fully copied into Applications. If the upstream release notes specify a minimum macOS version, check that your system meets it.

For further checks, use Terminal to inspect the app’s signature and macOS assessment result. The example below uses Clash Verge Rev installed in the standard location; these commands only read status:

codesign -dv --verbose=4 "/Applications/Clash Verge Rev.app" 2>&1
spctl --assess --type execute --verbose=4 "/Applications/Clash Verge Rev.app"

The codesign output can show the identifier, signing authority, and runtime settings. spctl reports whether macOS accepts the app. If the app has a different name, drag the actual app from Finder into Terminal to insert its exact path. Do not use old forum commands to remove security attributes from every app.

How network extensions, VPN configurations, and system proxies differ

Common Clash traffic-interception methods include the system proxy and TUN. The system proxy mainly changes the HTTP, HTTPS, or SOCKS proxy settings for the current macOS network service. TUN uses a virtual network interface to handle a broader range of IP traffic. Whether a client requests a network extension, VPN configuration, or administrator authorization depends on how it implements TUN—not on proxy strategies such as Rule mode or Global mode.

Using only the system proxy usually does not require a VPN configuration

When the client enables the system proxy, it writes the proxy server into the current network service. The common local address is 127.0.0.1, and the common mixed listening port is 7890. Older configurations may instead use HTTP port 7890 and SOCKS port 7891. These values are not universal; use the client’s Settings → Port Settings, runtime logs, or the current configuration’s mixed-port, port, and socks-port as the source of truth.

The system proxy works well with apps that follow macOS network proxy settings, but curl in Terminal, package managers, development tools, and some cross-platform apps may ignore them. If a browser works while Terminal fails, that does not mean the network extension is broken. Check the app’s own proxy settings or set explicit HTTP_PROXY, HTTPS_PROXY, and ALL_PROXY variables for the current Terminal session.

Enabling TUN may show VPN or network-content-filtering prompts

When a client uses Apple Network Extension to create a TUN, macOS may say that the app wants to add a VPN configuration or ask to allow a network extension. After confirming that the app name matches the client you just operated, you can allow it. Once authorization is complete, macOS 13 through 15 usually show a client-managed item under System Settings → Network → VPN & Filters.

Some clients use a privileged helper tool to create a virtual interface or maintain routing tables. The first time the service is installed, macOS may ask for an administrator password or Touch ID. This prompt grants system-level authorization; it is not a subscription login. Enter the credentials for the Mac’s current administrator account. The credentials are handled by the macOS authentication dialog—do not enter a subscription URL, proxy-node password, or website account.

How to tell whether a Keychain prompt is trustworthy

macOS has two password dialogs that are easy to confuse. The first is system administrator authentication, usually showing a username, password field, or Touch ID. It is used to install helper tools, change network settings, or start privileged services. The second is a Keychain Access dialog, which typically names the app requesting access to a specific Keychain item and offers options such as “Deny,” “Allow,” or “Always Allow.”

Verify the requester, Keychain item, and triggering action first

1. Check whether the prompt appeared immediately after installing a service, enabling TUN, configuring launch at login, or saving credentials.
2. Check whether the requesting app name matches the client you launched.
3. Check whether the Keychain item name corresponds to the client, a helper tool, or configured authentication information.
4. If the prompt keeps appearing while the client is not running, choose “Deny” first, then inspect login items, remnants of older versions, and Keychain items.

“Always Allow” means that apps with the same signing identity will be asked less often when accessing that item in the future. Use it only after confirming the details and establishing that the running client genuinely depends on the item. If the purpose is unclear, choose one-time “Allow” and see whether the client recovers; this is easier to troubleshoot than granting permanent access immediately.

Repeated prompts after an upgrade may involve signing changes or old items

After a client upgrade, app-name change, signing-identity change, or an overwrite installation from another release channel, Keychain may treat the new version as a different requester. Quit every client with that name and make sure Applications contains only the copy you intend to use, then launch it again. Open Keychain Access, search for the client name in the “login” keychain, and inspect the item’s creation date and Access Control list.

Do not delete the entire login keychain at once. If you have confirmed that an item belongs only to an uninstalled older client, record its name first, delete only that item, and let the current client recreate it. If the client asks for proxy credentials or helper-service installation again, follow the current version’s setup process.

Complete initial setup and authorization in order

Turning on several switches at once makes problems harder to isolate. A safer sequence is to verify that the client and core start, import the configuration, verify the local ports, and then enable the system proxy or TUN one at a time.

Step 1: Start the client and verify the core status

After opening the client, go to Settings or Settings → Core Settings and check whether the core is ready. Different clients may place this status on the home page, log page, or service-management page. If the log continues to show configuration parsing errors, fix the configuration first rather than repeating authorization. Common issues include incorrect YAML indentation, a policy group referencing a nonexistent proxy, a rule pointing to an undefined PROXY policy group, and a port already occupied by another process.

You can use Terminal to check whether common ports are listening:

lsof -nP -iTCP:7890 -sTCP:LISTEN
lsof -nP -iTCP:7891 -sTCP:LISTEN
lsof -nP -iTCP:9090 -sTCP:LISTEN

7890 and 7891 are commonly used for proxy listeners, while 9090 is often configured as an external control interface. The actual ports must come from the current configuration. If an old client is using the same port, fully quit it instead of changing several configuration files at random.

Step 2: Import the subscription and select the active configuration

1. Open the client’s Configuration or Subscription page.
2. Import the configuration using the URL provided by the subscription service.
3. Wait for the download to finish, then check the update time and configuration name.
4. Set the newly imported configuration as the active configuration.
5. Open Proxy or Policy Groups and choose an available node for any group that requires manual selection.

A successful import only means that the client obtained the configuration file; it does not mean system traffic is already passing through Clash. You must also confirm that the core loaded successfully, that policy groups have selectable options, and that at least one interception method—system proxy or TUN—is enabled. Subscription updates may overwrite direct edits inside the subscription; use the client’s supported override, merge, or script mechanism for lasting custom rules.

Step 3: Test the system proxy before deciding whether to enable TUN

After enabling the client’s system proxy, run scutil --proxy to view the current macOS proxy status. The HTTP, HTTPS, or SOCKS switches in the output should match the client settings. If the client says the proxy is enabled but the system output is unchanged, check whether the active network service changed, whether the client has authorization to modify network settings, and whether another proxy tool is overwriting them.

scutil --proxy
curl --proxy http://127.0.0.1:7890 https://example.org/

The second command explicitly sends the request to local port 7890. This helps distinguish “the core and node work” from “Terminal is not using the system proxy.” If the explicit proxy succeeds but curl https://example.org/ fails directly, focus on Terminal’s proxy environment instead of reinstalling the network extension.

Consider TUN only when you need to handle apps that ignore the system proxy, UDP traffic, or a broader range of application traffic. If enabling it produces a VPN configuration or administrator-authentication prompt, verify the app name and triggering action as described above. Once TUN is established, the logs usually show a virtual interface, route, or DNS module starting; the exact interface name depends on the client and core implementation.

Layered troubleshooting after authorization still cannot connect

The system proxy is enabled, but the browser has no traffic

• Check System Settings → Network → the active Wi-Fi or Ethernet connection → Details → Proxies. Verify that the server is 127.0.0.1 and that the port matches the client.
• Confirm that the client core is running, rather than only the interface remaining in the menu bar.
• Check whether the browser has a separate proxy-management extension or its own proxy configuration.
• Review rule-hit logs to confirm that the request is not going to REJECT and that the target policy group has an available node.
• Temporarily quit other network tools that modify the system proxy so multiple programs do not overwrite the settings in turn.

The network drops immediately after enabling TUN

Turn off TUN first and confirm that basic connectivity returns, then inspect the first error in the client log. Common causes include failure to create the virtual interface, route conflicts, DNS listener conflicts, and a helper service that did not start. If System Settings contains VPN configurations left by several older clients, disable unused ones first, but do not bulk-delete corporate VPNs, remote-work tools, or other network extensions before confirming ownership.

Also check whether the DNS section of the configuration is compatible with the current core version. mihomo’s supported DNS options evolve over time, and an older Clash configuration may not migrate unchanged. For “field does not exist,” “invalid type,” or listening-address conflicts, adjust the configuration according to the documentation for the core bundled with the current client instead of blaming macOS VPN authorization.

The proxy toggle stops working after a restart

Open System Settings → General → Login Items & Extensions and check whether the client is allowed to open at login and whether its related background items remain enabled. Some clients provide three separate options: launch at startup, launch silently, and set the system proxy after launch. Enabling only the first usually starts the interface without guaranteeing automatic traffic interception.

If the client requires a privileged service, also check its Settings → Service Mode or TUN Settings for the service status. If the service and client versions no longer match after an upgrade, use the client’s “Reinstall Service” or “Repair Service” function first, and watch for the macOS administrator-authentication dialog that follows.

The system still has a proxy after quitting the client

An abnormal exit may not give the client time to restore the system proxy. Reopen the same client, turn the system proxy on and off once, and it will usually complete its cleanup. You can also open System Settings → Network → Current network → Details → Proxies and check the HTTP, HTTPS, and SOCKS entries to ensure unwanted switches are off.

Clean up permissions when upgrading, switching clients, or uninstalling

Before upgrading the same client in place, quit the old version and confirm that its menu-bar icon has disappeared. After installation, verify the version number, core version, active configuration, and system-proxy status. If the new version requests network-extension or helper-service authorization again on first launch, check its signature and source, then allow it as needed; a renewed permission prompt does not mean the subscription configuration was lost.

Do not let multiple clients control the system network at the same time

When switching between ClashX Meta, Clash Verge Rev, FlClash, and other clients, first export any configuration you need to keep or record the subscription entry point. In the old client, turn off the system proxy, turn off TUN, and quit the app in that order. Start the new client and verify its local ports before enabling one interception method. Two clients listening on 7890 or both modifying the system proxy can cause port conflicts and a mismatch between displayed status and actual settings.

Uninstalling means more than dragging the app to the Trash

1. Turn off the system proxy and TUN in the client.
2. If the client offers “Uninstall Service” or “Remove Helper Tool,” run it from the Settings page first.
3. Quit the client and confirm that no process with the same name is still running in Activity Monitor.
4. In System Settings → Network → VPN & Filters, check for configurations created by the client.
5. In System Settings → General → Login Items & Extensions, check login items and background items.
6. Only after confirming that you no longer need the local configuration should you delete the app and its dedicated configuration directory.

If you are only upgrading or troubleshooting temporarily, do not delete all configuration first. Keep one working configuration and recent logs so you can determine whether the problem is in the app upgrade, core loading, system permissions, or subscription content. After installation, the minimum verification loop should confirm that the app starts, the core reports no configuration errors, a local port is listening, an explicit proxy request succeeds, only the intended system-proxy or TUN path is enabled, and the system network recovers after quitting.