Clash Subscription URL Import Guide: URL, YAML, and Base64 Formats

A URL is an address; YAML and Base64 describe content formats

When a Clash subscription fails to import, first check whether the URL is reachable and then whether its response can be parsed. A URL points to a remote resource; YAML is a configuration format; Base64 is an encoding. These are different layers, not three mutually exclusive subscription types. An HTTPS subscription URL may return a full YAML config, a Base64-encoded proxy list, or even a login page.

For clients running the mihomo core, use the Clash Meta or mihomo subscription endpoint specified by the provider. These labels indicate the intended compatibility, but the actual response fields must still be supported by your local core. A client saving a URL doesn't mean it can interpret the response.

Before importing, get the subscription URL and confirm core compatibility

1. Check which core the client uses. Look under “About” or in the core information section of “Settings” to see whether it uses mihomo. The GUI client version and core version are separate; record both when reporting compatibility issues.
2. Copy the dedicated URL from your provider’s account page. Choose an endpoint labeled Clash, Clash Meta, or mihomo. Don’t copy a plan page, login page, or the current browser address.
3. Keep the query parameters. Tokens and format parameters after ? may be needed for authentication or to select the response format. Don’t keep only the domain and path.
4. Remove stray characters added during copying. Delete leading or trailing spaces, line breaks, and curly quotes. Don’t alter percent-encoding, letter case, or parameter order within the URL.

Subscription URLs usually don’t end in .yaml. The server may choose the response format based on the path, query parameters, or request headers, so the filename doesn’t tell you whether it’s compatible. Being able to open an account page in your browser also doesn’t mean the client has the same login session when it requests the subscription endpoint.

If the URL has been exposed, reset the subscription token in your provider’s account page and replace the old URL in the client. Deleting chat messages or local configuration won’t revoke credentials that have already been copied.

Paste the URL into the client and activate the configuration

Button names vary by client, but the process boils down to four steps: create a remote config, download its contents, select the config, and choose a policy. The steps below use the common “Config” page. If your client calls it “Subscriptions” or “Profiles,” open the corresponding remote config list—not the proxy import field.

First-time import steps

1. Open “Configuration” and paste the full URL into the subscription field. If there’s no direct input field, choose “New” and set the type to “Remote.”
2. Give it a recognizable name, such as “Daily subscription,” then click “Import” or “Save.” Wait for the download to finish; don’t submit the URL repeatedly.
3. Check that the config card shows an update time. Click the card or choose “Use this config” to make it active. Downloading a config to the list may not activate it automatically.
4. Open “Proxies” and check that proxy groups and nodes appear. Select a node, run a latency test, then try accessing a site.
5. Enable the system proxy if needed. Configure TUN mode and grant its required permissions only if you need to capture traffic from apps that don’t follow the system proxy.

“Import successful,” “config active,” and “traffic routed through the proxy” are three separate checks. A successful import only means the file was retrieved and processed; it doesn’t prove that a node can connect. The system proxy or TUN mode captures traffic, while rules and proxy groups route it. Enabling TUN won’t fix an incompatible subscription format.

Fields to check after importing

• proxies or proxy-providers: Is there a source of nodes, and are their names displayed correctly?
• proxy-groups: Do the policy groups referenced by the rules exist, and does each group have selectable options?
• rules: Are the expected routing rules present, and is there a policy at the end to handle remaining traffic?
• Local listening port: Use the port shown in your client; don’t assume it’s 7890 just because another guide uses it.

How to tell a full YAML config from a proxy list

YAML describes structure, but that doesn’t guarantee the file is complete. A file containing only proxies: may be a node resource intended for a main config to reference, or it may require the client to add proxy groups and rules. That doesn’t necessarily make it invalid YAML, but used directly as the main config, it may lack the proxy selection interface or routing behavior you need.

Here’s a minimal config that illustrates how the pieces fit together. It provides only a direct-connection policy and has no remote nodes. Use it to understand the fields, not as a working proxy subscription.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

proxies: []

proxy-groups:
  - name: Select an exit
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,Select an exit

mixed-port: 7890 means HTTP and SOCKS share a local endpoint; mode: rule routes traffic according to rules. The final rule sends remaining connections to “Select an exit.” The group name must match the name in the rule. A client may override the port and mode at runtime, so check the effective configuration too.

If a remote resource is used with proxy-providers, the main config must define the provider and the proxy group must reference it with use. Updating a provider and updating an entire Profile are separate operations. Don’t paste a full main-config URL into a proxy-provider field, and don’t assume every Base64 list can be read directly as a provider by your current core.

Decoding Base64 doesn’t produce a full config

A common Base64 subscription decodes to a list of proxy URIs, one per line. Each line describes a node’s protocol, server, port, and authentication parameters, but usually doesn’t include rules, DNS, or proxy groups. Decoding restores the text; it doesn’t build the configuration structure Clash requires.

Another common source of confusion: a vmess:// URI may itself contain Base64-encoded data. That’s different from an entire subscription being Base64-encoded. Repeatedly decoding the whole text doesn’t replace parsing it according to its subscription format. The safest option is to get the dedicated mihomo endpoint from your provider again.

Enable auto-updates without losing custom rules

Enable auto-updates after the first import has been verified. Look for options such as “Auto-update” or “Update interval” under “Edit” or “Settings” on the config card. If the interval is in minutes, 360 means every 6 hours; if it explicitly requires seconds, use 21600 for the same interval. Don’t mix up the units.

1. Run “Update” manually first and confirm that the URL still works and the update time changes.
2. Choose a reasonable interval, such as every 6 hours. Follow your provider’s rate limits if specified.
3. Check for options such as “Update on launch” or retry on failure. Internal scheduled tasks usually won’t run while the client is closed, and may be delayed while the device sleeps.
4. After an update, check the selected node, proxy groups, and rules. If a node was renamed or removed, the previous selection may no longer be available.

Don’t make long-term edits directly to YAML downloaded from a remote subscription. The next update may overwrite them. If your client supports overrides, merges, or scripts, put custom content in the appropriate place and confirm it still affects the effective config after an update. Merge order varies by client; seeing a rule in the editor doesn’t prove it’s active.

Troubleshoot subscription import errors by type

What to do when the format isn’t compatible

First, look for the correct format endpoint on your provider’s site. Next, check whether the client has an explicitly labeled proxy-list import option. Only consider conversion as a last resort. A converter can handle only the protocols and fields it supports; it can’t fill in missing transport parameters, TLS settings, or rules.

Prefer conversion tools provided by your service or trusted tools that run locally. Submitting a tokenized URL to a public conversion service gives that service access to your subscription. Check the converted result for proxy types, transport settings, proxy groups, and rules. Being able to save the file doesn’t prove it’s compatible.

Three checks to run after importing

1. Verify the update flow. Run an update manually and note when it succeeds. If it fails, keep the old config and troubleshoot the subscription request first; don’t repeatedly delete and recreate a config that still works.
2. Verify the routing flow. Select a specific proxy group and node, open a target site, then check the matched rule, policy, and connection result in the connection log. A latency test returning a value doesn’t mean every site will be reachable.
3. Verify the traffic entry point. Check whether the target app follows the system proxy; configure TUN only if needed. Use the logs when checking the egress path—a connection matching a direct rule doesn’t prove the entire config is broken.

Once all three checks pass, set up scheduled updates and custom rules. Checking subscription retrieval, config parsing, node connectivity, and system traffic routing separately makes it easier to pinpoint issues such as “import succeeded, but I can’t get online.” For setup and port details, see the setup guide. For rule changes, see the custom rules guide.