1 Why “paste subscription URL” often fails in Clash
Clash, Mihomo, and most third-party GUIs ultimately consume a structured document: a YAML file with proxies, proxy-groups, and rules (plus optional proxy-providers and rule-providers). Commercial or community “airport” dashboards, by contrast, usually expose a single HTTPS link that returns a text blob—often Base64—containing Shadowsocks URIs, VMess JSON lines, Trojan shares, or a mixture of legacy formats. None of that is YAML, so the client’s importer shrugs, the parser throws, or you end up with an empty node list even though the link opens fine in a browser.
A subscription converter (most famously the open-source Subconverter project) sits in the middle: it fetches the provider link server-side, decodes the payload, normalizes each node into Clash’s schema, and emits either a downloadable YAML file or another HTTPS URL your client can poll on a schedule. The workflow sounds mechanical, yet the details matter—target flavor (clash versus Meta extensions), naming, UDP flags, TLS SNI fields, and how often you refresh remote providers all change real-world stability. This guide walks the full path so you can reproduce results on a laptop, an Android phone running FlClash, or a headless Linux box running Mihomo under systemd.
Nothing here endorses a specific commercial service or encourages bypassing lawful network policy. Treat credentials like API keys: assume any third-party converter that sees your subscription URL can impersonate your traffic until you rotate the token. Prefer self-hosted converters, read generated YAML before deployment, and combine outbound lists with rule sets you understand—our ACL4SSR rule-provider tutorial shows how community lists layer on top once nodes exist.
2 What your provider link usually contains
Shadowsocks links follow the familiar ss:// scheme, sometimes wrapped in Base64 to hide metadata from casual logs. VMess and the newer VLESS family ship as JSON snippets, either per line or embedded in share URLs. Trojan endpoints advertise trojan:// URIs with explicit TLS server names and ALPN hints. Providers may mix several transports in one subscription response so a single fetch updates every region they operate. Because the payload is not Clash-native, the client cannot map fields like alterId, flow, or Reality public keys without a translation layer—that is exactly what Subconverter implements with per-protocol parsers.
Some dashboards also offer “Clash” or “Mihomo” specific links. If that URL already returns valid YAML with a top-level proxies: key, you can often skip external conversion and import directly, or point proxy-providers at the URL. When in doubt, download the response to disk, open it in an editor, and confirm it is YAML rather than Base64 gibberish. Mixed responses—HTML error pages, gzip bombs, or rate-limit JSON—mean you should fix authentication headers or user-agent strings before blaming the client.
Quick manual inspection
Use curl -sL 'https://example-subscription' | head -c 400 from a trusted machine to preview bytes. Legitimate text subscriptions often start with readable scheme prefixes after decoding, while pure Base64 blocks look like long alphanumeric strings without punctuation. Keep logs off shared pastebins; subscription URLs are bearer tokens.
3 The Clash document shape converters must produce
After conversion, every node lands under proxies as a list of dictionaries. Shadowsocks entries specify type: ss, cipher, password, server, and port. VMess and VLESS map to type: vmess or type: vless with UUIDs, TLS toggles, transport websockets or gRPC extras, and packet encoding flags. Trojan shares collapse into type: trojan with password authentication and SNI metadata. Converter quality shows up in edge cases: UDP support, skip-cert-verify misuse, and whether obfuscation parameters survived the round trip.
Groups turn raw nodes into something humans can switch inside a GUI. A minimal pattern is a select group named Proxy listing every outbound plus DIRECT, then rules that send traffic to Proxy or DIRECT based on domain, IP, or GeoIP. Advanced setups add url-test or fallback groups for latency-sensitive applications. Converters sometimes inject default groups; you can keep them, rename them for clarity, or strip them if your main config already defines routing.
Separating “nodes only” from “full profile” is a useful mental model. Some workflows generate a fragment with just proxies and merge manually into a hardened baseline that already contains DNS, TUN, and rule providers—similar to the skeleton in our Linux Mihomo systemd guide, where placeholders remind you to attach real outbounds.
proxies:
- name: hk-ss-01
type: ss
server: example.com
port: 443
cipher: aes-256-gcm
password: "redacted"
proxy-groups:
- name: Proxy
type: select
proxies:
- hk-ss-01
- DIRECT
rules:
- MATCH,Proxy4 Subconverter request flow and query parameters
Subconverter exposes an HTTP API. You pass your original subscription URL as an encoded parameter, pick an output target such as clash or newer Meta-aware profiles, and optionally reference external rule templates that append standardized rules sections after the nodes are parsed. Behind the scenes the service performs an outbound fetch, decodes provider-specific formats, applies naming rules, deduplicates servers when configured, and streams YAML back to the caller. Understanding that pipeline explains failures: fetch timeouts, TLS MITM inside corporate networks, or provider IP allowlists that block datacenter IPs.
Typical query knobs include target (output format), url (one or more comma-separated subscription links), insert (whether to embed nodes into a template), emoji (prefix country flags), udp toggles, and new_name strategies when providers recycle labels. Advanced users point config at a custom INI that locks down allowed protocols or rewrites cipher lists. Always match the target to the core inside your GUI—Mihomo understands extensions that legacy Clash Premium builds reject, so selecting a Meta profile avoids silently dropping nodes that rely on newer keys.
Public converter websites are convenient for a one-off test but multiply risk: you paste a privileged URL into someone else’s server logs. For recurring use, run the same software locally or on a VPS you control, restrict access with firewalls, and rotate provider tokens if you ever suspect exposure. Treat the converter output like source code: diff it against previous runs when a provider pushes a breaking change.
https://127.0.0.1:25500/sub?target=clash&url=ENCODED_SUBSCRIPTION&insert=false5 Self-hosting with Docker or a static binary
The upstream project publishes container images that bundle dependencies and default configuration paths. A common pattern on a home NAS or small VPS is binding port 25500 to localhost only, then using SSH port forwarding when you need GUI access from another machine. Container users should mount persistent volumes for custom pref.toml or rule snippets so upgrades do not wipe your templates. Pair the service with a reverse proxy only if you fully understand TLS termination and authentication; an unauthenticated Subconverter instance on the public internet becomes a free open proxy factory for attackers scanning Shodan.
Binary installs trade container overhead for simpler debugging: download the release for your architecture, place the executable alongside a config directory, and supervise it with systemd using the same rigor you would apply to Mihomo itself. Either way, schedule occasional updates—providers add new transport types regularly, and older converter builds may drop nodes silently rather than erroring loudly.
docker run -d --name subconverter --restart=always \
-p 127.0.0.1:25500:25500 \
tindy2013/subconverter:latest
After the daemon listens, hit http://127.0.0.1:25500/version or the documented health route to confirm readiness, then craft a /sub request with your encoded subscription. Store the resulting Clash YAML under version control without secrets if you want reproducible infrastructure, or skip committing and rely on proxy-providers to pull fresh nodes at runtime.
6 Feeding converted nodes through proxy-providers
Instead of pasting hundreds of lines into config.yaml, Mihomo and modern Clash derivatives can poll a remote URL on an interval. Point proxy-providers at the HTTPS endpoint Subconverter exposes (or at a provider’s native Clash link if they offer one). Set type: http, supply url, choose path for the cached file on disk, and tune interval to balance freshness against provider rate limits. Use health-check when you rely on automatic latency sorting so dead nodes fall out of rotation.
Reference provider-defined groups with use inside proxy-groups to keep YAML short. When multiple subscriptions exist—work, personal, family sharing—create separate providers and nest them inside a master selector so GUIs show clean sections. After editing providers, reload the running core through your dashboard or PUT /configs API if enabled.
proxy-providers:
airport:
type: http
url: "https://127.0.0.1:25500/sub?target=clash&url=ENCODED"
path: ./providers/airport.yaml
interval: 3600
health-check:
enable: true
url: https://www.gstatic.com/generate_204
interval: 600
proxy-groups:
- name: Proxy
type: select
use:
- airportMobile clients such as FlClash also accept subscription URLs directly; after conversion you can paste the Subconverter output link exactly like any other remote profile. Our FlClash Android setup article walks through VPN permission prompts and import UX that pair well with remote YAML.
7 Rules, templates, and staying out of “all traffic proxy” traps
Converters frequently ship optional templates that prepend advertising filters, streaming domain lists, or regional shortcuts. That is convenient but opaque: you should know whether a template forces MATCH,Proxy at the end or inserts DIRECT exceptions for local subnets. Blindly stacking templates from different authors can duplicate RULE-SET downloads or create contradictory priorities. Prefer starting from a minimal ruleset you understand, then layering rule-providers for maintenance-heavy lists such as streaming unlock or malware blocklists.
DNS must agree with your rules—split DNS mistakes look exactly like “Clash broken” when the real issue is resolver bypass. If you inject aggressive ad filters, expect occasional false positives on CDNs. Version-control your final YAML and note which template version you used so you can diff when something changes overnight.
8 Token hygiene and supply-chain caution
Subscription URLs are secrets. Anyone holding the link can fetch your nodes, consume your quota, and potentially attract abuse complaints toward your provider account. Never embed raw tokens in screenshots, chat logs, or public Git repositories. When testing converters, redact URLs before posting issues upstream. If a third-party site already saw your link, regenerate the subscription from the provider dashboard and delete old tokens when possible.
Treat converter binaries and Docker images as part of your supply chain: verify checksums, pin image digests in production compose files, and monitor release notes for remote code execution fixes. Running outdated Subconverter next to an exposed Mihomo API multiplies risk—both tools can touch the network on your behalf.
Finally, align DNS and TLS verification with your threat model. Disabling certificate checks might unblock a misconfigured node but also invites silent interception. Prefer fixing the server configuration or picking another outbound rather than permanently setting skip-cert-verify: true across the profile.
9 Troubleshooting checklist
- Converter returns empty
proxies: Re-fetch the subscription withcurl -vto confirm HTTP 200, inspect whether the body is still Base64, and verify thetargetmatches your core. Missing nodes often mean the provider rotated ciphers your Subconverter build does not yet map. - YAML imports but every node fails handshake: Check system clock skew, duplicated SNI fields, or accidental
skip-cert-verify: falseon servers using self-signed certs. Compare one manual URI from the provider dashboard against the converted entry field by field. - Remote provider never refreshes: Confirm
intervalelapsed, diskpathis writable, and no corporate proxy intercepts outbound fetches from the Mihomo host. Watch the core log for download errors. - Rate limits or HTTP 429: Increase polling intervals, avoid running multiple identical providers on separate devices against the same token, and ask the vendor whether they require a static egress IP.
- “Works in browser, fails in converter”: Copy the exact User-Agent header your vendor documents, or mirror cookies if they use a session gate—some panels are not meant for automated fetch.
10 Wrap-up
Subscription conversion is not magic; it is disciplined data plumbing. Understand what your provider ships, run Subconverter (or an equivalent stack) in an environment you trust, and treat the emitted Clash YAML like infrastructure code: diff it, lint it, and keep secrets out of logs. Once nodes land in proxy-providers, the rest of the Clash ecosystem—selectors, rule providers, DNS policies, and TUN mode—can behave the way tutorials promise instead of fighting half-imported configs.
Compared with juggling single-protocol clients, a Mihomo-powered workflow keeps routing, observability, and updates in one place. Desktop users still benefit from polished GUIs that hide YAML, while server operators can stay close to the metal with the patterns outlined in our Linux systemd guide and the Clash Verge Rev TUN walkthrough when they need full-device capture without per-app toggles.
If you are ready to consolidate subscriptions, rules, and DNS into one maintained client, grab a current build for your platform and import the converted profile—most users spend less time fighting parsers and more time verifying that routing matches how they actually browse.
