Before You Add a Subscription
ClashX is a macOS menu-bar client that applies Clash-compatible configuration profiles and routes network traffic according to the rules in the active profile. A subscription is not the same thing as the app: it is a URL supplied by a proxy service that lets ClashX download a configuration containing server details, proxy groups, and routing rules. You need both a working ClashX installation and a valid subscription from a provider before you can connect to a node.
The exact menu labels can vary slightly between ClashX versions and forks. In the classic app, most controls are available by clicking the ClashX icon in the macOS menu bar. Look for items such as Config, Proxy, and Set as system proxy. If your version uses a preferences window or a differently named configuration manager, use the equivalent profile or remote-configuration control rather than importing the subscription as a one-off local file.
Before continuing, obtain the subscription URL from your provider’s account page. It may be labeled Clash subscription, configuration URL, or copy subscription link. Treat this URL like a password: anyone who obtains it may be able to use the service assigned to your account. Do not paste it into a public issue, screenshot, shared document, or chat. If you believe it has been exposed, revoke or regenerate it through your provider.
What You Need
A supported ClashX installation, an internet connection, and a current Clash-compatible subscription URL from a provider. A URL alone does not create an account or provide proxy access.
It is also useful to know the difference between downloading a profile and using it. Adding the URL tells ClashX where the profile can be retrieved; refreshing downloads the provider’s latest version; selecting a node chooses an outbound connection within a proxy group; and enabling the system proxy asks macOS to send supported applications’ traffic through ClashX. These are separate actions, so a successful profile download does not automatically mean that the system proxy is on or that a particular node has been selected.
1Add the Subscription URL to ClashX
Start ClashX and confirm that its icon appears in the macOS menu bar. If the icon is missing, open ClashX from the Applications folder and check whether macOS has blocked the first launch. Once the app is running, click the icon to open its menu. The menu-bar location matters: adding a subscription in your provider’s website or in another Clash client will not add it to this ClashX installation.
- Open the provider’s dashboard in a browser and copy the URL specifically intended for Clash or ClashX. If the provider offers several formats, do not choose a format for a different application unless the provider says it is compatible.
- Click the ClashX menu-bar icon and open Config. In versions that provide a remote-profile manager, choose the item labeled Remote Config, Manage Configs, or a similar option. Some builds place profile management in the app’s preferences.
- Choose the control to add a remote configuration. Depending on the build, it may be shown as a plus button, Add, or Download from URL. Paste the complete subscription URL into the address field.
- If the manager asks for a profile name, enter a short descriptive label such as the provider name. The label is for your own reference; it does not alter the subscription or select a proxy node.
- Confirm the addition or download. Wait for the profile to finish loading, then check that the new configuration appears in the profile list and can be selected as the active configuration.
Pay attention to the entire URL when pasting it. A leading or trailing space, a missing character, or an incomplete copy can cause a download failure. Some provider dashboards offer a button that copies the link, while others display a link that must be copied in full. Avoid manually changing query parameters or shortening the URL: those values can identify the subscription or select a provider-specific format.
Use the Remote Profile, Not a Local YAML Import
A remote profile can be refreshed from its source. Importing a downloaded YAML file as a local configuration may work for a one-time setup, but it will not necessarily receive the provider’s later node or rule updates.
When a subscription has been added successfully, make it the active profile if ClashX does not select it automatically. In the menu, open Config and choose the profile by the label you gave it. An active or checked item usually indicates which configuration is currently loaded. If the menu continues to show only the previous profile, return to the manager and confirm that the new item was saved rather than merely entered into a dialog.
2Refresh the Profile and Confirm It Loaded
Providers may change server addresses, add nodes, retire overloaded locations, or update routing rules. Refreshing the remote profile asks ClashX to retrieve the latest configuration from the subscription URL. The refresh command may appear under Config as Update Config, Update, or an equivalent command. Some versions expose the action in the remote-profile manager; select the relevant profile first if the manager has more than one entry.
- Make sure the Mac has an internet connection. If the current proxy is broken, temporarily disable the system proxy or use an available direct connection so the client can reach the subscription server.
- Open the ClashX menu and select the profile update or refresh action. If prompted to choose a remote configuration, choose the subscription you added.
- Wait for the update to complete. Do not quit ClashX or put the Mac to sleep while a download or profile reload is in progress.
- Reopen the menu and check for the profile’s update result. Then open the proxy groups or node list and see whether the expected entries are present.
A refresh generally updates the configuration; it does not guarantee that every node in the list is reachable. It also may not change the selected node. If the provider has not changed the profile since your last download, the visible list may remain the same. A successful refresh is best confirmed by a completed update message or a refreshed profile timestamp when your version displays one—not simply by seeing the same profile name in the menu.
If an update reports an error, check whether the subscription URL is still valid and whether your provider has a service outage or usage limit. A subscription can expire, be revoked, or become unavailable after a password or account change. Do not assume the link is wrong just because the profile cannot be updated while the Mac is offline or while a restrictive network blocks access to the provider’s subscription host.
Do Not Share the Update URL
A subscription URL can contain account-specific credentials. When asking for help, redact the full URL, tokens, server addresses, and any other private values from screenshots or logs.
3Select a Proxy Node in the Right Group
Once the profile is loaded, click the ClashX menu-bar icon and open Proxy. A provider’s profile commonly includes several groups, for example a group for automatic selection, a region-specific group, or a group used by a particular rule. The names are controlled by the profile, so they will not necessarily match examples from another provider. Select a group first, then choose a node inside that group.
For a first connection test, select a specific node in a group that offers a manual choice. A location label can help you identify the approximate region, but it does not guarantee speed or availability. If the provider offers an automatic or latency-testing group, you may use that option instead; its behavior depends on the rules and health checks in the downloaded profile. Some groups are nested, so clicking a group name may open its available choices rather than immediately activating a server.
| Menu item or group type | What it usually does | When to choose it |
|---|---|---|
| Manual node group | Lets you select a particular server from a list. | Useful for testing a known region or comparing available nodes. |
| Auto or URL-test group | Selects a member according to the provider’s configured health check or delay test. | Useful when you want the profile to choose from eligible nodes automatically. |
| Rule-based group | Provides an outbound choice used by one or more routing rules. | Useful when the profile separates traffic by service, region, or purpose. |
| DIRECT | Sends matched traffic without a proxy node. | Use only when direct routing is intended for that traffic. |
After choosing a node, allow a few seconds for the selection to take effect. Test a site or service that should use the proxy, and check the ClashX connection or request display if your build provides one. A node name in the menu confirms the selection, not that every application is successfully routed through it. A rule may send a particular destination to DIRECT or to a different group, so test with an appropriate destination before concluding that the node selection failed.
If a selected node does not connect, try another node in the same group, then try a different group if one is available. A failure on one server may reflect a temporary outage, capacity limit, or an incompatible route rather than a problem with the entire subscription. Avoid changing protocol settings or editing provider credentials unless you understand the profile format and have a backup of the original configuration.
4Turn On the macOS System Proxy and Test
Selecting a profile and node does not, by itself, ensure that macOS applications use ClashX. In the menu-bar menu, find Set as system proxy and enable it. In some versions, the item displays a checkmark when enabled; others may show a status change or a differently named system-proxy control. The system proxy setting directs applications that respect macOS proxy settings to ClashX. It is not a promise that every command-line tool, virtual machine, or application with its own network configuration will follow the same route.
- Confirm that the intended configuration is active under Config.
- Open Proxy and choose a node or group that should handle the traffic you are testing.
- Enable Set as system proxy in the ClashX menu.
- Open a new browser tab and visit a site that your profile routes through the selected proxy. If the profile includes a connection log, check which rule and outbound group handled the request.
- If the test fails, compare with the system proxy disabled. This helps distinguish a general network issue from a ClashX routing or node issue.
Do not enable a separate proxy configuration in the browser at the same time unless you intentionally want it to override the system settings. Conflicting browser settings can make a working ClashX setup appear ineffective. Likewise, if you have another proxy client open, it may compete for the macOS proxy configuration or use the same local listening port. Close or disable other proxy tools while testing, then re-enable them only after checking that they do not conflict.
A Simple Troubleshooting Test
Test one browser destination with the system proxy on, then turn it off and repeat. If both tests fail, investigate the Mac’s network or the destination itself. If only the proxy-enabled test fails, check the active profile, selected group, node availability, and ClashX logs.
When you finish using the proxy, you can turn off Set as system proxy from the ClashX menu. This returns macOS applications that follow the system setting to their normal network path. If a network behaves unexpectedly after quitting the app, reopen ClashX and use its menu to disable the system proxy cleanly. Also check macOS network settings if a manually configured proxy remains enabled; avoid deleting unrelated network settings while troubleshooting.
Common Problems and FAQ
Why does ClashX fail to download my subscription?
First confirm that the Mac is online and that you copied the complete Clash-compatible URL. Check for accidental spaces and try copying the link again from your provider’s dashboard. If the URL was previously working, verify that the subscription has not expired, been revoked, or reached an account limit. A captive Wi-Fi portal, firewall, DNS problem, or provider outage can also prevent the download. If the provider supplies a new URL, replace the old remote profile using the profile manager rather than appending fragments to the link. Keep the URL private when contacting support.
Why is the node list empty or missing expected locations?
Confirm that the remote profile finished downloading and is selected as the active configuration. Refresh it once, then reopen the Proxy menu and inspect the available groups. The provider may have changed the subscription format or removed nodes from the plan. Some profiles expose nodes inside nested groups rather than in one flat list. If the expected entries remain missing after a successful update, ask the provider whether the subscription is intended for ClashX and whether your plan includes those locations.
Why does turning on the system proxy not change my connection?
Check that a node is selected in the correct group, not merely that the overall group is visible. The profile’s rules may route the test destination directly or through another group. Also confirm that the browser is set to use the system proxy, and temporarily close other proxy tools that may overwrite macOS settings. If the browser works but a command-line program does not, that program may ignore the system proxy and require its own proxy configuration. Use ClashX’s request display or logs, when available, to see how the destination was routed.
Should I use the same instructions in every Clash client?
No. ClashX is a macOS client, and its menus differ from Clash Verge, Clash Verge Rev, Clash for Windows, Clash for Android, and Mihomo-based applications. The general concepts—remote profile, refresh, proxy group, node selection, and system proxy—are similar, but menu names and supported features can differ. Follow the controls shown by your installed version and consult the provider’s instructions if it supplies a ClashX-specific setup guide. Do not assume that a profile or menu path from another client applies unchanged.
In short, a reliable setup follows a clear sequence: add the provider’s remote URL, make the profile active, refresh it when needed, select a node in the appropriate group, enable the macOS system proxy, and test a destination that should use that route. Keeping these steps separate makes it much easier to find the cause of a problem without repeatedly replacing a profile that is already working.