Before Downloading from the App Store: Check Clash Config Compatibility
Make sure the client can import your config before installing it. Supporting a proxy protocol, accepting Clash subscriptions, and reading a complete Clash YAML file are three different things. Even if mihomo on desktop can read the same file, an iOS client might import only the proxy nodes, ignore rules and proxy groups, or fail to recognize certain fields.
- Verify the developer and app listing. Open the App Store from a link published by the developer, or search for the product in the App Store and check the developer name. Similar names and icons don’t prove that two listings are for the same client.
- Check the iOS version requirement. On your iPhone, go to Settings → General → About to check your iOS version, then compare it with the Compatibility details on the App Store listing. If the app isn’t available in your current store region, check the availability information published by the developer. Don’t treat an unfamiliar installation link as an App Store listing.
- Check what the client can import. If you have a subscription URL, look for support for remote configs or subscriptions. If you have a YAML file, check for instructions on importing local files. If your setup relies on custom routing, confirm support for
proxy-groups,rules, and remote rule sets.
Import a Subscription URL: Make Sure It Contains a Full Config
Use a subscription URL that the provider explicitly identifies as Clash-compatible or compatible with your client. Subscription links usually look like HTTPS URLs, so the file extension won’t tell you what they contain. The same service may offer a full config, a proxy-node list, and an account management page as separate links.
- Copy the full URL from the provider’s subscription page, including any parameters after the question mark. Don’t share your personal subscription URL in public chats, screenshots, or online conversion tools; it may contain a token that grants direct access to your subscription.
- Open the client’s config manager and choose Add Remote Config or Import from URL. Paste the link into the URL field. You can choose any name to identify the config; it won’t change the subscription or act as a proxy server address.
- Save the config and run its first update. Make sure the client reports a successful download or parse, then check that the expected proxy nodes and proxy groups appear. If the original config included routing rules, confirm they were imported too—not just the proxy-node list.
- Set the new config as the active one. Saving, updating, and enabling are separate actions: seeing a new entry in the list doesn’t mean the active connection has switched to it.
Use the result to identify where the import failed. If the log shows HTTP 401 or 403, check your subscription authorization and the provider’s access requirements. If the download succeeds but parsing fails, make sure the link didn’t return a web page, a login response, or a subscription format intended for another client. Keep your previous working config until the new one passes testing.
Import a Local YAML File with the Files Picker
Save the complete file in the iOS Files app, then import it from your client. In Files, go to Browse and look under On My iPhone or iCloud Drive. If the file still shows a cloud download icon, open or download it first to make sure it’s available on your device. If the config is in an archive, extract it and select the actual .yaml or .yml file.
- In the client’s config manager, choose Import from File and open the file using the system file picker. If the client can receive configs through the Share menu, you can also touch and hold the file in Files, tap Share, and select the client.
- For a parse error with a line number, check that line and the one above it. Indent with spaces, align items at the same level, and place entries beginning with
-under the right field. Renaming a file to.yamlwon’t turn a web page or a list of proxy nodes into a config. - Check the imported config, then set it as active. A local file is usually imported as a copy. Unless the client explicitly supports syncing changes, edits to the original in Files won’t update the imported config. Import it again and make sure the active config is switched to the new version.
If the same file works on your computer but won’t load on your iPhone, distinguish YAML syntax errors from client compatibility issues. For example, if the config references local rule sets, importing the main YAML file alone may not include those external files. Desktop absolute paths won’t work on iPhone either. Get a version made for your client if possible; don’t delete an entire block of rules just to clear an error.
Check Rule Indentation with a Minimal Example
This example shows Clash-style top-level fields and the format and order of a rule list. It includes no proxy nodes and can’t be used to test connectivity. When checking your config, put specific matching rules before the fallback rule; rules are generally evaluated in order, with the first match taking effect.
mode: rule
rules:
- DOMAIN,example.com,DIRECT
- MATCH,DIRECT
First Connection: Allow iOS to Add a VPN Configuration
Select the imported config, then tap Connect in the client. The first time a tunnel starts, iOS usually asks whether to let the app add a VPN configuration. Make sure the prompt is for the client you just installed, tap Allow, and authenticate if iOS asks. A subscription or YAML file is data the client reads; the VPN configuration is a system setting iOS uses to start the tunnel. Importing the former doesn’t grant permission for the latter.
- Check the connection status in the client. If it stays disconnected or drops immediately, review the startup log and confirm that the active config loaded and system authorization is complete.
- On iOS 18, go to Settings → General → VPN & Device Management → VPN to check the status. If the menu labels differ, search for “VPN” in Settings. Make sure the client you just installed is connected—not another VPN you used before.
- If you tapped Don’t Allow the first time, return to the client and try connecting again to bring up the system prompt. If a work or school-managed device restricts VPN connections, ask the device administrator to check the policy. Don’t remove the management profile yourself.
After Connecting: Check Rules and Proxy Nodes Separately
A connected VPN status only means the tunnel has started. It doesn’t confirm that the remote node, DNS, and routing rules are all working. Test on the same Wi-Fi first. Don’t change the node, mode, and DNS at the same time, or you won’t know which change restored access.
- Check the mode and proxy groups. If the client offers rule mode, make sure it’s enabled and that the proxy group for the traffic you want to route is set to a working node, not
DIRECT. If you’re in global mode, opening a website doesn’t prove that your rules are working correctly. - Test one direct and one proxied request. Choose one domain your rules should send direct and another they should send through a proxy, then make fresh requests to both. If the client has a connection list or logs, check the matched rule and actual outbound route for each domain. A speed test only shows how its test request performed; it doesn’t verify access to the domains you’re troubleshooting.
- Test one symptom at a time. If only certain domains fail, check whether an earlier rule matches them. If one node repeatedly times out, keep the mode and network unchanged and test another node in the same proxy group. If several domains fail with DNS errors, first rule out a Wi-Fi network that requires a login page, then check whether the client’s DNS settings are compatible.
- Test cellular data last. Once the connection works over Wi-Fi, turn off Wi-Fi and retry the same domains with the same config and node. If it fails only over cellular, go to Settings → Cellular and check whether cellular data is enabled for both the client and the app you’re testing. Then use the logs to distinguish a DNS failure from a connection timeout.
If problems start after a subscription update, check whether the update succeeded, whether the active config changed, and whether the selected node was removed or renamed. When asking for help, include your iOS and client versions, import method, and the first relevant error. Remove subscription URLs, tokens, and account details from configs before sharing them.