Clash Subscription Formats: YAML, Base64 Links & Conversion

Identify the content first: a subscription URL is not a format

If a Clash subscription fails to import, check what the server returned before deciding whether to convert it. A subscription URL beginning with https:// is just an access point. The response might be a complete YAML config, a Base64-encoded list of proxy links, a login page, or an error message. A file named clash.yaml is not necessarily a valid config, and a client’s “subscription” feature does not mean it accepts every proxy format.

This guide focuses on Clash clients that use the mihomo core. mihomo is the project that followed Clash Meta; support for protocols and import methods varies across legacy Clash cores and graphical clients. Check separately whether the core can run the proxy and whether the interface can parse the share link. The client’s name alone is not enough to tell.

Clash YAML: proxies and routing config in one document

YAML is a structured text format, not a proxy protocol. proxies defines proxies, proxy-groups organizes them into groups, and rules determine which policy handles each connection. A complete config can also set mixed-port, dns, and tun. When generating YAML from proxy links, a conversion template or local config must supply these additional settings.

Complete config example: one Shadowsocks proxy

This is an example of a complete config structure, not a working subscription. proxy.example.com is a reserved example domain, and the password is for demonstration only. For real use, replace them with the server address, port, cipher, and password provided by your service. This config does not enable TUN or define custom DNS settings.

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

proxies:
  - name: SS example
    type: ss
    server: proxy.example.com
    port: 8388
    cipher: aes-128-gcm
    password: "password"
    udp: true

proxy-groups:
  - name: Manual selection
    type: select
    proxies:
      - SS example
      - DIRECT

rules:
  - IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - MATCH,Manual selection

• 7890 is the local HTTP/SOCKS mixed-proxy port; 8388 is the remote proxy port. They are not interchangeable.
• SS example must match exactly in both the proxy definition and the proxy group reference, including spaces.
• MATCH is the catch-all rule and should come after specific rules. This only demonstrates rule order; it is not a complete routing setup for mainland China and destinations outside China.
• Use spaces for indentation, not tabs. Quote passwords to prevent YAML from interpreting special characters as syntax.

If you only have a proxy list, consider using proxy-providers

If you maintain your own routing rules over time, keep the main config stable and update only the proxy provider. This reduces the impact of subscription updates on your local rules. The following snippet must be merged into an existing main config. The local file ./providers/nodes.yaml should contain a top-level proxies: field and a list of proxies.

proxy-providers:
  Local proxies:
    type: file
    path: ./providers/nodes.yaml

proxy-groups:
  - name: Subscription selection
    type: select
    use:
      - Local proxies

The file path depends on the core’s working directory and how the client manages files; it may not be your downloads folder. Make sure the main config’s rules point to Subscription selection. A file containing only proxies is not a complete config with routing rules already set up.

Base64 subscriptions: encoded, not encrypted

A common generic subscription combines multiple share links into one text block and Base64-encodes it. Decoding gives you a list of proxy links, not a ready-made Clash YAML config. Some services return plain-text links instead, so inspect the content first rather than blindly decoding every subscription.

What you’ll usually find after decoding

Here are two sample links. They use an example domain and demo password and cannot connect to a server. The first link’s user info decodes to aes-128-gcm:password; the second uses sni to specify the server name for TLS.

ss://[email protected]:8388#SS-demo
trojan://[email protected]:443?sni=proxy.example.com#Trojan-demo

1. Read the subscription text locally and check whether it is already YAML or a list of plain-text share links.
2. Decode it only after confirming it is Base64. Common variations include a URL-safe alphabet and omitted trailing padding; importers need to handle these differences.
3. Identify the protocol on each line, then map parameters such as server, credentials, and transport to YAML proxy fields.
4. Add proxy groups and rules, check that the target core supports every field, and only then import the config.

A decoding error may mean the server returned an HTML page, such as a login page after a redirect or a rate-limit notice. Check whether the subscription has expired, the response status, and the returned content instead of stacking more decoding steps. Changing the file extension or repeatedly encoding the data will not fix an authorization problem on the server.

ss, vmess, and trojan: fields to preserve during conversion

Share links do not follow one universal container format. A protocol may have several link formats, and converters vary in which query parameters they support. A successful conversion preserves the connection semantics; it does more than produce syntactically valid YAML.

Shadowsocks: keep the two encoding layers straight

Common SIP002 links encode the user info before @; older share links may encode a longer section. A generic subscription may add another layer of Base64 around the links. Distinguish encoding of the entire subscription from encoding within an individual link. If a link includes plugin parameters, copying only the server and password may drop the transport settings needed to connect.

VMess: decoding the JSON is only the first step

