Clash Subscription Formats: Convert Between YAML, Base64, and Proxy URIs

Subscription URLs, encoding, and configuration formats

A subscription URL is an address for retrieving content, YAML is a data format for describing configuration, Base64 is an encoding scheme, and a proxy URI represents a single proxy. These concepts operate at different levels. A subscription URL starting with https:// might return a complete YAML file or multiple proxy links encoded in Base64.

To determine whether Clash can import a subscription, focus on the response body’s structure and whether the client’s core can parse it—not whether the URL ends in .yaml. Some services return different content based on the request’s User-Agent, so what you see in a browser may differ from what the client receives when updating a subscription.

Clash YAML: Complete Configurations and Proxy Lists

YAML uses key-value pairs and indentation to represent structure. Here’s a minimal configuration to show how the fields relate: the local mixed proxy port is 7890, while the proxy server port is 8388—they serve different purposes. The example domain and password illustrate syntax only; they don’t provide a working proxy.

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

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

proxy-groups:
  - name: "Proxy Selection"
    type: select
    proxies:
      - "Example SS"
      - DIRECT

rules:
  - MATCH,Proxy Selection

What the three core fields do

• proxies defines connection parameters, including the protocol, server, port, and authentication details.
• proxy-groups defines how to select proxies. In this example, select lets you choose “Example SS” or DIRECT manually.
• rules determines which policy handles a connection. Here, MATCH,Proxy Selection is the final catch-all, not a rule set that distinguishes by location or domain.

YAML containing only proxies is not a complete configuration. It works as a data file for a proxy provider; even if a client lets you import it directly, that doesn’t mean it includes a complete routing policy. Auto-completion, configuration merging, and overrides depend on the client, so check each separately.

If YAML parsing fails, check indentation and strings first

Use spaces for indentation; don’t mix in tabs. Quoting proxy names is a good idea, especially when they contain characters such as colons or hash marks. Passwords should also be quoted to prevent some values from being interpreted as numbers or booleans. After editing, check both the YAML structure and core compatibility: successful YAML parsing doesn’t mean the current core supports every proxy field.

Base64 and URIs: Decode first, then identify the protocol

Many Base64 subscriptions concatenate multiple URIs, one per line, and then encode the result as a whole. To convert one, first decode the text, then identify the protocol on each line. Some services return a plain-text list of URIs, so don’t assume every subscription needs to be decoded.

Example: a Shadowsocks share link

Here’s a common SIP002 format: the authentication section is Base64-encoded, while the server and port remain visible outside it. Decoding the authentication section YWVzLTEyOC1nY206dGVzdA== gives aes-128-gcm:test.

ss://[email protected]:8388#demo

• ss:// specifies the Shadowsocks protocol.
• The authentication section contains the encryption method aes-128-gcm and password test.
• node.example.com:8388 gives the server address and port.
• #demo is the display name, not the server password. It isn’t sent to the subscription server as part of the HTTP request.

Older SS share links may also encode the server address; links with plugins may include a plugin parameter. You can’t parse every variant by splitting at one fixed @ position. Trojan, VMess, and VLESS share links also use different structures. For example, the encoded body of a common VMess link is JSON, not an SS-style authentication string.

Names and encoding variants

Proxy names often use percent encoding. For example, %E9%A6%99%E6%B8%AF in a URI fragment represents “Hong Kong.” Percent-decoding and Base64 decoding are separate operations, and the correct order depends on the protocol. Base64 may also use URL-safe characters such as - and _, or omit trailing = padding. A parser should recognize these variants rather than treating missing padding as proof that a link is malformed.

Subscription conversion: parsing, mapping, and generation

A converter typically fetches the original subscription, parses its proxies into an internal data structure, and then generates the target format. To create a complete Clash configuration, it may also apply a template that adds proxy groups, DNS settings, and rules. So “converting Base64 to YAML” isn’t just changing the text wrapper—it involves mapping fields and generating configuration.

1. Fetch the source: Check the HTTP status and response body. Rule out a login page, expiration notice, rate-limit page, or CAPTCHA.
2. Identify the input: Distinguish complete YAML, provider YAML, plain-text URI lists, and encoded subscriptions.
3. Parse the proxies: Extract the protocol, address, port, authentication details, and TLS and transport parameters.
4. Choose the target: Output fields supported by the actual core; don’t rely on whether the client’s name includes Clash.
5. Apply a template: Generate proxy groups and rules, then check references to proxy and group names.

Understanding common conversion parameters

The examples below use a common subconverter-style API. These parameters aren’t an industry-wide standard, and defaults vary by implementation and version. Check the documentation for the service you’re using.

Assume a conversion service is already running locally and listening on 127.0.0.1:25500. The example below shows how the parameters are nested and encoded. This address illustrates the API only; installing a client won’t automatically provide a conversion service.

http://127.0.0.1:25500/sub?target=clash&url=https%3A%2F%2Fsubscription.example.com%2Ffeed%3Ftoken%3Ddemo&list=false&emoji=false&udp=true

