How To Use ClashX: Add Subscriptions And Switch Nodes

What ClashX Does on macOS

ClashX is a macOS graphical client for the Clash family of proxy cores. It provides a menu-bar interface for loading profiles, selecting proxy policies, changing the system proxy, and checking connection logs. The application itself does not create a subscription or provide proxy servers. Your subscription provider supplies the profile URL, and ClashX downloads the YAML configuration or compatible profile data from that URL.

The important distinction is between a profile, a proxy node, and a proxy group. A profile is the complete configuration downloaded from a subscription address. It can contain dozens of nodes, DNS settings, rules, and policy groups. A node is one individual server entry, such as a Shadowsocks, VMess, Trojan, VLESS, or other supported outbound. A proxy group is the selection layer that decides which node receives a connection. When you click a server in ClashX, you are often changing the active member of a proxy group rather than editing the node itself.

ClashX normally works through macOS system proxy settings. When you enable the system proxy from the menu-bar icon, applications that respect the macOS HTTP and HTTPS proxy configuration can send traffic through the local ClashX service. The local mixed or HTTP proxy port is commonly 7890, while the SOCKS5 port is commonly 7891, but these values depend on the imported profile and client settings. Do not assume a port from a tutorial is correct; check the active configuration before entering it into another application.

Profiles store subscription URLs and downloaded configurations.
Proxies or Proxy displays policy groups and individual nodes.
Rules determines whether traffic is sent to a proxy group, directly connected, or rejected.
Logs shows requests, rule matches, connection failures, and selected outbound policies.
System Proxy controls whether macOS applications use ClashX's local proxy automatically.

A subscription is a private access credential

The URL usually contains an account token. Anyone who obtains it may be able to download your server list or consume your provider's traffic quota. Store it in ClashX rather than posting it in screenshots, chat messages, public issue trackers, or shared documents. If the URL is exposed, revoke or reset it in the provider dashboard and import the replacement link.

Before Importing a Subscription

Prepare three things before opening ClashX: a supported macOS version, a working ClashX installation, and a valid subscription URL. The exact menu labels can vary between the original ClashX, ClashX Pro, and repackaged builds, but the workflow remains the same: open the profile manager, add a remote profile, update it, then select the resulting profile as active.

Use a complete URL beginning with https:// whenever the provider offers one. A shortened address, a copied URL with spaces, or a link that was truncated by a messaging application may appear to import successfully but return an empty profile later. Some providers also offer a conversion page with a target format or client preset. If the provider specifically supplies a Clash or ClashX subscription address, use that address rather than manually changing query parameters.

Item	What to verify	Why it matters
macOS	The system is supported by the installed ClashX build and has an active internet connection	An old binary may open but fail when loading modern TLS or profile formats
Subscription URL	It starts with `https://` and was copied in full	A missing token or character can produce an authorization or empty-profile error
Profile format	The provider lists Clash, Clash Meta, or mihomo compatibility	Unsupported fields or protocols may be ignored by an older ClashX core
System proxy	No other VPN or proxy application is changing macOS network settings	Two tools competing for the same proxy settings can make testing misleading

ClashX is an older macOS client in many installations, and its bundled core may not understand every feature used by current mihomo profiles. If a subscription includes newer protocols, advanced rule providers, or fields introduced after the original Clash line, the profile may load with warnings or fail validation. In that case, compare the core supported by the client with the format offered by the provider. A modern mihomo-based client may be more appropriate; the download center lists available client choices.

How to Add and Update a Subscription in ClashX

The following procedure applies to the common ClashX menu-bar interface. Keep the subscription URL available in the clipboard, but do not paste it into a shell command or a public note. The profile manager may be named Profiles, Config, or Remote Profiles depending on the build.

Launch ClashX and confirm that its icon appears in the macOS menu bar. If macOS blocks the application, open System Settings, choose Privacy & Security, and use the available option to allow the application to open. Only continue when the client is running normally.
Click the ClashX menu-bar icon and open the profile management entry. Look for Profiles, Remote, or an option such as Manage Profiles. This is different from selecting a proxy node; you are opening the list of downloaded configurations.
Choose the option for adding a remote profile. Paste the full subscription URL into the URL field. If the dialog asks for a profile name, use a short local label such as main-mac or work-profile rather than placing the private URL in the name.
Save or confirm the remote profile. ClashX should fetch the document and display a new profile entry. A successful download does not always mean the configuration is usable, so check whether the entry reports a node count, policy groups, or a valid YAML configuration.
Select the new profile and choose Update, Download, or the refresh action shown by your build. Wait for the request to finish. Do not switch profiles repeatedly while the download is still running.
Make the downloaded profile active. The active profile is usually marked with a check symbol or highlighted row. If the profile was only downloaded but not selected, the proxy page may still show nodes from the previous configuration.
Open the proxy policy view and inspect the group names. A normal subscription often creates groups such as PROXY, Proxy, Auto, Fallback, or a provider-specific name. Select one group and verify that individual nodes appear beneath it.

