Clash for Mac Setup Guide

Before You Begin: Check Your Client and Configuration Source

Open About This Mac from the Apple menu. If it lists a chip with an Apple family name, choose the Apple silicon installer. If it lists an Intel processor, choose the Intel installer. The installer must also support your version of macOS. If you haven’t installed a client yet, choose one from the Mac downloads. Open the disk image, drag the app to Applications as prompted, eject the image, then launch the app from Applications. Avoid running it long-term from Downloads or the disk image.

When you first open the app, macOS may ask you to confirm its source. Continue only if you trust the source and the app is the one you expected. If macOS blocks it, check the specific reason under System Settings → Privacy & Security. Don’t disable macOS security protections or ignore malware warnings just to follow this guide. You can allow or deny notification access based on your preferences; it isn’t required for browser proxying.

This guide assumes you already have a valid Clash- or mihomo-compatible subscription link, or a local YAML configuration file. Installing a client doesn’t create nodes, accounts, or subscriptions. Subscription links often contain server details and access credentials, so protect them like account information. Don’t share them in public screenshots, chat logs, or online conversion tools. Import the configuration first, but leave the system proxy and TUN off so configuration issues aren’t confused with system-level routing issues.

1. Import a Subscription and Enable the Configuration

Open the client’s main window and find Subscription or Configuration in the sidebar. Click Add, Import, or the plus button, then choose import from URL. If prompted for a name, enter one that’s easy to recognize locally. Paste the full subscription link from your provider and click Confirm or Download. Check for extra spaces at either end, links truncated by a messaging app, or missing URL parameters. Don’t mistake a website login link or account dashboard URL for a subscription link.

During import, the client downloads and parses the remote file. When it succeeds, the configuration page usually shows a new card or list entry. Select it as the active configuration. Some clients enable it automatically; others require you to click Use, Activate, or a selection icon. Seeing a configuration in the list only means it’s been saved—it doesn’t confirm the core is using it. Open the Proxies page and make sure the configuration’s policy groups and outbounds are visible.

To use a local file, choose Import from File on the same page and select a configuration with the .yaml or .yml extension. Some clients copy the file; others keep a reference to it, so check the client’s documentation before editing it later. Importing a file doesn’t automatically provide remote updates. If the configuration references external rules or proxy providers, it may still need an internet connection to download them the first time. A local file doesn’t mean all its dependencies are available.

If you see a format error, first confirm that the subscription explicitly supports Clash or mihomo. A string of encoded text, a single protocol link, or a JSON file for another core may not work in a YAML configuration importer. Ask the configuration provider for a compatible format rather than trying multiple conversion tools. A subscription link can return a login page, an expiration notice, or an access error; a successful download doesn’t make any of those a valid configuration. Check the client log for error details, but hide URL parameters, account details, and server credentials before sharing it.

If the download fails, first check that your Mac can reach regular websites without a proxy, then try updating once more. Don’t repeatedly enable an unfinished system proxy to fix a subscription download; requests may be sent to a local port that isn’t ready to work. Continue once the subscription has loaded and its policy groups are visible. You can set an automatic update schedule later. For now, make sure manual updates and activation both work. For more on configuration formats and cores, see the protocol guide.

2. Choose Rule Mode and a Policy Group

Open the Proxies page and look for Outbound Mode or Running Mode. Choose Rule for your first setup. In rule mode, each request follows the rules in the active configuration and may be proxied, sent directly, or rejected. This setting doesn’t automatically identify the purpose of every website; the result depends on the rules in your subscription. If the page is still blank, go back and confirm the configuration is active instead of switching straight to Global mode.

Next, review the policy groups. A configuration may include groups for manual selection, automatic selection, or fallback. Group names are set by the configuration author, so they vary between subscriptions. In groups that require manual selection, choose an available outbound. If an option points to another policy group, check that group’s selection too. Leave automatic groups as configured; you don’t need to switch every group to manual mode. Availability tests, if offered, can help with troubleshooting, but one successful test doesn’t guarantee that every site or protocol will work.

Keep “policy group name,” “option within a group,” and “running mode” distinct. A group named “Auto” may not be used by the active rules, and selecting a node doesn’t mean all traffic will use it. DIRECT usually means a direct connection; REJECT usually means the connection is blocked. Neither is a remote proxy server. For everyday use, follow your subscription provider’s guidance to choose the default outbound group, then check connection records to see where requests are going.

Global mode typically sends connections handled by the core through a global policy. It can be useful for a brief comparison when you know what you’re testing, but it doesn’t take over every app on your Mac. Direct mode typically sends connections handled by the core straight out, but it doesn’t turn off the macOS system proxy. There’s no need to try every mode when getting started; leave Rule selected and note your current choice. For more on policy group references, see the glossary. For now, finish a basic setup you can reproduce.

3. Start the Core and Enable the System Proxy

