How to Import Remote Subscriptions and YAML Configs in ClashFX

Published on 2026-03-01 · Last updated 2026-11-11

Understanding Remote Subscriptions

A remote subscription is a secure HTTPS link supplied by your proxy service provider. When ClashFX queries this URL, it downloads a structured YAML configuration containing:

• Server Node List: Endpoints, ports, passwords/UUIDs, and encryption protocols (Shadowsocks, VMess, VLESS, Trojan, Hysteria2, TUIC).
• Proxy Groups: Strategic routing groups such as Auto-Select (low-latency fallback), Manual Select, and Failover groups.
• Routing Rules: Instructions governing which domains and IP subnets route through specific proxy groups or bypass proxies directly.
• DNS Settings: Upstream resolvers and Fake-IP address mapping rules.

Using remote subscriptions eliminates the need to manually update server IP addresses and port numbers whenever infrastructure changes.

Getting Your Subscription URL

To set up your connection in ClashFX, obtain your subscription endpoint from your service dashboard:

1. Sign in to your proxy provider’s web portal.
2. Locate the Subscription or API section.
3. Select the Clash or Clash Meta / Mihomo format.
4. Copy the generated HTTPS URL to your clipboard.

Security Note: Subscription URLs contain private authentication tokens. Never paste subscription URLs in public forums, GitHub repositories, or shared workspaces.

Method 1: One-Click URL Scheme Import

The quickest way to add a profile is using browser-triggered URL schemes. Many provider portals offer an Import to Clash button. ClashFX registers both clashfx:// and legacy clash:// protocols:

clashfx://install-config?url=https%3A%2F%2Fapi.provider.com%2Fsub%3Ftoken%3Dxyz&name=Provider-Fast
clash://install-config?url=https%3A%2F%2Fapi.provider.com%2Fsub%3Ftoken%3Dxyz&name=Provider-Fast

When you click the import button:

1. macOS asks: “Do you want to allow this page to open ClashFX?”
2. Click Allow.
3. ClashFX automatically opens the configuration prompt with the URL and profile name pre-filled.
4. Click OK to download and switch to the profile.

Method 2: Manual Subscription Setup

If your provider provides only a plain text link:

1. Click the ClashFX icon in the macOS menu bar.
2. Select Remote Config Management → Manage Remote Configs.
3. Click the + (Add) button.
4. Fill in the required fields:
   • Config Name: A clear label (e.g., Overseas-Primary).
   • Config URL: Paste your full subscription link (https://...).
   • Update Interval: Choose a schedule (e.g., 24 Hours).
5. Click Confirm / Save.
6. ClashFX will immediately download the remote profile. If the status changes to a checkmark, the profile is active and ready.

Method 3: Importing Local YAML Configuration Files

If you create your own configurations or need custom rule-providers:

1. Click the ClashFX menu icon.
2. Navigate to Config → Open Config Folder.
3. Finder will open ~/.config/clashfx.
4. Drop your .yaml or .yml configuration file directly into this directory (e.g., custom-mihomo.yaml).
5. Return to the ClashFX menu bar dropdown, hover over Config, and click your new file name to make it active.

ClashFX will parse the syntax and apply the nodes and rules immediately.

Managing and Updating Subscriptions

Manual Update

To fetch newly added nodes or updated credentials immediately:

• Click the ClashFX menu icon → Remote Config Management → Update All Profiles (or click the refresh icon next to a specific subscription).

Automatic Scheduled Updates

Inside Manage Remote Configs, specify an update interval in hours. ClashFX executes non-blocking background refreshes without interrupting existing active TCP/UDP connections.

Common Import Issues & Fixes

1. “Invalid Config / Parse Error”

If ClashFX reports a YAML parsing error when downloading a subscription:

• Modern protocols like VLESS, Hysteria2, or TUIC require the mihomo (Clash Meta) core. ClashFX natively runs the mihomo core, so it will handle modern protocols. If your provider generates malformed YAML headers, switch your provider portal format to Clash Meta. See our detailed guide on Fixing Subscription Import & YAML Errors.

2. “Connection Refused / Network Timeout”

If the subscription URL cannot be retrieved:

• Temporarily disable Set as System Proxy to ensure the download request isn’t looping back through a dead proxy node.
• Check if your proxy provider requires a direct domestic connection to fetch subscription links.

Next Steps

• Enable Enhanced Mode (TUN) to route all Mac traffic, including terminal applications.
• Customize your traffic rules and policies using the Built-in Config Editor.
• If you are switching from older ClashX builds, read our Migration Guide from ClashX.