ClashX Subscription Setup: Import and Refresh Proxy Nodes on Mac

Prepare the subscription URL and check what it contains

A ClashX subscription setup has three separate parts: the subscription service, the configuration downloaded from that service, and the ClashX interface that loads the configuration. The URL is an access link to configuration data; it is not itself a proxy node, and adding it does not automatically prove that the nodes can connect. Keeping these parts separate makes it easier to tell whether a failure comes from an expired link, an incompatible configuration, a stopped core, or a network problem.

Before opening ClashX, sign in to the provider’s account page and locate the subscription address intended for Clash or Clash-compatible clients. Some services show several formats, such as a general subscription link, a Clash configuration link, and links intended for other clients. Choose the format specified for ClashX. If the provider offers a configuration conversion option, use it only when the provider documents that it is needed; unnecessary conversion can change proxy names, groups, rules, or protocol details.

Check whether the provider requires a separate activation step, an assigned device, or a generated link before first use. Some services limit how often a subscription can be fetched, or invalidate an older address when a new one is generated. If the account page shows an expiry date, data allowance, or device limit, record those details. A URL that was copied correctly can still fail when the account has expired, reached a quota, or had the link revoked.

On the Mac, confirm that ClashX is installed and can start, and close other proxy clients while testing. Running two applications that both change macOS proxy settings can make it unclear which local proxy is receiving traffic. Also check that the installed ClashX build supports the configuration features supplied by the service. Older ClashX builds may not understand newer configuration fields or proxy protocols, even when the subscription URL itself is valid.

Add the remote configuration in ClashX

ClashX versions do not all use identical menu wording, so use the menu-bar application rather than expecting a separate full-size setup window. Start ClashX and look for its icon in the macOS menu bar. In many builds, the remote-profile controls are under Config and then Remote Config; a management window may be opened with an item such as Manage. If those exact labels are absent, check the installed build’s configuration menu for remote, subscription, or profile management instead of importing the URL into an unrelated proxy setting.

  1. Open the remote configuration manager and choose its add or new-profile control, commonly shown as a plus sign.
  2. Enter a short local name, such as Personal or Provider. This label is for identifying the profile in ClashX and does not change the subscription address or the provider’s account name.
  3. Paste the complete subscription URL into the URL field. Make sure the beginning and end of the address are included, with no extra spaces, quotation marks, or line breaks.
  4. Save the entry, then select the profile’s download, update, or load action. Some builds fetch the configuration when the entry is saved; others require a separate download or update command.

A successful fetch should result in a downloaded configuration and a profile that ClashX can select. The wording and location of the confirmation depend on the application version. If the manager displays a timestamp, check that it changes after the fetch. Then select the newly added profile from the configuration menu if it has not been activated automatically. Adding a remote entry and activating it are distinct operations in some builds.

Do not put the subscription address into a manual YAML editor as though it were a local configuration file. The URL is used to retrieve the file; it is not YAML content. Likewise, do not replace a working profile until the new one has downloaded and loaded successfully. Keeping the previous profile available gives you a simple rollback path if the new configuration contains an error.

Remote profile: Provider
Source: subscription URL saved in ClashX
Local result: downloaded Clash-compatible configuration
Next step: select the profile and confirm that the core starts

If ClashX offers a choice between a remote profile and a local file, choose the remote-profile option for a subscription URL. Use a local-file import only when you have downloaded or received an actual configuration file, typically with YAML content. A provider may also supply a one-time download that does not refresh automatically; in that case, follow the provider’s update instructions rather than assuming that every imported file remains linked to the account.

Refresh nodes and verify the active profile

To refresh the configuration later, open the remote configuration manager and run the update or download action for the saved profile. Menu labels vary by ClashX release, but the goal is to fetch the remote configuration again—not merely switch between existing profiles. Wait for the request to finish before changing profiles. If the service publishes updated nodes, groups, or rules, a successful refresh should make the new data available to the active configuration.

A subscription refresh and a node connection test answer different questions. The refresh checks whether ClashX can retrieve and parse configuration data. A latency test or connection attempt checks whether a particular proxy can be reached from the Mac at that moment. A profile can refresh successfully while one or more nodes are offline; conversely, a profile may still contain usable nodes even if a later refresh is temporarily unavailable.

After updating, confirm that the intended profile is selected and that the ClashX core is running. Open the proxy-group or node selection menu and inspect the available entries. Choose a suitable node or group if the configuration does not already make a choice. Then visit a site or service that should use the proxy and inspect ClashX’s connection display or logs, where available, to see whether a new request is being handled.

  • Profile list: Verify that the newly added profile is selected, not just present in the remote manager.
  • Node or group list: Confirm that the expected names appear. A provider may rename nodes or group them differently after an update.
  • Core status: Check that ClashX has started its core and that no configuration-load error is shown.
  • Connection evidence: Use the client’s activity or log view, if available, to confirm that the test request reaches ClashX.
  • System proxy: Enable ClashX’s system proxy control only if you want macOS applications that honor system proxy settings to use it.

