Clash for Apple Setup Guide

Step 1: Import a Subscription and Activate the Configuration

At this stage, the goal is to see available policy groups—not to connect yet. Open the client and go to Config, Subscription, or Profiles. Look for an option such as Add, Add Subscription, or Import from URL. Choose the remote URL option, give the configuration an easy-to-recognize name, such as “Personal Remote Config,” and paste the full subscription URL from your service provider. The name is just a local label and won’t affect the connection.

After pasting the URL, check that it doesn’t contain extra spaces, line breaks, or explanatory text added by a messaging app. Query parameters in a subscription URL may be used to identify your account, so don’t remove anything after the question mark or post the URL in a public forum. When ready, tap Save, Download, or Update, then wait for the client to fetch and parse the configuration. If it needs another manual update after import, use Update in that configuration’s action menu.

Once you see a configuration card, an update time, or a success message, select the configuration and tap Enable, Use, or the equivalent selection control. Adding a file to the list doesn’t necessarily make it the active configuration. Next, open the Proxy page and check for policy groups and node options. Group names are set by the configuration author; you might see “Proxy Selection” or “Auto Select,” or something else entirely. Seeing policy groups in the interface confirms there are proxy policies to choose from.

Using a Local YAML File

If you received a .yaml or .yml file, choose Import from File instead. On a Mac, select the configuration in the file picker. On iPhone or iPad, save it to the Files app and import it from the client, or use the client’s option in the system share menu. Select and activate the configuration after importing it. A local file doesn’t update automatically over time; updates depend on remote references in the file and the client’s update features.

Don’t confuse a regular web URL or a single protocol share link with a complete Clash configuration. If you see “Parse failed” or “Missing fields,” or the download returns an HTML page, check with your service provider that you’re using its Clash-compatible subscription link. Don’t remove or change configuration keys just to make an error disappear. For a first setup, avoid sending your subscription to an unfamiliar online converter: it may contain access credentials and service details.

You’re ready to move on when the configuration is selected, the Proxy page shows the expected policy groups, and no new parsing errors appear during an update. Keep the original subscription URL for future updates, then continue to step two.

Step 2: Choose a Routing Mode and Proxy Policy

Choose Rule mode for your first setup. You’ll usually find the mode selector on the home or Proxy page, or in the menu for the Mac menu bar icon. Rule mode uses domain names, IP addresses, and other conditions in the configuration to decide whether a request connects directly or through a proxy. It doesn’t require every app to use the same endpoint, and it doesn’t mean all traffic goes through a proxy server. It’s a good starting point for checking the subscription’s routing rules.

With Rule mode selected, open the main proxy policy group from the configuration you just imported. If the group supports manual selection, choose a node your service provider confirms is available, then check that the selection indicator moves to it. If the subscription includes an “Auto Select” group, you can choose that instead. Group names aren’t standardized, so don’t infer behavior from labels such as “Default” or “Recommended”; check the current selection in the group.

The mode and policy group handle two different questions: the mode determines which requests need a proxy, while the policy group determines where those requests go. So even in Rule mode, requests matched to a group that’s set to DIRECT may still connect directly. Conversely, choosing a node won’t send sites matched by direct rules through the proxy. In the next step, use the connection log to check both.

Global, Direct, and TUN: What’s the Difference?

Global mode generally sends traffic entering the core through the global policy, but you still need to select an endpoint for that policy. It can be useful for a brief comparison test, but it’s not a universal fix for connection problems. Direct mode generally sends traffic entering the core straight to its destination, making it useful for checking whether the proxy endpoint affects access. Some cores may still perform specific internal processing, so check the actual connection logs.

TUN is a way to capture traffic, not a routing mode alongside Rule mode. You can use Rule mode with TUN enabled; switching to Global mode won’t make an app that ignores the system proxy start using it. For your first setup, don’t change both of these independently: keep Rule mode, enable the system proxy on Mac, and establish the client’s device VPN connection on iPhone.

If your client offers connectivity or latency tests, use them to help choose a policy. A successful test only confirms that the specific test request got a result; it doesn’t guarantee access to every website, sign-in service, or app. Don’t keep switching nodes based on a single test result. Choose one available policy, complete the setup, and then adjust based on your actual browsing experience.

You’re ready to move on when Rule mode is selected and the main proxy policy group has a clearly selected option. A group name or test result alone doesn’t prove the connection works. Next, send system or device traffic through the client.

Step 3: Establish a System or Device Connection

Check the configuration and policy before enabling traffic capture. Before testing, disconnect any other proxy client or VPN to avoid multiple apps changing system proxy settings, routes, or DNS at the same time. Don’t remove network configurations managed by your employer or school to troubleshoot. On managed devices, follow device management requirements if VPN or helper service installation is restricted.

macOS: Start the Core and Enable the System Proxy

