ClashX on Apple Silicon Mac: Install and Setup Guide

Check compatibility before downloading

ClashX is a macOS graphical client that manages a Clash-compatible core, local proxy ports, configuration files, and the system proxy switch. On an Apple Silicon Mac, the first decision is not which configuration to import, but which application build your Mac can run reliably. Apple silicon includes M1, M2, M3, and M4 families, while older Macs use Intel processors. The installer architecture, macOS security policy, and the core bundled with the client all affect the first launch.

Open the Apple menu, choose About This Mac, and check the hardware description. If the window shows a Chip field containing Apple M1, M2, M3, or M4, your Mac uses the arm64 architecture. If it shows a Processor field containing Intel, it uses x86_64. Choose an Apple silicon build when one is available. An Intel build can sometimes run through Rosetta 2, but native arm64 software generally starts faster and avoids an additional translation layer.

ClashX and its bundled core should also be treated as separate components. The client provides the menu bar interface and changes macOS proxy settings; the core reads YAML, listens on local ports, resolves domains, matches rules, and creates outbound connections. A ClashX window opening successfully does not prove that the imported configuration is compatible or that the core has started without errors.

Download and install ClashX

Download the macOS package that matches your Mac. A DMG file is common for macOS applications, although some distributions provide a ZIP archive. If the download page lists arm64, Apple Silicon, or universal, select that package for an M-series Mac. Avoid choosing an Intel-only archive unless the publisher documents that Rosetta is supported and no native build is available.

After the download completes, compare the file name and approximate size with the information published by the distributor. A very small file, a file with an unexpected extension, or a download that redirects to an HTML page should not be opened as an installer. If a checksum is provided, calculate the checksum locally and compare it before mounting the disk image.

shasum -a 256 ~/Downloads/ClashX.dmg

The command does not install anything. It only prints a SHA-256 value that you can compare with the value supplied by the download source. Never paste a private subscription URL into a checksum service or public support forum. Subscription links commonly contain access tokens and should be handled like passwords.

Copy the application into Applications

1. Open the downloaded DMG file in Finder.
2. Drag the ClashX application into the Applications folder.
3. Wait for the copy operation to finish before ejecting the disk image.
4. Eject the DMG, then launch ClashX from Applications or Launchpad.
5. Keep only one ClashX process active while completing the first setup.

Running the application directly from Downloads or from inside the mounted DMG is not a good long-term arrangement. A fixed path makes updates, login-item registration, Keychain access, and macOS permission decisions more predictable. It also prevents the common situation where an old copy in Applications and a newer copy in Downloads both appear in the menu bar.

If another Clash client is already running, turn off its system proxy and quit it before starting ClashX. Two clients may attempt to control the same macOS proxy settings, and two cores may attempt to listen on the same local port. Typical ports include 7890 for a mixed HTTP and SOCKS connection and 9090 for an external controller, but the actual values depend on the configuration.

Handle macOS security prompts

The first launch may show a warning that the developer cannot be verified, that macOS cannot check the application for malicious software, or that the application was moved to the Trash. These messages concern Gatekeeper and code signing. They are different from a request to install a helper component, create a VPN configuration, or access an item in Keychain.

For a normal first launch, find ClashX in the Applications folder, hold the Control key, click the icon, and select Open. macOS may display the same warning once more, but the dialog should provide an explicit option to open the application. If the option is absent, open System Settings → Privacy & Security and look for a recent message about the blocked application.

Do not immediately disable Gatekeeper or run broad commands copied from an unverified post. If macOS reports that an application is damaged, first delete the current copy, download it again from the intended source, and confirm that the DMG mounted correctly. A genuine signing problem, an incomplete transfer, and a quarantine issue can produce similar wording, so the download source must be established before changing security settings.

Complete the first launch step by step

Once ClashX opens, look for its icon in the macOS menu bar. Depending on the build, the application may not display a large main window; many controls are available from the menu bar. Before importing a subscription, confirm that the client is the copy installed in Applications and that no other Clash client is currently changing the system proxy.

1. Open the menu bar menu. Confirm that ClashX is running and inspect the current status. If the icon is missing, check whether macOS has hidden it in the menu bar or whether the application exited immediately.
2. Open the configuration or profile menu. Choose the option for adding a profile from a URL when your provider gives you a subscription link. Use the complete HTTPS URL, including its token and query parameters.
3. Name the profile clearly. Use a local name such as Daily profile or Home rules. This name is only for identification and does not change the remote configuration.
4. Wait for the download to finish. A successful HTTP response is not enough; ClashX must also parse the returned content as a compatible configuration.
5. Select the imported profile. Make sure the active check mark points to the newly downloaded configuration rather than an empty or outdated local file.
6. Choose a proxy mode. Start with Rule mode when the configuration contains rules. Use Global only for a deliberate all-traffic test, and use Direct when you need to compare behavior without proxy routing.
7. Enable the system proxy. Turn on the system proxy only after a profile is active and the core has started. macOS applications that respect system proxy settings should then use the local HTTP or SOCKS endpoint.
8. Test one ordinary website. Check the core log and the browser result together. A page loading does not necessarily prove that every rule or policy group is correct.

