ClashX Setup Guide: How to Add a Subscription and Switch Nodes

Understand what ClashX, a subscription, and a node each do

ClashX is a macOS graphical client for controlling a Clash-compatible proxy core. It can import configuration files, download subscription profiles, start or stop the local core, switch proxy policies, and enable or disable the macOS system proxy. The subscription provider supplies the configuration content; ClashX does not create proxy servers or repair an expired account. Keeping these roles separate makes the setup process much easier to troubleshoot.

A subscription URL normally contains proxy nodes, proxy groups, routing rules, DNS settings, and update information generated by your provider. A node is one outbound server entry, while a proxy group is a selectable collection of nodes. For example, a group called Proxy, Node Select, or 手动选择 may contain servers in several countries. Selecting a node inside that group changes the outbound route used by traffic matched to the group.

Before making changes, confirm that you have an active subscription, a complete subscription URL, and a macOS account allowed to change network settings. Treat the URL like a password because it often contains an access token. Do not paste it into screenshots, public issue reports, or support messages without removing the token portion.

Install ClashX and verify the initial macOS state

Download ClashX from a source you trust and select the package that matches your Mac when separate Intel and Apple silicon builds are offered. You can check the hardware in Apple menu → About This Mac. A Mac with an Apple M-series chip requires an arm64 or Apple silicon build; an Intel Mac requires an x64 or Intel build. If only an older universal build is available, macOS may use Rosetta for Intel code, but a native build is generally preferable when supported.

1. Open the downloaded DMG or archive.
2. Drag ClashX into the macOS Applications folder.
3. Launch it from Applications and look for its icon in the menu bar.
4. If macOS blocks the first launch, open Finder, locate ClashX, hold Control, click the app, and choose Open.
5. Review System Settings → Privacy & Security if macOS reports that the developer cannot be verified.

Do not run the application permanently from a DMG, Downloads folder, or removable drive. A fixed location makes upgrades, permissions, and saved configuration paths more predictable. If another proxy client is already active, turn off its system proxy before testing ClashX. Two clients may attempt to control the same macOS proxy settings or listen on overlapping local ports.

Check the local core before importing a profile

After launching ClashX, open its menu bar menu and identify the entries for configuration, proxy mode, proxy selection, logs, and system proxy. The exact labels vary between ClashX releases and forks, but the operational concepts are similar. A client window or menu icon alone does not guarantee that the core is running. The core must load a valid configuration and listen on its local port before applications can send traffic through it.

Common configurations use a mixed HTTP and SOCKS port such as 127.0.0.1:7890, although the actual value may be different. If a browser or another application offers manual proxy settings, use the port shown in the active profile rather than copying a value from an online example. When diagnosing a connection problem, check the ClashX log for core startup errors, port conflicts, unsupported proxy types, or YAML parsing failures.

Add a subscription URL and download the profile

Open the profile or configuration management area from the ClashX menu bar. Depending on the build, the command may be called Config, Profiles, Remote Config, or Manage Configurations. Choose the option for adding a remote configuration or subscription, then paste the complete URL supplied by your provider. Avoid manually retyping the address because one missing character can produce an authentication error or download an unrelated page.

1. Copy the full subscription URL from the provider’s account dashboard.
2. Open ClashX’s profile management menu.
3. Choose the remote URL, subscription, or add-profile command.
4. Paste the URL into the address field.
5. Give the profile a short name such as Daily or Personal.
6. Start the download and wait for the profile to appear in the local list.
7. Select the downloaded profile so ClashX uses it as the active configuration.

A successful download may still be followed by a parsing error. A valid response should contain Clash-compatible YAML, encoded configuration content that the client knows how to decode, or a provider-generated profile in a supported format. If the response is an HTML login page, a CAPTCHA, a JSON error, or a message saying that the plan has expired, ClashX cannot treat it as a usable profile.

Refresh the profile and test node latency

Subscription providers change server addresses, certificates, ports, and policy groups over time. After importing a profile, refresh it once before choosing a node. In ClashX, use the profile’s update or reload command. If the profile has an automatic update interval, a daily interval such as 1440 minutes is usually less aggressive than repeatedly pressing refresh. Excessive requests can trigger a provider’s rate limit, while a very long interval can leave you using expired nodes.

After the update finishes, open the proxy selection area and locate the main group used by the active rules. It may be named Proxy, Proxy Group, Node Select, Auto, or another provider-defined name. Do not assume that the first visible node is the best choice. A node’s name may include a location or speed label, but names are not a live measurement of availability.

Use the latency test or delay-test command when available. The test usually sends a small request to a fixed URL and records the round-trip time; it does not measure sustained download speed, streaming quality, or performance for every website. A node showing 80 ms may still fail to load a particular service because of routing, congestion, TLS behavior, DNS resolution, or destination-side blocking.

Switch nodes and turn on the macOS system proxy

Once the profile is updated and the latency test is complete, select a working node inside the policy group used by your rules. Click the group, choose a node with a successful test, and wait for the selection mark to change. Some versions apply the selection immediately; others require choosing the node and then reloading the configuration. Watch the ClashX log or connections panel for a new outbound connection after switching.

The node you select may not control every request. In rule mode, different domains can be sent to different groups such as a direct group, a streaming group, an advertising-block group, or a default proxy group. If switching the visible “Proxy” group has no effect on a particular website, inspect which rule matched the request and which policy group that rule references.

For ordinary macOS applications, enable the system proxy from the ClashX menu bar. The client commonly writes a local HTTP and HTTPS proxy address such as 127.0.0.1:7890 into the current network service. The exact port is controlled by the profile, so check the active configuration if applications report that the proxy is unavailable.

1. Confirm that a profile is active and the ClashX core is running.
2. Select a node that passed the delay test.
3. Choose the appropriate proxy mode, usually Rule for normal rule-based routing.
4. Enable Set as system proxy or the equivalent system-proxy command.
5. Open a browser and test a simple HTTPS page.
6. Check the connections or logs panel to confirm that the request reaches the expected policy group.

System proxy mode works for browsers and applications that respect macOS HTTP or HTTPS proxy settings. It may not capture every command-line program, game, virtual machine, or application with its own network stack. TUN mode can cover a wider range of traffic, but it requires additional permissions and changes DNS and routing behavior. Start with the system proxy and use TUN only when the applications you need do not follow the system proxy.

Verify both access and routing

Test more than one destination. First open a normal HTTPS website, then check a service that is expected to use the selected proxy group. Compare the ClashX connection log with the browser result. If the log shows no request, the browser may be bypassing the system proxy or using a separate proxy extension. If the log shows a request but the node fails, try another node and inspect the core error.

When a page opens but appears to use the wrong region, check the active group and the matched rule rather than immediately changing the subscription. When all pages fail, disable the system proxy, confirm that the core starts without errors, verify the local port, and then enable the proxy again. This separates a node problem from a local client or system-setting problem.

Frequently asked questions