Clash Subscription Formats Explained: YAML, Base64 Links, and SIP008

First, distinguish subscription URLs, content formats, and proxy protocols

A “subscription import failed” message doesn’t necessarily mean the URL is invalid. A link might return Clash YAML, a Base64-encoded list of proxy nodes, or even a login page. After downloading the content, the client must identify its structure, parse the nodes, and pass them to the core to establish connections. A mismatch at any step can cause an import failure or leave nodes unusable.

When troubleshooting, check these three layers separately instead of repeatedly clicking “Update subscription.”

• Subscription URL: The HTTP or HTTPS address used to download a configuration. A .yaml suffix in the URL doesn’t prove that the response is YAML.
• Content format: The structure used to store nodes and configuration, such as YAML, a Base64-wrapped list of URIs, or SIP008 JSON.
• Proxy protocol: The protocol used for the actual connection, such as Shadowsocks, VMess, or Trojan. Converting formats doesn’t turn one proxy protocol into another.

YAML: a full configuration isn’t the same as a proxy provider

YAML is a configuration format, not a proxy protocol. A full Clash-style configuration typically includes fields such as proxies, proxy-groups, and rules; it may also reference external nodes through proxy-providers. Beyond server addresses and passwords, it can define proxy group selection, rule order, DNS, listening ports, and more.

A full configuration can include routing rules

This example shows the structure. The domain and password are for demonstration only and won’t connect to a server. mixed-port: 7890 sets the local mixed-proxy listening port; it is not the remote server port.

mixed-port: 7890
allow-lan: false
mode: rule
proxies:
  - name: "Sample SS node"
    type: ss
    server: node.example.com
    port: 443
    cipher: aes-128-gcm
    password: "demo-password"
proxy-groups:
  - name: "Proxy selection"
    type: select
    proxies:
      - "Sample SS node"
      - DIRECT
rules:
  - DOMAIN-SUFFIX,example.org,DIRECT
  - MATCH,Proxy selection

Here, 443 is an example remote port. Rules are matched from top to bottom: traffic to example.org and its subdomains goes direct; other connections are handled by the “Proxy selection” group. If the import shows a node but no corresponding proxy group or rules, check whether the client imported the source as a list of nodes rather than as a full configuration.

A file containing only proxies may be provider content

Proxy provider files often store a node list under the top-level proxies: key. The main configuration loads it through proxy-providers, then references it from a proxy group with use. Since it doesn’t include a complete routing policy, don’t assume it’s a ready-to-use full configuration just because it’s YAML.

Conversely, don’t paste a full configuration into an import field that accepts only a node list. To keep local rules while updating provider nodes, use a provider or override feature supported by your client instead of manually reworking the entire remote configuration after each update. See the protocol reference for setup details.

Base64: a list of proxy links wrapped in an encoding

A “Base64 subscription” usually means multiple proxy URIs arranged on separate lines and then Base64-encoded as a single text block. Decoding it may reveal links beginning with ss://, vmess://, or trojan://. Some subscriptions return these links in plain text, without an outer encoding layer.

• Base64 is not encryption: Anyone who obtains the content can usually recover server addresses, credentials, and node names.
• Individual node links may contain additional encoding: For example, a URI’s credentials or payload may also use Base64. Decoding the outer subscription layer doesn’t mean every field is now in plain text.
• Support for extended fields varies: The importer and core must both support transport, TLS, plugin options, and newer protocol fields for them to be preserved correctly.

Base64 is only an outer wrapper and usually doesn’t include Clash rules or proxy-groups. If a conversion to Clash configuration adds “URL-test,” “failover,” or routing rules, they most likely come from the conversion template—not from the original node list.

SIP008: a structured server list for Shadowsocks

SIP008 is a convention for delivering online configurations in the Shadowsocks ecosystem. It uses JSON to represent a server list. It’s not a universal subscription standard for all proxy protocols, and it doesn’t define Clash policy groups or domain rules. Common SIP008 v1 documents include version and servers fields; each server entry lists an address, port, encryption method, password, and remarks.

{
  "version": 1,
  "servers": [
    {
      "id": "c71e2e80-925f-4cf6-a437-ef9b79e9cb17",
      "remarks": "Sample SS node",
      "server": "node.example.com",
      "server_port": 443,
      "method": "aes-128-gcm",
      "password": "demo-password"
    }
  ]
}

When converting to a Clash node, server_port is typically mapped to port, method to cipher, and remarks to name, with type: ss added. That’s field mapping, not protocol conversion.

If an entry includes plugin and plugin_opts, check whether the target core supports the plugin and its option syntax. A converter producing YAML doesn’t guarantee that the plugin handshake will work. The connection will succeed only if the server supports the corresponding connection method and the client is configured correctly.

