How to Import a Clash Subscription URL: Import Steps and Common Subscription Formats
A complete guide to importing a Clash subscription URL, covering YAML, Base64 node lists, and formats that require conversion—so you can identify why a link is not recognized.
“Import subscription” in Clash is more than saving a web address. The client requests the URL, downloads the configuration returned by the server, checks whether the current core can parse its format, and saves the result as a local profile. After importing, you usually still need to select the profile, choose a proxy node, and enable the system proxy or TUN mode before traffic actually passes through Clash.
Most import issues occur at one of three points: the copied address is not a subscription URL, the server returns a format unsupported by the current client, or the configuration downloaded successfully but was not set as the active profile. Start with a standard URL import, then identify YAML, Base64 node lists, and single share links one by one.
Confirm that you have a subscription URL before importing
A subscription that supports remote updates usually starts with https:// and is copied as one complete line, for example:
https://sub.example.com/api/client/subscribe?token=abc123&target=clashA web page URL, purchase page, dashboard login address, and subscription URL are different things. If opening the address in a browser shows a full account dashboard, plan details, or a login form, you probably copied a regular web page. The correct entry is usually labeled “Clash subscription,” “Clash Meta,” “Copy subscription URL,” or “Universal subscription.” When a provider offers several buttons, choose the version explicitly labeled Clash, Mihomo, or Clash Meta.
Check these four items after copying
- Complete scheme: The address must include
https://orhttp://; a domain and path alone are not enough. - No extra text: The link should not include “Subscription URL:”, quotation marks, spaces, or line breaks before or after it. On phones, long-press copying can easily select part of the accompanying instructions.
- Query parameters are intact: Parameters such as the token and target after
?may determine your identity and the returned format. Trimming them manually can cause 401, 403, or format errors. - The address is still valid: After resetting a subscription, migrating an account, or changing plans, the old URL may stop working immediately. Return to the provider page and copy it again.
A share link is a different type of content. A string beginning with ss://, trojan://, vmess://, vless://, or hysteria2:// usually describes a single node, not an HTTP subscription URL that can be updated on a schedule. Some clients support importing a single node directly, but use “Import from clipboard” or “Add node” instead of the subscription URL field.
Standard steps for importing a Clash subscription URL
Menu names vary slightly between clients, but the sequence is the same: open profile management, paste the URL, download the configuration, enable the profile, then verify the nodes and traffic status. These steps apply to common desktop and Android clients using the Mihomo core.
Desktop: Clients such as Clash Verge Rev
- Launch the client and open the “Subscriptions” page from the left sidebar.
- Paste the complete URL into the subscription address field at the top of the page.
- Click “Import” or press Enter, then wait for the remote configuration to finish downloading. On a normal connection, this usually takes 1–10 seconds.
- After importing, check that the profile card shows a node count, update time, and update button.
- Click the profile card to make this subscription the active profile. Some versions show a selected state or “Current profile.”
- Open the “Proxies” page and choose a node with suitable latency in the proxy group, or run a latency test first.
- Open “Settings” → “System proxy” and turn on the system proxy. Configure TUN mode only when you need to handle applications that do not follow the system proxy.
Android: Clients such as Clash Meta for Android
- Open the “Profiles” page and tap the plus button in the upper-right corner.
- Choose “Import from URL” or “New profile” → “URL.”
- Enter a profile name such as “Daily subscription,” then paste the complete link into the URL field.
- You can initially set the automatic update interval to
1440minutes, meaning once per day. Adjust it according to the provider’s instructions when necessary. - Save it and wait for the download to finish. Then return to the profile list and select the profile you just created.
- Return to the home screen and start the service, then open the proxy groups and choose a node. The first launch on Android displays a VPN connection permission prompt that must be approved by the system.
Quick checks after importing
After importing, use the results below to confirm that each step is working:
- The profile page shows the subscription name and a recent update time, with no parsing error.
- The proxy page shows groups such as
PROXY,Node Selection, andAuto Select, along with nodes inside the groups. - The latency test returns specific millisecond values, such as 85 ms or 210 ms, instead of continuously timing out.
- The logs show connection records, including the matched rule, destination address, and final policy.
- The update button can fetch the configuration again without requiring you to paste the URL again.
What is native Clash YAML?
A native Clash configuration is a structured YAML file. A complete configuration typically includes fields for listening ports, operating mode, DNS, nodes, proxy groups, and rules. Mihomo retains this basic structure while adding support for more protocols and configuration options. If a Clash-compatible remote subscription returns complete YAML directly, the client can usually parse it immediately.
mixed-port: 7890
mode: rule
allow-lan: false
proxies:
- name: Example-Trojan
type: trojan
server: edge.example.com
port: 443
password: demo-password
sni: edge.example.com
proxy-groups:
- name: Node Selection
type: select
proxies:
- Example-Trojan
- DIRECT
rules:
- GEOIP,CN,DIRECT
- MATCH,Node SelectionThis example contains the main outline of a complete configuration: mixed-port: 7890 lets HTTP and SOCKS requests share a local mixed port; mode: rule routes traffic according to rules; proxies stores nodes; proxy-groups organizes the policies users can choose; and rules determines whether each connection ultimately uses a direct connection or a proxy.
Complete configuration YAML vs. proxy-provider YAML
Not every file ending in .yaml can be used directly as the main profile. A proxy-provider file contains only payload and is usually referenced by proxy-providers in the main configuration:
payload:
- name: Example-SS
type: ss
server: node.example.com
port: 8388
cipher: aes-128-gcm
password: demo-passwordIf you put this provider file directly into a regular profile import field, the client may report missing proxies, proxy-groups, or rules, or the imported profile may have no selectable proxy groups. It is not a complete main configuration; it must be called by a main YAML file containing proxy-providers, proxy groups, and rules.
| Content type | Common opening line or fields | Can it be used directly as a Clash configuration? |
|---|---|---|
| Complete Clash YAML | mixed-port、proxies、proxy-groups |
Usually yes |
| Proxy-provider YAML | payload: |
Usually must be referenced by the main configuration |
| Rule-provider YAML | payload: followed by domains or rules |
Cannot be used alone as the main configuration |
| Web error content | <html>, login prompt, or error page |
No |
Why a Base64 node list may not be recognized
A universal subscription often lists multiple node share links line by line, then encodes the entire block as Base64. After decoding, the content may look like this:
ss://[email protected]:8388#Example-SS
trojan://[email protected]:443?security=tls#Example-Trojan
vmess://encoded-json-dataThis content is not Clash YAML; it has no proxy-groups or rules. Clients that support subscription conversion may convert the node list into an internal configuration during import. Clients that accept only Clash YAML may report a YAML parsing failure or configuration format error, or import it without any proxy groups.
Choose the Clash format provided by the service first
If the subscription page offers options such as “Universal subscription,” “Clash,” “Clash Meta,” and “Surge,” copy the Clash or Clash Meta link first. The subscription server then generates the target format directly, making it easier for node protocols, proxy groups, and rules to match the current core.
When only a universal Base64 link is available, first confirm that the client explicitly supports this format. Do not judge by the URL suffix alone: many subscription addresses have no .yaml extension and use query parameters, request headers, or server settings to determine the returned content. A file downloaded by the browser may be named subscribe while actually containing valid YAML.
A single node share link is not a Base64 subscription
The content after vmess:// is usually Base64-encoded data, but it describes one VMess node. A full Base64 subscription contains multiple share links before encoding. The two may use different import paths. For a single link, look for the client’s “Import from clipboard” feature first; for long-term automatic updates, request an HTTPS subscription URL from the provider.
Troubleshoot URL import failures by error type
“Import failed” can refer to very different issues: a failed network request and a format parsing failure require completely different fixes. Record the status code, error text, and time shown by the client, then compare them with the table below.
| Symptom or status | Common cause | First action |
|---|---|---|
| Timeout or connection failure | The subscription domain is unreachable, DNS is malfunctioning, or the current network is restricted | Switch networks, check the system time and DNS, then try again |
| HTTP 401 or 403 | The token has expired, the account is not in good standing, or the request is restricted | Return to the provider page, copy the subscription again, and confirm the account status |
| HTTP 404 | The path is invalid or the old subscription was reset | Do not edit the URL manually; obtain a new complete address |
| YAML parsing error | The response is Base64, an HTML page, or YAML indentation is corrupted | Confirm that the Clash format is selected and inspect the response content type |
| Import succeeds but no nodes appear | A rule set, provider file, or empty subscription was imported | Check whether proxies and proxy groups are present |
| Nodes are present but cannot connect | The nodes are unavailable, the system time is inaccurate, or no policy is selected | Correct the system time, test other nodes, and check the proxy groups |
Use a browser for a basic check
Paste the subscription URL into a browser’s address bar to confirm that it is still reachable. If the browser downloads a text file directly, the server is at least responding. If it redirects to a login page, plan page, or CAPTCHA page, the client may also be receiving HTML instead of a configuration. A URL opening in the browser still does not guarantee the format is correct, because the server may return different content based on the client request headers.
Check the HTTP status from the command line
If you are comfortable with a terminal, you can inspect only the response headers. Before running the command, avoid exposing a real token on a shared screen, in synchronized terminal history, or in public logs:
curl -I -L --max-time 15 "https://sub.example.com/api/client/subscribe?token=abc123&target=clash"-I requests only the response headers, -L follows redirects, and --max-time 15 limits the maximum wait to 15 seconds. A 200 result means the request returned successfully. If a 301 or 302 redirect ultimately lands on a login page, the issue is usually authorization or the link. A 404 means the path does not exist. Some subscription services do not respond to HEAD requests, so the command may fail even though the client’s normal GET request works.
Check YAML indentation and fields
YAML is sensitive to indentation when you save or edit a configuration manually. List-item hyphens, spaces after colons, and indentation at the same level must be consistent. Tab characters can also trigger parser errors; two spaces are generally recommended for indentation. If the original subscription is generated directly by the server, avoid making broad replacements in the downloaded file just to rename nodes, because the next remote update will overwrite local changes.
How to choose between an automatic update interval and a local configuration
Remote subscriptions are useful when you need node changes to stay synchronized, while local YAML is better for testing rules, DNS, or proxy groups. If you combine both in one automatically updated profile, local edits may disappear after an update, so first decide who maintains the configuration.
Do not set the update interval too short
A common automatic update interval is 1440 minutes, or 24 hours. If nodes change frequently, use 360 or 720 minutes. Setting it to 1–5 minutes creates many redundant requests and may cause the server to limit access. When you temporarily need the newest nodes, clicking “Update” once is a better option.
- 1440 minutes: Suitable for everyday use with a stable update schedule.
- 720 minutes: Updates twice a day; suitable for subscriptions whose nodes change frequently.
- 360 minutes: Updates every 6 hours; confirm that the provider allows this frequency.
- Manual updates: Suitable for long-term fixed configurations; refresh as needed before use.
Should subscription updates go through a proxy?
Some clients offer “Update through proxy” or “Use system proxy to update subscription.” When the subscription domain is directly reachable on your current network, keep direct updates enabled first for a simpler connection path. Try updating through a proxy only when direct access times out and the current proxy node works. If the subscription update depends on the same expired profile currently in use, you can end up in an update loop. Switch networks or enable another working profile instead.
Keep a recoverable configuration
Before changing DNS, TUN, or complex rules, export the current working configuration or keep a basic local profile. If a new subscription contains incompatible fields, you can restore connectivity first and continue troubleshooting. Remember that nodes in an old profile may already be expired; the main value of a backup is preserving ports, rules, and runtime settings.
Final checklist when the import is not taking effect
If the subscription shows “Update successful” but websites still will not open, check the items below in order. Change only one thing at a time so you can tell whether the issue is in the configuration, the node, or system traffic interception.
- Confirm that the profile selected in the profile list is the subscription you just imported, not an old profile or an empty local configuration.
- Open the proxy groups and switch the primary policy from
DIRECTto a node that passes the latency test. - Confirm that the operating mode is “Rule” or “Global.” In Rule mode, websites matching
DIRECTstill connect directly; this is expected. - On desktop, open “Settings” → “System proxy”; on Android, confirm that the VPN service is running.
- Check for local port conflicts. The common mixed port is
7890, but use themixed-portvalue in the current configuration as the authority. - Check whether the logs contain the target connection. No record at all usually means application traffic has not entered Clash; a record showing connection timeouts points more toward a node or network problem.
- If only applications that ignore the system proxy are affected, consider TUN mode. Do not treat TUN as a fix for an incorrect subscription format.
When identifying a subscription format, the most useful clue is the actual returned content, not the filename: complete Clash YAML should contain nodes, proxy groups, and rules; provider YAML contains only a collection for the main configuration to reference; a universal Base64 subscription usually decodes into multiple share links; HTML means you received a web page or error page. Check in this order—get the URL, download the response, identify the format, enable the profile, and verify traffic—to quickly locate where the import is stuck.