Once the configuration and policy are set, check the core status on the client’s home or status screen. Some clients start the core automatically; others require you to click Start or Connect. If you see an error such as a port conflict or configuration load failure, fix it before routing system traffic through the client. A menu bar icon alone doesn’t confirm that the core is listening on a local proxy port. Pause other proxy clients too, so they don’t overwrite each other’s macOS settings.

Go to Settings → General or Settings → Network and turn on Set as System Proxy. Some clients offer the same switch in the menu bar. This sends requests from apps that follow macOS system proxy settings to the local client, where the core handles them according to its rules. If macOS asks to install or authorize a helper, check which app is requesting access and why before confirming. If authorization fails, follow the client’s specific instructions rather than repeatedly entering your system password without knowing the reason.

For your first test, leave Enhanced Mode (TUN) off and don’t enable Allow LAN. TUN involves a virtual network interface, routing, and additional permissions. Allow LAN lets other devices connect to your local proxy. Neither is needed to test a browser on your Mac. Start with a straightforward system proxy connection. If terminal tools, games, or other apps don’t follow the system proxy, learn about TUN later and enable it only if needed instead of switching on every network option at once.

Use the local port shown in the client. A common example for a mixed port is 7890, but clients and configurations may use other values; don’t change your settings to match the example. The client should normally fill in the system proxy settings automatically. If you configured them manually before, check for leftover addresses under System Settings → Network → Current Network Service → Details → Proxies. On a managed work device, follow your organization’s policies and don’t override required settings.

Once enabled, leave the client running. Closing the main window may only hide it; whether it stays in the menu bar depends on the client’s settings. Choosing Quit may stop the core, so don’t treat the two actions as equivalent. For now, skip terminal tests and browser-specific proxy extensions. Use a browser that follows system proxy settings for the next step. To route apps that don’t, first complete the basic test, then read the protocol guide’s section on networking and cores. This avoids troubleshooting two proxy methods at once.

4. Test Your Connection and Verify the Rules

Open Safari or another browser that follows system proxy settings. Start a new tab and visit a site you know works to confirm your basic connection is intact. Then visit the site you want to test through the proxy. Don’t rely on the client switch’s color or whether a single page loads. The browser may use cached content, and the website itself may be temporarily unavailable. Check both the actual request and how the client handled it.

Leave the client’s Connections page open, reload the test page, and look for the corresponding domain or destination address. If the interface shows rules, policy chains, or outbound details, check that they match your expectations: requests meant to go direct should be direct, and requests that need a proxy should use the selected policy group. Short-lived connections may disappear quickly; check the logs or send the request again. Log detail varies between clients, so a missing domain entry doesn’t automatically mean the request bypassed the core.

If the request appears but the site won’t load, it may have reached the core. Next, check whether the selected outbound works, the subscription is valid, and a rule hasn’t rejected the request or assigned it to another policy. Change one thing at a time—for example, select a different outbound in the same group, then test again. Don’t change the port, DNS, mode, and subscription all at once, or you won’t know which change mattered. There’s usually no need to delete the entire configuration; existing records can help narrow down the issue.

If the browser request doesn’t appear at all, check that the system proxy is still enabled, the browser has no separate proxy extension or custom proxy setting, and the core is running. A stale port in System Settings or another client taking over the proxy can prevent requests from reaching the current app. Try turning the system proxy off and back on so the client can reapply its settings. If it still fails, check in this order: active configuration, core status, local port, and system proxy. Find common symptoms and fixes in the Help Center.

If your browser works but terminal commands still fail, that doesn’t mean the whole setup is broken. Many command-line tools don’t use the macOS system proxy and need their own proxy options or environment variables. Supported protocols vary too. For the initial test, it’s enough for the browser and connection records to agree; handle terminal access separately. Likewise, checking your public IP only confirms the route used for that specific lookup, not that every app uses the same outbound. After testing, keep Rule mode and note the active configuration and policy group so you can compare them after an update.

When You’re Done: Turn Off the Proxy and Restore Network Access

Before quitting the client, turn off System Proxy from the menu bar or settings. If you enabled TUN, turn that off too, then quit. This prevents your Mac from sending requests to a local port after the client stops. Some clients can restore settings automatically on quit, but it’s worth checking manually the first time. If you’re only closing the window and leaving the client running, you can keep the proxy enabled if needed; there’s no need to import the subscription again each time.

If all websites stop loading after the app quits unexpectedly, reopen the client and turn off System Proxy first. If it won’t start, open the proxy settings for your current network service and check whether they still point to a local loopback address and an old port. Remove only entries you can confirm were added by this client and are no longer in use. Don’t remove organization-managed proxies from a work device. Once regular internet access is restored, check the client logs to troubleshoot startup. There’s no need to reset your Mac’s entire network configuration as a first step.

For everyday use, you usually only need to do three things: confirm the subscription updated, check that the active policy suits your needs, and enable the system proxy when needed. Subscription updates can change group names and default selections. If access changes after an update, check the policy group first. That’s the basic setup complete. For in-depth guidance on protocol choices, core compatibility, and subscription formats, see the protocol guide; you don’t need to change every advanced setting for everyday browsing.