The macOS system proxy switch does not force every program to use ClashX. An application may use its own proxy settings, ignore the system proxy, or maintain a connection opened before the switch was enabled. For a clean test, close and reopen the application, use a new request, and check for that request in ClashX. TUN support, where available in a particular client and core combination, is a separate traffic-capture method and should not be assumed to be enabled by importing a subscription.

When a profile does not update, avoid repeatedly pasting the same address or switching nodes at random. First note the exact stage that fails: the URL cannot be saved, the download request fails, the file downloads but cannot be parsed, the configuration loads with no usable groups, or traffic reaches the proxy but does not connect. Each symptom points to a different part of the setup.

Symptom Likely cause What to check
Update reports an authorization or not-found error Expired, revoked, incomplete, or incorrectly copied URL Generate or copy the current Clash-compatible link from the provider account page; check account status and avoid sharing the link in support requests.
Download times out or cannot connect Temporary network failure, DNS issue, provider outage, or a blocked route to the subscription server Retry once after checking the Mac’s connection, then check the provider’s service status. If another proxy is already running, avoid overlapping system-proxy changes while testing.
File downloads but ClashX reports a configuration error Malformed YAML, unsupported fields, or a format intended for another client Confirm the provider’s selected format and check the core error message. Use a client and core version that support the configuration features in use.
Profile loads but the node or group list is empty Incomplete provider output, unsupported configuration structure, or a profile that references missing providers Check the provider’s Clash instructions and the client log. Do not assume that a successful HTTP download means the configuration is usable.
Nodes appear but connection attempts fail Offline node, account restriction, incorrect system-proxy path, or a protocol the installed core does not support Test another available node, confirm the selected group, inspect the connection log, and verify the core version before editing unrelated DNS or routing fields.

An expired-link error is best handled in the provider’s account portal. Copy a newly issued address if one is available, replace the old URL in the remote profile, and fetch the configuration again. Do not assume that adding a query parameter, changing capitalization, or opening the address in a browser will repair it. Subscription endpoints can include account-specific tokens and may be deliberately designed for client requests rather than ordinary browser navigation.

For a configuration error, record the error text and the ClashX/core version before making changes. YAML parsers are sensitive to indentation and structure, but a user should not need to rewrite a provider-generated configuration just to test a subscription. If a manual inspection is necessary, work on a duplicate and redact server addresses, credentials, UUIDs, and subscription tokens before sharing any excerpt. A provider-generated file may also include fields unsupported by an older core, in which case switching to a compatible client or core is safer than deleting fields without understanding their purpose.

If the profile loads but traffic fails, check the selected group and the connection log before changing DNS. Confirm that ClashX’s system proxy is enabled if the application relies on macOS proxy settings, and make sure another client has not replaced those settings. Test more than one node if the provider offers alternatives, but remember that latency measurements are not a guarantee that every destination or protocol will work. A successful connection to one website only verifies that particular route.

Handle subscription credentials safely and keep a fallback

A subscription URL often contains a long token that grants access to the account’s current configuration. Store it only in ClashX or another client you trust, and avoid saving it in shell history, chat transcripts, public issue trackers, or screenshots. If you need help, share the error message and the non-sensitive part of the workflow first. If the complete URL has been exposed, revoke or regenerate it through the provider when that option is available, then update the saved remote profile.

Keep the local profile name neutral. There is no need to include the full URL, account email, or access token in the name. When using macOS screen sharing or recording a tutorial, hide the remote configuration manager before showing the screen. Be cautious with third-party URL checkers: testing a subscription address through an external site gives that site the opportunity to receive the credential.

Before replacing a profile that currently works, confirm that the new remote configuration has loaded and that its groups and nodes are present. If ClashX supports exporting or saving a local copy, keep a backup for recovery, while remembering that a downloaded copy will not necessarily update itself. Protect that file as well: it may contain server addresses, passwords, UUIDs, or other details that should not be published.

Finally, treat subscription updates as configuration changes rather than as a guarantee that the service will behave identically after every refresh. Providers can change node names, available groups, rules, and supported protocols. After a major update, verify the active profile, inspect the group selection, and test the applications you rely on. If an older ClashX build repeatedly rejects a valid configuration, compare its supported core features with the provider’s requirements instead of repeatedly exposing or regenerating the subscription link.

Download Clash