A typical vmess:// link contains Base64-encoded JSON. add usually maps to the server, id to the UUID, aid to alterId, and net to the transport. Modern VMess AEAD configs typically use alterId: 0, but don’t force that value onto every legacy config.

If the source proxy uses WebSocket, check ws-opts.path and ws-opts.headers.Host. The TLS server name and WebSocket Host serve different purposes; don’t merge them just because their values sometimes match. For gRPC, also check grpc-opts.grpc-service-name. Whether the converter preserves it matters more than how polished the proxy label looks.

Trojan: decode URI parameters correctly

Passwords and labels containing special characters may be percent-encoded in share links. An importer should parse them according to URI rules instead of splitting everything at colons or hash signs. After conversion, check that the password, SNI, and ALPN are preserved. For certificate errors, first verify the system time and server name; don’t use skip-cert-verify: true as a default fix.

Converting between formats: proxies can be exported, rules may not be recoverable

“Convert a Base64 subscription to Clash” usually means extracting the proxies and applying a config template. “Convert Clash to a generic subscription” usually exports only proxies that can be represented as share links. These are not fully reversible conversions: proxy groups, rule order, DNS, TUN settings, and some core-specific parameters generally have no equivalent fields in generic share links.

How to choose a conversion method

1. Use the native format first: In your provider’s subscription dashboard, choose a Clash/mihomo format supported by your target core to avoid an extra conversion step.
2. Enter a few proxies manually: Fill in each protocol field, ideal for one or a few proxies and useful for checking TLS and transport settings.
3. Convert batches locally: Confirm the tool supports the source protocol and target core, then check the proxy count, fields, and warnings after conversion.
4. Be cautious with online converters: Check who operates the service and how it handles data. Never embed a tokenized subscription URL in public documentation or a public config repository.

• If 12 proxies go in and only 9 come out, check for unsupported protocols, duplicate-name handling, and filter settings before replacing your existing config.
• Giving every proxy the same name can break proxy group references. If you rename proxies, update the group references too.
• A config that uses a remote proxy-providers may not automatically expand the provider’s proxies during export. Check exactly what data the tool reads.
• Changing the conversion template can alter rules and proxy groups. Keep a local copy of the original so you can compare changes and restore it if needed.

If you want to keep your rules and only update the provider’s proxies, consider proxy providers or your client’s override features instead of converting the entire config back and forth each time. Check how your client handles edits to remote configs; some changes are overwritten the next time the subscription updates.

Importing and troubleshooting: check the format before the connection

In the common Clash Verge Rev interface, add a complete remote config by going to “Subscriptions” → “New,” entering the subscription URL, then saving, updating, and selecting the profile. Import local YAML from the file import option on the same page. Button labels vary by version, so follow the current interface. Other clients may call this section “Configuration” or “Profiles.” Don’t confuse the single-proxy import screen with the full-config import screen.

Check these four things after importing

1. Confirm the config is active: Check which config is selected on the subscription or configuration page. A successful download does not mean the core has loaded it.
2. Check the parsed result: Open the “Proxies” page and verify the proxy groups and proxy count, then select the proxy you need. An empty group usually points to a broken proxy reference or a provider loading problem.
3. Check the local proxy port: Verify the actual mixed port in settings. This guide uses 127.0.0.1:7890; your client may use a different port, so don’t overwrite it with this example.
4. Check the logs: Fix YAML parsing errors, unknown proxy names, and provider read errors first. Then investigate authentication failures, TLS errors, or connection timeouts.

FAQ: file extensions, QR codes, and subscription updates

Can I rename Base64 text to .yaml and import it directly?

Renaming the file does not convert it. The extension does not change the content structure; you need to decode and parse the proxies, then generate YAML that meets the target core’s requirements. If your client has a built-in generic subscription parser, it can do this for you—but that is an extra client feature, not something a YAML parser does by default.

How are QR codes related to share links?

A QR code usually stores a share link as text, but it may also contain a subscription URL. After scanning, check whether you have a single-proxy link or a remote subscription URL, then choose the right import screen. QR codes can expose passwords or tokens too, so protect them just like text credentials before sharing.

Will proxies update automatically after I save them to a local file?

A one-time local YAML export will not know when the source subscription changes. You’ll need to convert and import it again, or use a remote config or HTTP proxy provider that supports scheduled updates. Automatic updates depend on the update URL and scheduling method saved by the client, not on whether the file contains the word “subscription.”

Which format should I save in?

To use proxies, proxy groups, and routing rules together, save a complete Clash/mihomo YAML config. To keep your own rules stable over time, save the main config and maintain the proxy provider separately. To move proxies between compatible clients, use share links or a generic subscription. Choose based on what information you need to preserve, not on which encoding looks more complex.