For scheduled refreshes, some ClashX versions expose an interval in the remote profile settings. A shorter interval is not automatically better: every update consumes provider traffic or request quota, and a temporary provider outage can replace a previously usable local copy with an error state. A daily refresh is usually enough for ordinary use unless the provider instructs otherwise. After an update, check the timestamp and confirm that the node count is plausible.

Downloaded is not the same as active

ClashX can retain several profiles at once. Importing a new subscription only adds it to the local list. You must activate the intended profile, open its policy groups, select a node, and then enable the system proxy. Checking all four states prevents the common situation where a new subscription was added but the old profile remains in use.

Compare Latency and Choose a Node

Node selection should be based on more than the smallest latency number. ClashX's delay test generally measures the time required to reach a test URL through an individual proxy. It does not measure video buffering quality, peak download speed, route stability over several hours, or whether a streaming service accepts the node's exit IP. A node reporting 80 ms can still be less useful than one reporting 140 ms if the first has packet loss or frequent resets.

Open the proxy policy page and find the group used by the rules for the traffic you want to test. If the group is an ordinary select group, choose a node manually. If it is a url-test or fallback group, the group may automatically select or switch according to its configured behavior. Testing the node list but then leaving a different policy group selected will not change the route used by your browser.

Identify the actual proxy group used by the active profile. The default group is often named PROXY, but a rule may point to a separate group for streaming, messaging, or gaming traffic.
Run the built-in delay test if your ClashX version provides one. Use the same test URL for all nodes and wait for enough results to appear. A timeout means the test request did not complete; it is not a latency value.
Remove obviously unusable candidates from consideration: repeated timeouts, very large variation between tests, or immediate connection resets. Do not treat a single successful response as proof of stability.
Choose a node with a reasonable delay and a suitable exit region. For general browsing, stable response time is usually more important than the lowest one-time result.
Click the node in the group and verify that the group now displays it as selected. Then generate a new request from a browser or terminal so the result is not confused with an existing connection.

Observation	Likely interpretation	Recommended action
20–100 ms with consistent results	Good response path for ordinary interactive traffic	Keep it as a daily-use candidate and compare stability later
Low delay but frequent timeouts	The route may have packet loss, congestion, or an unstable server	Test another node instead of choosing by the lowest number
All nodes time out	The subscription, local network, core, or test endpoint may be the problem	Check logs, update the profile, and test the local proxy port
Browser still uses the old exit address	The browser connection is cached or the selected group is not used by its rule	Reload the page, close persistent connections, and inspect the rule match
One service fails while ordinary sites work	The service may require a different region or reject the node's address	Try a node from another region and inspect the service-specific policy

After switching nodes, existing TCP and TLS sessions may continue through the old node until they close. A browser tab that was already open can therefore show an old result. Close the tab or restart the application being tested, then make a fresh request. For long-lived applications, such as chat clients or development tools, restarting the application is often quicker than waiting for all connections to expire.

Enable the macOS Proxy and Verify Routing

Selecting a node does not necessarily route every Mac application through ClashX. The usual next step is to enable Set as System Proxy or System Proxy from the ClashX menu-bar menu. macOS may ask for an administrator password because changing system network proxy settings requires permission. Approve the request only when ClashX is the application you intended to run.

System proxy mode normally covers browsers and applications that honor the macOS HTTP or HTTPS proxy settings. It does not guarantee coverage for every command-line tool, game, background service, or application that uses its own networking stack. A program may bypass the system proxy, use a separately configured SOCKS5 endpoint, or resolve and connect directly. If full-device capture is required and the client supports it, a TUN-capable mihomo client is generally a better fit than relying only on system proxy mode.

Check that the system proxy indicator is enabled in the ClashX menu.
Open macOS network settings and confirm that the active interface has HTTP and HTTPS proxy entries pointing to the local ClashX address and port.
Use the ClashX log view while opening a new webpage. A request appearing in the log confirms that this application reached ClashX.
Inspect the matched policy. Seeing a request in the log is not enough; the log should show whether the connection used DIRECT, a proxy group, or another outbound.
After selecting another node, repeat the test with a fresh request and compare the outbound address or service behavior.

For a quick local-port check, a browser can be configured manually with the HTTP proxy address 127.0.0.1 and the port shown in ClashX. If the client exposes only a SOCKS5 listener, use the SOCKS5 protocol and its displayed port instead of guessing 7890 or 7891. A port conflict with another proxy application can cause a connection refusal, so check whether another process is already listening on the same port.

Verify one request from start to finish

The most reliable check is a fresh request while watching the log: confirm that the request appears, note the matched rule, confirm the selected outbound group or node, and then check the result in the application. This distinguishes a working proxy from a client that is merely running in the menu bar.