On the Mac client’s home page, confirm that the core is running. Some clients start it automatically when the app opens; others require you to click Start or Connect. If the page reports a configuration error, go back to step one and resolve it first. Then enable System Proxy from the home page, Settings, or menu bar menu. This sends requests from apps that follow macOS proxy settings to the client. Leave TUN off for now to keep your first setup simple.

After enabling it, go to System Settings → Network → the network service you’re using → Details → Proxies and check whether a local proxy address has been added. The wording and navigation may vary slightly by macOS version. Don’t assume example port numbers are fixed: use the mixed, HTTP, or SOCKS port shown in your client. Manually changing it to another common port may cause a mismatch.

If your browser works but a particular app doesn’t, don’t import the subscription again. Some terminal tools, games, and apps with their own networking stack don’t use the system proxy. They may need separate proxy settings or TUN, if you understand the required permissions. TUN may require a helper service, administrator authentication, and route changes. For details, see the troubleshooting guide; use a browser to verify the basic connection for now.

iOS / iPadOS: Allow and Start the Device VPN

On your iPhone or iPad, tap Connect or the main toggle on the client’s home page. The first time you connect, iOS may ask to add a VPN configuration. Confirm that the prompt comes from the client you just installed and are using, then tap Allow and complete any password or biometric authentication requested by the system. Return to the client and wait for its status to change from Connecting to Connected before testing a website.

On iOS, the VPN configuration provides the network traffic capture used by the proxy client. This is separate from choosing Global mode: even when the system reports the VPN as connected, subscription rules and policies still determine where each request goes. The VPN icon may not appear in the status bar on every device or system interface. Check both the client and VPN status in Settings rather than relying on the icon alone.

If the connection drops as soon as you tap Connect, check that the selected configuration is still valid, no other VPN is capturing traffic, and the client’s recent error log. Note when the error occurred and what you were doing; don’t keep changing DNS, ports, and modes all at once. If the issue started after switching between Wi-Fi and cellular, reconnect and repeat the same test to avoid mistaking a network change for a failed subscription.

You’re ready to move on when the Mac core is running and System Proxy is enabled, or both the client and system show an active connection on iPhone or iPad. This only confirms that traffic capture is set up; verify the result in step four.

Step 4: Verify Access and Routing Rules

Check a real request and the connection log—not just the “Connected” status. Open the client’s Connections, Sessions, or Logs page. In a new browser tab, visit a site that the configuration is expected to route through the proxy and that’s suitable for testing on your network. Use a test site recommended by your service provider when possible, so a site outage isn’t mistaken for a client issue. If the page was already open in another tab, refresh it to generate a new request for the client to log.

Return to the connection log and find the entry for the domain you just visited. Check the destination, matched rule or rule set, and final policy and endpoint. Fields vary by client: some show the full policy chain, while others display only the final node. A page loading, together with a log entry that shows the expected route, is evidence that this request followed the intended path.

Next, visit a site that should connect directly according to your configuration and check its log entry the same way. The two requests don’t have to follow the same route—that’s the point of Rule mode. With the macOS system proxy, requests from apps that ignore proxy settings may never reach the core. So if an app doesn’t appear in the connection list, don’t assume it was blocked. Verify with a browser first, then test your everyday apps one by one.

If Results Don’t Match, Check Each Layer

If a site won’t load but you can see its request in the client, check whether the matched rule and final policy are what you expect, then try a different node known to work. If the site won’t load and there’s no corresponding entry at all, check the system proxy, device VPN, and the app’s own proxy settings before changing subscriptions. If the log shows a domain resolution error, investigate DNS next. Change one setting at a time, and note its original value before you do.

Checking your exit IP alone doesn’t prove that all traffic uses the proxy: the lookup site itself may match a direct rule, and different protocols or apps may follow different routes. A page loading also doesn’t prove that DNS is working as expected. For your first setup, just confirm that the request, policy, and actual access match. For DNS leaks, UDP, IPv6, or routing conflicts, follow the systematic troubleshooting guide to check each item; there’s no need to change every network setting at once in this guide.

Disconnect and Confirm Your Network Is Restored

Once you’ve finished testing, make sure you can disconnect normally. On Mac, turn off System Proxy in the client first. If you enabled TUN separately, turn that off too, then quit the app. On iPhone or iPad, tap Disconnect in the client and check the system VPN status. Refresh a site that normally connects directly to confirm regular network access still works. If your Mac can’t connect after you quit the client, check whether System Proxy still points to the local service that has stopped. See the troubleshooting guide for recovery steps.

For everyday use, follow the same order: update the subscription and confirm the active configuration, check Rule mode and the selected policy, connect, then verify your important apps. Keep a local copy before changing the configuration so you can compare it if an update causes problems. Reinstalling the app shouldn’t be your first response to every issue—problems with policies, subscription validity, and system network settings often have nothing to do with the app installation.