Clash Subscription Formats: YAML Configs, Base64 Proxies & Conversion

Check the response before choosing an import method

A Clash subscription link is an address for retrieving a config; YAML or Base64 describes the format of the response. A link opening in your browser doesn't mean Clash for Apple can import it directly. Prefer a Clash or mihomo subscription explicitly provided by your service. Use a converter only when you have a generic proxy subscription. An Apple silicon Mac needs the arm64 client, but that doesn't change the required subscription format. On iPhone and iPad, also check which protocols and config fields the app supports.

Check the response body rather than judging by whether the link ends in .yaml. The same URL may return different content depending on query parameters or the request User-Agent. A browser might also receive a login page instead of the config the client gets.

YAML configs: what proxies, proxy groups, and rules do

YAML is structured text; listing proxies line by line isn't a complete config. Clash-family cores typically use proxies to define proxy nodes, proxy-groups to organize selectable outbound routes, and rules to direct traffic. External proxy lists are added with proxy-providers; external rule lists are declared with rule-providers and referenced by rules.

A readable minimal config structure

This config demonstrates the structure only; all connections go direct and no remote proxy nodes are included. 7890 is a mixed-proxy port chosen for this example, not a default for every client. allow-lan: false and the loopback listener prevent other devices on your local network from using this endpoint.

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

proxies: []

proxy-groups:
  - name: Manual Select
    type: select
    proxies:
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.com,Manual Select
  - MATCH,DIRECT

• proxies: Defines proxy type, server address, port, and authentication or TLS details. Available fields depend on the core.
• proxy-groups: Defines routing choices. Every group referenced by a rule must exist; update references when you rename a node or group.
• rules: Rules are usually matched from top to bottom. The first match determines the policy; a final MATCH acts as a catch-all.
• dns and tun: Control DNS resolution and virtual network interface behavior. Not every subscription needs them, and you shouldn't add them blindly just to make a config seem complete.

YAML uses spaces for indentation, not tabs. Quote strings properly when node names contain special characters such as # or a colon followed by a space. A YAML parser accepting the file confirms only that its syntax is readable; the core must still validate proxy types, field values, and policy references.

Base64 subscriptions: encoding isn't config or encryption

Many generic subscriptions join proxy URIs with newlines, then Base64-encode the text. Decoding may reveal proxy details for protocols such as Shadowsocks, VMess, or Trojan. Formats vary by provider: some return a plain URI list, some use URL-safe Base64, and some omit trailing padding. Don't identify a subscription by appearance alone.

Check saved content locally on macOS

1. Save the raw response you want to inspect as a local text file named nodes.b64. Don't save a login page as the subscription body.
2. In Finder, open the folder containing the file, then use Terminal to switch to that directory. Make sure it isn't in a shared folder.
3. For standard Base64 content, run this command to write the decoded result to a separate file, preserving the original response.

base64 -D < nodes.b64 > nodes.txt

These are the decoding options for macOS's built-in base64 command. If it reports an error, the output file may be incomplete; don't try to import it. First check whether the source is already plain-text URIs or uses URL-safe characters or omitted padding. If compatibility handling is needed, use a local tool that explicitly supports that variant. Don't delete characters at random.

Successful decoding doesn't prove that the proxies are valid. Base64 doesn't provide confidentiality, and the decoded nodes.txt may contain passwords, UUIDs, and server details. Handle both the original and decoded files carefully, and don't share them through cloud drives or support-ticket attachments.

Subscription conversion workflow and common parameters

A converter typically fetches the source subscription, parses proxies, filters or renames them, maps protocol fields to the target format, applies a template, and generates the output. It can't upgrade the core or make an older core support a new protocol, and it can't recover rules the provider never supplied.

Choose the target core before the output format