A profile may contain fields that the bundled core does not understand. Common symptoms include an import error, missing proxy nodes, an empty policy group, or a log entry stating that a field or proxy type is unsupported. Older ClashX builds may not understand newer mihomo-specific fields or protocols such as Hysteria2, TUIC, VLESS variants, advanced rule providers, or newer DNS options.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

These fields illustrate a common local arrangement: a mixed proxy port on loopback, LAN access disabled, rule-based routing, informational logs, and a controller available only to the local Mac. Do not copy them into a remote subscription without understanding how the provider generates the rest of the configuration. In particular, enabling allow-lan: true can expose the proxy to other devices on the network and should be paired with deliberate access controls.

Confirm the local proxy before troubleshooting the browser

When the system proxy is enabled, inspect macOS network settings and ClashX’s current port at the same time. The system HTTP and HTTPS proxy address is often 127.0.0.1, but the port may not be 7890. If the client uses a SOCKS-only port, entering that port in an HTTP proxy field can produce connection failures even though the core is running.

If a browser shows a proxy connection error, first disable the system proxy and confirm that the browser works directly. Then enable the proxy again and test a single site. This separates a general network outage from a local port, rule, DNS, or policy-group problem. Avoid changing DNS, TUN, the core, and the subscription all at once because the resulting behavior will be difficult to interpret.

Choose system proxy or TUN deliberately

System proxy mode is the simplest starting point on an Apple Silicon Mac. It changes macOS network proxy settings so applications that honor those settings send HTTP, HTTPS, or SOCKS traffic to the local ClashX port. Web browsers and many developer tools support this arrangement, but some games, background services, command-line programs, and applications with their own network stack may ignore it.

TUN mode creates a virtual network interface and routes a broader range of traffic through the core. It can help when software does not read the system proxy, but it also adds DNS handling, route management, and macOS network extension permissions. A TUN connection can appear to be enabled while traffic still fails because the core cannot resolve domains, a route conflicts with another VPN, or the configuration uses unsupported DNS fields.

Before enabling TUN, turn off other VPN applications and confirm that the current ClashX build actually includes a compatible TUN implementation. Approve a network extension only when the prompt names the expected application. After enabling it, inspect the core log, DNS result, and connection list rather than relying only on the menu bar icon.

Troubleshoot common installation issues

ClashX opens and then quits

Check whether the build matches the Mac architecture and whether another copy is being launched from a different path. Remove duplicate copies, download the correct arm64 or universal package, and start it from Applications. If the application still exits, inspect the macOS crash report and the client log if available. An incompatible embedded core, an outdated macOS API, or an invalid configuration loaded at startup can all cause an immediate exit.

The subscription downloads but cannot be imported

Open the subscription URL only in a controlled manner and check whether the response is actually a Clash configuration. An HTML login page, a CAPTCHA, a JSON error, or a provider notice is not valid YAML for the client. Status codes such as 401, 403, 404, and 429 usually indicate an account, access, URL, or request-frequency problem rather than a macOS installation problem.

The profile imports but no websites load

Check the selected policy group, the core log, and the local port. A profile can parse correctly while every policy group contains unavailable nodes. Confirm that the selected node passes a test, then compare rule mode with a short global-mode test. If global mode works but rule mode does not, inspect the rules and rule-provider updates. If neither works, check DNS, the outbound protocol, and whether the provider still supports the core bundled with ClashX.

The system proxy cannot be turned off

Quit ClashX and check macOS network settings manually. An old client may have left a proxy address such as 127.0.0.1:7890 enabled after its process stopped. Clear the HTTP, HTTPS, and SOCKS proxy entries if they point to a closed local port. Then restart the network application or reconnect the current network service and test again.

Keychain or administrator prompts repeat

Repeated prompts can occur after replacing the application, changing its signing identity, moving it between folders, or enabling a helper component. Keep the application in Applications, confirm that the prompt names the expected program, and remove stale entries only after identifying them in Keychain Access. If the request appears every time and the app was obtained from an uncertain source, stop and reinstall a verified copy rather than approving prompts repeatedly.

Frequently asked questions