How to Import a Clash Subscription URL: Identifying and Handling URL, Base64, and YAML Formats

First, distinguish subscription URLs, node lists, and Clash YAML

A “subscription URL” is first and foremost a URL, not a fixed file format. The server returns the actual content only after a client requests that URL. The response may be a complete Clash YAML file, a YAML file containing only nodes, a Base64-encoded generic node list, or even a web page, JSON error, or expired-link notice. Whether it can be imported directly depends on whether the client can process the final response.

The configuration entry points for Clash and the Clash Meta kernel, now commonly called mihomo, are YAML-based. A complete configuration usually includes ports, the operating mode, nodes, proxy groups, rules, and DNS fields. Some GUI clients detect generic subscriptions before import and invoke an integrated converter; when the kernel reads a configuration file directly, the input generally must already be valid, parseable YAML.

Key differences between the three common response types

Importing a subscription URL in Clash clients

Before importing, verify that the system clock is correct and that the link is reachable over HTTPS. A clock offset of a few minutes can cause TLS certificate validation to fail; extra spaces, line breaks, or Chinese punctuation introduced during copying can also break the request. The URL should begin with https:// and should not end with a period.

Clash Verge Rev remote configuration entry

Using the Clash Verge Rev 2.3.1 interface as an example, open “Subscriptions” → “New”, set the type to “Remote”, paste the address into the URL field, and confirm. After the import finishes, enable the configuration from its card. Some versions show the New entry as a plus button, but the meanings of the remote configuration, URL, and update interval fields are the same.

1. Open the “Subscriptions” page and select “New” or the plus button.
2. Choose the remote configuration type and paste the complete HTTPS address.
3. Use a name that describes the service purpose, such as “Daily rules”, and never use the token as the name.
4. Save it, wait for the download and YAML parsing to finish, then set the configuration as the active one.
5. Open “Proxies” to choose a proxy group policy, then go to “Settings” → “System Settings” and enable the system proxy.

Legacy Clash for Windows interface path

If you still maintain a legacy setup, the entry point in Clash for Windows 0.20.39 is “Profiles” → the URL field at the top → “Download”. After the download succeeds, click the corresponding configuration card to make it active. This client is no longer updated, so this path is mainly useful for identifying existing installations; for new deployments, prefer a maintained client using the mihomo kernel.

After importing, do more than check for a “download successful” message

• Check that the configuration card shows an updated timestamp rather than appearing only in the history list.
• Check whether the “Proxies” page contains the expected proxy groups, such as “Node Select”, “Auto Select”, or “Fallback”.
• Check the current mode. Rule-based configurations should normally use Rule mode rather than Global mode.
• Check the local listening port. 7890 is a common mixed port, but the actual value should come from mixed-port in the configuration.
• After enabling the system proxy, confirm that the system HTTP and HTTPS proxies point to 127.0.0.1 and the client’s actual port.

Identify the subscription format from the response

When you open a subscription URL directly in a browser, it may download a file or display a long string of characters. The most reliable clues are the HTTP status, response headers, and response body—not the file extension. A server may return standard YAML from a .txt path; conversely, a URL named config.yaml may return a login page.

Inspect status and response headers with curl

curl -L --compressed -D headers.txt \
  -o subscription.txt \
  "https://sub.example.net/profile?token=demo-token"

-L follows 301, 302, 307, and 308 redirects; --compressed lets curl decompress supported compressed responses, including gzip and Brotli; -D writes the response headers to a separate file. Check that the final status is 200, then inspect Content-Type. YAML responses may use text/yaml, application/yaml, or plain text/plain, so the MIME type is only a supporting clue.

Structure of a complete Clash YAML file

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

proxies:
  - name: Example-Trojan
    type: trojan
    server: edge.example.net
    port: 443
    password: sample-credential
    sni: edge.example.net

proxy-groups:
  - name: Node Select
    type: select
    proxies:
      - Example-Trojan
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.org,Node Select
  - GEOIP,CN,DIRECT
  - MATCH,Node Select

As long as the indentation and fields are valid, this content can be saved as a UTF-8 config.yaml file. YAML uses spaces to express nesting; do not use tabs for indentation. If a name contains a colon, hash, or leading or trailing spaces, quote it. A configuration that parses successfully does not guarantee that its node parameters work; the protocol, port, TLS, SNI, and authentication details must still match the server.

Provider YAML containing only nodes

Another common response contains only a top-level proxies: key, with no rules: or proxy-groups:. It is usually a proxy provider file, intended to be referenced by proxy-providers in a complete configuration, and may not start independently as the main configuration.

proxy-providers:
  remote-nodes:
    type: http
    url: "https://sub.example.net/provider.yaml?token=demo-token"
    path: ./providers/remote-nodes.yaml
    interval: 21600
    health-check:
      enable: true
      interval: 600
      url: https://www.gstatic.com/generate_204

proxy-groups:
  - name: Auto Select
    type: url-test
    use:
      - remote-nodes
    url: https://www.gstatic.com/generate_204
    interval: 300

Here, interval: 21600 means that the provider updates every 21,600 seconds, or six hours; the health check runs every 600 seconds, and proxy group latency testing runs every 300 seconds. These intervals are independent—successful latency tests do not mean that the subscription has been updated.

Handling Base64 and generic node subscriptions

Base64 is an encoding method, not a proxy protocol. It is often used to combine multiple URI lines into a single transport-friendly string. A typical body contains uppercase and lowercase letters, numbers, plus signs, slashes, and a trailing equals sign; URL-safe Base64 may also use hyphens and underscores. The character pattern alone cannot confirm the format, so decode it and inspect the content.