Troubleshoot Import, Update, and Connection Failures

When a subscription or node fails, change one variable at a time. Disabling the system proxy, changing the profile, switching DNS, and installing another VPN simultaneously removes the evidence needed to identify the cause. Start with the exact stage that failed: importing the URL, parsing the downloaded profile, testing a node, connecting through the local port, or matching the intended rule.

Subscription URL Errors

An HTTP 401 or 403 response usually indicates an invalid, expired, revoked, or unauthorized subscription link. A 404 response usually means the address is wrong or the provider has removed the endpoint. A timeout can be caused by the local network, DNS resolution, a provider outage, or a server that is unreachable from the current connection. Test the URL only in a private browser window if the provider permits it; remember that opening the URL may expose the subscription content to that browser session.

If ClashX downloads a very small file, an HTML error page, or a document asking you to log in, it may report a format or YAML parsing failure. The response is not a valid Clash profile even though the HTTP request technically succeeded. Return to the provider account page, copy the generated Clash-compatible URL again, and check whether the link requires a conversion target.

Profile and Node Errors

If the profile loads but contains no usable nodes, check its timestamp and the provider's account status. The subscription may have reached a traffic or device limit. If only some nodes are missing, the current ClashX core may not support the protocols or fields used by those entries. A legacy client can display a partial list while silently skipping unsupported outbounds. Compare the profile format with the core requirements before editing the YAML manually.

If every node shows a timeout, first test the local ClashX service. Make sure the client is running, the selected profile is active, and the local port is not occupied by another application. Then look at the log while testing one node. A TLS handshake error, certificate error, authentication error, or connection reset points to a different problem than a local port refusal.

Routing and DNS Symptoms

When the log shows DIRECT for a destination that should use a proxy, the rule order or policy group is the first place to look. Rules are evaluated from top to bottom, and a broad rule placed above a specific rule can capture the request early. A final MATCH rule is expected, but it should not be moved above service-specific rules. If the log shows the correct proxy group but the domain still fails, test another node and inspect DNS behavior.

Fake-IP mode can make local diagnostics look unusual because a domain may resolve to an address in the reserved 198.18.0.0/15 range. That address is an internal mapping used by the Clash DNS module, not necessarily the remote server's real public address. Avoid hard-coding such addresses in local firewall rules. If a browser reports a DNS error while Clash logs no request, the application may be bypassing Clash or the system DNS interception is not active.

Symptom	Check first	Practical fix
Profile import says invalid format	HTTP response and provider target format	Copy a Clash-compatible URL and update the client if the profile requires mihomo
Profile downloads but node list is empty	Account status, expiry, and downloaded file size	Refresh the subscription or request a new URL from the provider
Local proxy connection refused	ClashX process, port, and port conflicts	Start ClashX, check its actual port, and close competing proxy tools
Only one application bypasses ClashX	Whether that application supports system proxy settings	Configure its HTTP/SOCKS5 proxy separately or use a supported TUN client
Correct node but wrong route	Log rule match and selected policy group	Fix group selection or rule order, then create a fresh connection

ClashX Subscription and Node FAQ

Why does ClashX show the profile but no nodes?

The downloaded response may be an expired-account message, an HTML login page, or a profile using protocols that the bundled core cannot parse. Update the profile, check the provider account, and compare the subscription format with the core supported by your ClashX build. Do not assume that a visible profile name means the node data was successfully parsed.

How often should a ClashX subscription be updated?

Use the interval recommended by the provider. For a stable subscription, a daily update is generally sufficient. Updating after a provider changes servers or when a node disappears is reasonable, but repeatedly refreshing every few minutes wastes request quota and can make temporary service errors look like permanent profile failures.

Why does switching a node not change the connection?

The selected node may belong to a group that is not used by the request's rule, or the application may have an existing persistent connection. Check the ClashX log for the actual matched policy, close and reopen the test tab or application, and confirm that the system proxy is enabled. If no request appears in the log, that application is likely bypassing ClashX.

Does enabling System Proxy cover every Mac application?

No. It mainly affects applications that honor macOS HTTP and HTTPS proxy settings. Some command-line programs, games, background services, and applications with their own network stack may connect directly. Configure those applications separately when supported, or choose a maintained mihomo-based client with TUN mode when system-wide capture is required.

Continue with a Working ClashX Setup

The reliable sequence is simple: import the complete subscription URL, update the remote profile, activate that profile, select the policy group, compare several nodes, enable the macOS system proxy, and verify a fresh request in the ClashX log. When a connection fails, identify which stage failed before changing settings. This approach prevents an old profile, an incorrect group, a cached browser connection, or an unsupported core from being mistaken for a bad node.

For platform downloads and alternative maintained clients, use the download center. For the broader first-run workflow, including profile selection, system proxy behavior, and common permission prompts, continue with the setup tutorial.

Open Downloads View Tutorial