Which formats can Clash clients import directly?

Distinguish between “the core can read this configuration” and “the graphical client can convert it.” Clash and mihomo primarily use Clash-style YAML configurations. Some graphical clients also support importing share links, detecting subscriptions, or combining them with templates. Support for Base64 in one client doesn’t mean every Clash client can import it.

Menu labels vary between clients. First distinguish “Import configuration file,” “Add remote configuration,” and “Import nodes.” Don’t paste a node share link into a field that accepts only HTTPS subscription URLs. If you’re setting things up for the first time, follow the quick-start guide to import a configuration, then address any format compatibility issues.

What gets lost in subscription conversion: information beyond the nodes

“Conversion successful” only means the target file was generated; it doesn’t guarantee that the original configuration was fully preserved. First check whether the source format can represent the information you need, then verify what the converter actually retained.

Converting full YAML to proxy links

• Rules and their order: Rules such as DOMAIN-SUFFIX, IP-CIDR, and MATCH generally aren’t included in individual node URIs.
• Proxy group relationships: Group hierarchies using select, url-test, and fallback, along with test URLs and intervals, usually can’t be preserved.
• Local runtime settings: DNS, TUN, listen addresses, mixed ports, and controller interfaces aren’t part of shared node details.
• External references: Rule sets, proxy providers, and their update policies may be ignored on export, or reduced to a snapshot of the nodes available at that moment.

Converting a node list to full YAML

A converter has to decide which group to put the nodes in, which domains should go direct, and where unmatched traffic should go. The results vary by template. Two configurations generated from the same nodes may route traffic to the same website through different proxies because their rules differ—not because the nodes changed.

Node names are worth checking too. Renaming, deduplication, or grouping by region can break references in existing rules. Some names are URI-encoded and must be decoded correctly during conversion. If an import reports “proxy not found,” compare the names referenced in proxy-groups and rules before deleting all your rules.

Conversion can’t add capabilities the server doesn’t have

Rewriting a Shadowsocks entry with Trojan or other protocol fields won’t make the original server support that protocol. Likewise, if the source lacks a server name for TLS, a transport path, or required credentials, a converter can’t infer them. Get the correct subscription from the provider instead of adding random parameters until the file saves.

A repeatable workflow for identifying and converting subscriptions

1. Keep the original source: Record the subscription format and retrieval date, and back up your current working configuration. Don’t test by overwriting your only copy of an existing configuration.
2. Check the response: Verify that the download succeeded. A response starting with <!DOCTYPE html> or a login form is a web page, not a usable proxy configuration—even if the HTTP status is 200.
3. Check the structure, not the filename: Top-level fields such as proxies: usually indicate YAML. JSON containing version and servers may be SIP008. A long encoded text block needs to be decoded and inspected locally.
4. Prefer a native subscription: If the provider offers a Clash or mihomo format for your core, download that instead. Consider a trusted local or self-hosted converter only when no suitable option is available.
5. Preserve the update path: An exported YAML file is a snapshot; it won’t automatically receive updates from the original subscription URL. A remote conversion URL may depend on the conversion service remaining available and expose your original subscription to that service.
6. Verify the result after import: Compare the source and target node counts, protocol types, proxy groups, and final fallback rule. Then test one destination that should go direct and another that should use a proxy.

For example, if the source contains 12 entries and the target has only 9, check whether the other 3 were skipped because of unsupported protocols, missing fields, duplicate filtering, or name conflicts. This is an example of how to check—not an expected loss rate. A correct conversion shouldn’t silently drop nodes for unexplained reasons.

Troubleshooting import failures and subscription updates

YAML syntax errors

Check the indentation, colons, and quotes near the reported line first. YAML uses spaces for indentation; tabs aren’t valid substitutes. The example password is quoted to prevent special characters from being interpreted as syntax. If the response is actually JSON or HTML, changing YAML indentation won’t help—check the subscription source instead.

Configuration imports, but there are no nodes or connections fail

First check whether the file contains only provider data and whether the main configuration references it. If nodes are present but won’t connect, check the core logs for errors such as “unsupported proxy type,” “unknown cipher,” or invalid plugin options. A valid format doesn’t guarantee a working connection, which also depends on server status, network routing, and account validity.

Rules revert after the next update

Remote configuration updates usually replace the downloaded content. Edits made directly to a remote file may be overwritten by the next update. To keep rules, put them in an override, merge, or separate main-configuration mechanism supported by your client, and check the final load order. Rules are matched from top to bottom, so appending custom rules after MATCH usually won’t work as intended.