Decode offline and identify the URIs

On macOS or Linux, first copy the response to a file, then run the following command. GNU coreutils commonly uses base64 -d, while the built-in macOS tool also supports -D; if the options differ on your platform, run base64 --help first.

base64 -d subscription.txt > decoded.txt
head -n 8 decoded.txt

The decoded result is usually one node URI per line, such as ss://, trojan://, or vmess://. The body of a VMess URI may itself contain Base64-encoded JSON. Do not repeatedly decode the entire file; first check whether the first-layer result already contains readable protocol prefixes.

Why a Base64 subscription cannot always be given directly to the Clash kernel

The Clash configuration loader reads a YAML structure, while a generic Base64 list is simply a collection of node URIs. If a GUI client offers “Import generic subscription” or built-in conversion, it may automatically turn the URIs into proxies entries. When running the mihomo binary directly with -f to specify a configuration, first obtain YAML in Clash or mihomo format.

• When a provider offers “Clash”, “Mihomo”, or “Clash Meta” formats, choose the matching entry first.
• When conversion is necessary, prefer the provider’s own format converter or a conversion tool running locally.
• Match the conversion target to the kernel’s capabilities. If the configuration contains fields such as VLESS, Reality, or Hysteria 2, choose a mihomo-compatible format.
• After conversion, check the node count, proxy groups, rules, and DNS—not just whether the file was generated successfully.

Update intervals, caching, and expired subscriptions

Subscriptions do not need to refresh every minute. A remote configuration usually includes complete rules and a node list; frequent requests add server load and may trigger rate limits. For everyday use, set updates to every 6–24 hours. If nodes change frequently, shorten the interval to one hour, but avoid setting automatic updates to every few dozen seconds.

Common interval conversions

Old nodes still appear after a manual update

1. Make sure you updated the currently active configuration, not another configuration with the same name in the list.
2. Check the client log for the request time, HTTP status, and parsing errors.
3. Avoid browser-cache effects when checking the subscription URL; compare the result with curl using the Cache-Control: no-cache request header.
4. Check whether a CDN is caching stale content on the server side; the Age response header can provide a useful clue.
5. If you use proxy-providers, also check the provider file’s update time rather than looking only at the main configuration timestamp.
6. After a successful update, reselect the proxy group; deleted nodes may remain in use briefly by an old session.

Troubleshooting by HTTP status

• 401 or 403: The token is invalid, access is denied, the source is restricted, or the required request headers are missing.
• 404: The path has changed, or some query parameters were lost while copying the address.
• 429: Too many requests. Increase the update interval and wait for the restriction to clear.
• 500, 502, or 503: The server or an upstream service is temporarily unavailable. Keep the existing configuration and try again later.
• 200 but parsing fails: The response may be a login page, an error JSON object, Base64 text, or incompatible YAML.

YAML parsing failures and no internet access after import

Handle subscription import errors in three stages: download, parsing, and runtime. During download, check HTTP and TLS; during parsing, check the YAML line number and field types; during runtime, check node handshakes, DNS, routing rules, and the system proxy. Mixing these categories makes it easy to keep changing subscription URLs without locating the actual fault.

Common YAML errors

• Indentation error: The indentation level before list items is inconsistent, or tabs are mixed in.
• Duplicate key: The same level contains two rules: or two dns: keys. The latter may override the former or trigger a strict parsing error.
• Unquoted colon: If a node name contains “region:route”, leaving it unquoted may cause it to be interpreted as a key-value structure.
• Wrong field type: port should be a number but was written as text that cannot be converted; boolean values should use true or false.
• Incompatible kernel: The configuration contains mihomo extension fields, but the client still uses an older Clash kernel.

Import succeeds, but the browser cannot open websites

1. Confirm that the active proxy group has selected a working node rather than an empty group or an expired node.
2. Confirm that the system proxy address and port match the listener. With mixed-port: 7890 configured, the system proxy usually points to 127.0.0.1:7890.
3. In Rule mode, check which rule matched the request. The final MATCH policy affects traffic not matched by any earlier rule.
4. Check the DNS configuration. When fake-ip is enabled, make sure the relevant application traffic actually passes through the kernel so that the resolution and connection paths do not diverge.
5. Enable TUN only when you need to take over applications that do not follow the system proxy. If enabling it cuts off all network access, check the TUN stack, route installation permissions, and DNS hijacking settings.

A reliable subscription import workflow

For initial setup, prefer Clash or mihomo YAML supplied directly by the server. After importing, keep a recent working local configuration so you can roll back quickly if a remote update fails. If the client supports configuration merging, put personal rules, DNS settings, and scripts in a local override layer so subscription updates do not overwrite manual changes.

• Use subscription URLs only for client configuration; do not place them in public synchronized repositories.
• Manage complete configurations and provider files separately, with their update intervals clearly defined.
• Keep node names unique to avoid selecting nodes with the same name but different parameters.
• After modifying rules, reload the configuration and verify the matched policy in the connection log.
• After changing the kernel version, validate the configuration syntax before enabling the system proxy or TUN.

The key to identifying a subscription format is not what the link looks like, but what it ultimately returns. YAML can enter the configuration workflow directly; Base64 must be decoded and identified first; a generic URI list must be converted into target YAML by a compatible client or trusted conversion process. Check the four stages—download, parse, enable, and capture traffic—to accurately locate most import problems.