Clash Subscription Link Formats Explained: Converting Between Base64, Clash YAML, and sing-box

What a subscription link actually is

The "subscription link" a proxy provider gives you isn't the proxy nodes themselves — it's an HTTP(S) address you can revisit repeatedly. The client requests this address on a schedule, gets back a block of text, and parses that text into a node list and (possibly) routing rules. The content returned behind the same subscription URL isn't uniform; it mostly depends on which panel software the provider runs, how it detects the client type, and whether the content passes through a conversion service. That's why the same subscription link works fine when pasted into Clash but throws an error in a bare-node-only client — the link isn't broken, the client simply can't parse the format it received.

Understanding these format differences lets you quickly narrow down where an import failure sits: the link itself has expired, the provider hasn't adapted for this client, or you need to route it through a conversion service first.

Three common formats and how to spot them

Base64 node list

The oldest and most universal format. Visiting the subscription link returns a Base64-encoded string; decoded, it's a series of single-node links like vmess://, ss://, ssr://, or trojan://, one per line. This format has no proxy groups or routing rules — the client just builds its own default groups from the node list. Almost every proxy client (not just the Clash ecosystem) can read this format, so it's the most compatible but also the most basic.

Clash YAML subscription

The returned content is a full YAML configuration containing proxies, proxy-groups, rules, and similar sections — structurally identical to a hand-written config.yaml. The provider's backend generates this file according to Clash's spec, and the client uses it directly: the routing strategy and proxy groups are already designed on the provider's side, ready to use out of the box. To spot it, open the link in a browser or a command-line tool — if it starts with YAML keywords like port:, mode:, or proxies:, it's this type.

sing-box JSON configuration

With the growing adoption of the sing-box core, some providers now offer an additional JSON-format subscription structured around sing-box's outbounds and route fields. This type can only be read by the sing-box core or clients compatible with its config structure — it can't be fed directly to a Clash-core client. A telltale sign is content starting with { and containing an "outbounds" field.

How subscription conversion services work

A subscription conversion service (a common open-source implementation is called subconverter) is essentially a middle-layer proxy: it first requests the original subscription URL with appropriate headers, gets the raw node data back, regenerates it in the target format, and returns that to your client. The full chain is "client → conversion service → original subscription URL → conversion service → client," and the conversion service does two things in the middle: format translation and rule-template application.

Format translation "translates" Base64 node lists, sing-box JSON, and other formats into a Clash YAML the client can read. Rule-template application lets you additionally specify a routing rule template (rule sets like ACL4SSR) so bare nodes get wrapped in a ready-made routing policy — the resulting subscription link already includes proxy groups and rules, no manual writing needed. In practice, you append the original subscription URL as a parameter to the conversion service's endpoint, then paste the endpoint's returned link into your client — operationally no different from adding a normal subscription.

https://your-converter-domain/sub?target=clash&url=original-subscription-link&config=rule-template-url

Note that the conversion service itself also needs network access to the original subscription URL. If the original subscription is only reachable under specific network conditions, the conversion step can fail for network reasons unrelated to whether the subscription has expired.

The basics of self-hosting a converter

Public conversion services come with two concerns — reliability and privacy: the endpoint might get rate-limited or shut down, and the original subscription URL (which usually contains an account-related token) passes through a third-party server. If reliability and privacy matter to you, self-hosting a converter is the alternative. The basic approach:

1. Prepare a runtime environment

   Get a server that stays online long-term, or a local device that's always powered on, and set up the runtime (subconverter ships as a precompiled binary, so no extra language runtime is needed).

2. Download the converter program and rule templates

   Get the subconverter binary along with the routing rule template files you plan to use long-term, put them in the same directory, and configure the listening port per the project's included setup instructions.

3. Start the service and verify it

   Once started, visit http://127.0.0.1:port/sub?target=clash&url=test-subscription-url from a local browser to confirm it returns valid YAML.

4. Switch to your own converter address

   Replace the public conversion service's domain with your own server's address (pairing it with a reverse proxy for HTTPS is recommended). From then on, all subscriptions get converted through your own service, and the original subscription URL never touches a third party.

The main ongoing maintenance cost of self-hosting is keeping rule templates updated: routing rules keep changing as services evolve, and leaving templates stale for a long time degrades routing accuracy — sync with the upstream rule repository periodically.

Format compatibility across clients

The table below summarizes direct support for the three subscription formats across common clients, assuming no conversion service is used:

As you can see, Clash YAML only works across the Clash core family — feeding it to a sing-box-core client fails to parse outright; conversely, a sing-box JSON subscription can't be imported directly into a Clash client either. Whenever you're using nodes across different cores, subscription conversion is a required step, not an optional one.