1. Check the client core. Find the core name and version in the app's About or core information screen. The app version and core version are separate details; knowing that an app supports macOS or iOS isn't enough.
2. Prefer a native subscription. If your provider offers separate Clash and mihomo endpoints, choose the one that matches your target core to avoid unnecessary conversion.
3. If conversion is necessary, use a trusted environment. Prefer running it locally or on a server you manage. Third-party converters can read the source subscription and proxy credentials; HTTPS protects data in transit only.
4. Confirm what the output contains. Distinguish a complete config from a proxy list, then choose the configuration import option or proxy provider option accordingly.
5. Keep the original config and test first. Add the new config without overwriting the one in use. Check the proxy count, policy groups, final rules, and connection logs before switching.

Common parameters in the subconverter API

These are common parameter meanings, not a universal standard for every converter. Check the documentation and version of the instance you use, and don't assume every instance supports an output target named mihomo.

If the source URL contains &, appending it directly after the converter's url= parameter may cause the remaining URL to be parsed as converter parameters. Use a trusted tool to encode the URL correctly once; avoid manual concatenation or double encoding. The conversion URL may also contain the original token, so treat it as sensitive information.

Missing rules after conversion: check output, template, and override order

“Proxies connect, but every site uses the same route” doesn't necessarily mean rules were deleted. You may have only a proxy list, the config may not be active, the client may be in Global mode, or a template may have replaced the original rules. Check each possibility separately instead of repeatedly changing proxies.

Step 1: Check the conversion output

• Look for top-level rules: and proxy-groups:. If you see only proxies:, first check whether list-only output is enabled.
• If the rules use RULE-SET, check that the corresponding rule-providers entry exists and that its remote resource downloaded successfully.
• Check that each policy named in a rule exactly matches a policy group, including spaces, capitalization, and any renamed characters.
• Check where the catch-all rule appears. An early MATCH,DIRECT leaves later rules with no chance to match.

Step 2: Check whether the conversion template replaced upstream rules

The rules in the output may differ from those in the original complete YAML. Some conversion workflows extract only the proxies, then rebuild the config from their own template. Save and compare the before-and-after files, focusing on rules, proxy-groups, dns, and provider declarations. If the provider already supplies a suitable complete config, importing it directly is usually more likely to preserve its original behavior.

Step 3: Check the config the client is actually running

Make sure the newly imported config is selected and the client is in Rule mode, not Global or Direct mode. Then check the client's overrides, merges, scripts, or enhanced config features; local settings may modify the config again after a subscription update. Editing only the cached subscription file may not survive the next update. For persistent changes, use an override mechanism explicitly supported by the client.

Finally, open the connection log and check the matched rule and final route for a specific domain. A website's displayed region, proxy latency, or whether a page loads can't prove on its own that the rules are working. If the log shows the correct rule but access still fails, check DNS, proxy reachability, and restrictions imposed by the destination service.

Post-import checklist for Mac, iPhone, and iPad

Apple devices can use the same subscription source, but not every client supports every field in a given config. In particular, don't assume mihomo extensions, rules, or DNS options are compatible just because the file has a .yaml extension.

1. Check the import type. Use the remote config option for a complete config; use the node or proxy provider option for a proxy list, if supported by the app. Menu names vary by client. Don't use a rule-set URL as a proxy subscription.
2. Check the config source. Make sure the subscription URL wasn't truncated when copied, contains no extra punctuation, and uses a valid access token. If you get HTTP 401 or 403, fix authorization before changing the YAML.
3. Check the listening port. This example uses 127.0.0.1:7890; your app may use a different port. Before enabling the system proxy, check the listening address shown in the client so your browser isn't pointed at an inactive port.
4. Test traffic capture and routing separately. The macOS system proxy affects apps that honor proxy settings; TUN uses a virtual interface to receive routed traffic. iOS typically captures traffic through a system VPN configuration. Subscription conversion doesn't grant these permissions.
5. Test a remote update. After the first successful import, run an update manually. Check that local overrides remain in place, proxy filters haven't emptied the list, and policy references still work.

Subscription format FAQs