The inner URL is https://subscription.example.com/feed?token=demo. If the source URL also contains &type=all, the ampersand must be encoded as %26 too; otherwise, the conversion service will treat it as one of its own parameters. Don’t encode the entire outer URL again and use it as a subscription URL.

Conversion limits: proxies may carry over, but routing may not

A URI usually carries a single proxy, while a complete YAML configuration can include rules, proxy groups, DNS, TUN, and proxy-provider definitions. When you export a complete YAML file as a list of URIs, those global settings usually can’t be represented. Converting the URIs back to YAML creates a new configuration from a template—it doesn’t fully restore the original.

New protocols need support from both the core and the converter

The original Clash, Clash Meta, and mihomo differ in the protocols and fields they support. Hysteria2 is one example: the source having a Hysteria2 proxy doesn’t mean a conversion target for an older core can preserve it. Three things must line up: the converter recognizes the input protocol, the output format can represent its fields, and the running core can load and use them.

• TLS settings: Check SNI, certificate verification, and ALPN. Don’t disable certificate verification just to get the configuration imported.
• Transport settings: Preserve WebSocket paths and headers. Dropping a path can leave a proxy looking fine while causing the handshake to fail.
• Extensions: Check multiplexing, fingerprints, Reality, and other settings individually. Fields with the same name don’t necessarily mean the same thing in every core.
• Name references: If you rename a proxy, update its references in proxy groups too. Duplicate proxy names can cause validation failures or unexpected selections.

If the original service provides YAML compatible with your current mihomo core, use that format directly when possible. Add a conversion step only when the input format is incompatible, you need centralized template management, or you need to combine sources. Fewer conversion steps mean fewer opportunities to lose fields.

After conversion: verify everything from import to connectivity

A successful import only means the configuration passed one stage of parsing. Keep the original configuration and save the converted result as a separate file. Then verify it in the order below, so you don’t lose a working way to recover if a replacement fails.

1. Check the proxy count: For example, if the source subscription has 12 proxies but the output has only 8, check filters, protocol support, and parsing logs before using it.
2. Check key fields: Pick at least one proxy and compare its server, port, protocol, authentication, and TLS settings. Don’t assume matching names mean the details match.
3. Check the core configuration: If mihomo is installed as a command-line program, run the test command below. Use the executable name and path for your installation.
4. Check proxy groups: Make sure the group contains the intended proxy and the final rules reference an existing policy—not one the template unexpectedly changed to DIRECT.
5. Check the actual connection: Test the proxy, then check the connection list for the destination domain, matched rule, and final route. A single latency test can’t prove that every website and UDP app will work.

mihomo -t -f converted.yaml

This command tests the configuration; it doesn’t prove the remote server is reachable. If the configuration references external providers or rule resources, testing may also load those resources. If an error says a field isn’t supported, check the core’s capabilities first. If it reports an unknown proxy name, check proxy-group and rule references. For YAML parsing errors, start with indentation, quotes, and list structure.

If it imports but won’t connect: a troubleshooting order

• If all proxies fail, check the network, whether the subscription has expired, and whether the conversion applied the wrong template across the board.
• If only one protocol fails, check core support for that protocol, its transport settings, and the converter version first.
• If a proxy test succeeds but websites fail, check rule matching, DNS resolution, and whether the application is sending traffic through the proxy.
• If the browser works but a game doesn’t, investigate UDP, the application’s proxy method, and TUN routing. Changing the subscription encoding alone won’t fix it.

Subscription privacy, update URLs, and FAQs

Will proxies update automatically after conversion?

Importing a local YAML file usually imports a snapshot from that moment; it won’t go back to the original subscription for new proxies. If you import a remote URL produced by a converter, the client requests that URL again when it updates. Whether the converter fetches the source subscription in real time depends on its caching policy. Keep a record of the source URL, target format, and template settings so you can tell whether the source hasn’t updated or the conversion cache hasn’t refreshed.

Why does the browser show a long string of gibberish?

If the response body is mostly letters, numbers, and a few encoded symbols, it may be Base64. Decode it locally to check the contents. If the body starts with HTML tags or shows a login, quota, or access restriction notice, it isn’t a valid proxy configuration. Don’t try to convert an error page, and don’t treat an “HTTP 200” response alone as proof that a subscription is valid.

Is it safe to share a subscription URL to get help troubleshooting?

Avoid sharing the complete URL. You can share the protocol name, error text, and configuration snippet after removing credentials. If a token has been exposed, reset the subscription URL on the service side; deleting it from your local device won’t invalidate the old token. Update the source URL saved in your clients and conversion services as well.

The decision comes down to three steps: identify the response body, confirm the target core, then check the converted fields and connection. Encoding changes how text is represented; conversion maps between formats; and a rules template determines where traffic goes. Treating these as separate concerns makes troubleshooting more straightforward.