iOS Setup: Get a Client from the App Store and Import a Config

Prerequisites: System Version, Apple ID Region, and Client Type

iOS doesn't work the way desktop does. A client can't open an HTTP proxy port for the browser to use; instead it registers a VPN configuration through a Network Extension, and the system hands traffic to that extension. Before installing, confirm three things: system version, account region, and config format.

System Version and Device Requirements

• Most clients require iOS 15 or later; releases shipped after 2025 generally raise the bar to iOS 16.
• Check the version under Settings → General → About → iOS Version.
• iPhone and iPad share the same App Store app; the interface adapts to screen size and appears as a split view on iPad.
• The system gives the network extension a limited memory budget, usually in the tens of megabytes. With too many local rules the extension may be killed by the system, which shows up as a disconnect anywhere from a few seconds to a few minutes after connecting. Pulling remote rule sets with rule-provider in your subscription is more stable than writing tens of thousands of rules into a local config.

Apple ID Region Decides Whether the App Shows Up

• App Store visibility is set by the account's Country or Region, and the mainland China storefront does not carry most proxy clients.
• You need an Apple ID from another region (US, Japan, and so on) to download one.
• Switching affects only the store, not iCloud: Settings → your Apple Account at the top → Media & Purchases → Sign Out, then sign in with the account from the other region. You can also sign out from the profile icon in the top-right corner of the App Store.
• App updates require the same account that downloaded the app, so keep that account around — otherwise you'll have to recover the password every time.

Client Types and Feature Differences

Every iOS client that supports the Clash config format is a third-party app, and the differences come down to three things: support for proxy-providers and rule-providers, whether script or override features exist, and how subscription updates are triggered. For plain rule-based routing, any client that fully parses Clash YAML will do.

Get a Client from the App Store

iOS clients that support the Clash config format include Stash, Shadowrocket, and Karing, all third-party apps. Names, prices, and storefront availability change, so go by the App Store page at download time.

1. Open the App Store and search for the client name; if you're unsure which to pick, try Clash as the keyword first.
2. Check the developer name, the most recent update, and the number of ratings. Entries that update often and have been listed for a long time are usually more reliable.
3. Tap Get and confirm with Face ID or your Apple ID password. Paid apps show their price up front.
4. Once installed, open the app and allow notifications and local network access when prompted.

Can't Find It, or Region Not Available

• First check the current account and its region under the profile icon in the top-right corner of the App Store.
• If the App Store says the app is not available in your country or region, sign in with an account from the matching region or redeem a gift card issued there.
• Some clients distribute test builds through TestFlight with limited slots; the release version stays on the App Store.

Three Things to Check on First Launch

• Check the core version under Settings → About. Clients built on the Clash Meta branch show mihomo plus a version number such as v1.19.x.
• Confirm the app can parse the YAML in your subscription, including the proxy-providers and rule-providers fields.
• Confirm the Mode menu has Rule, Global, and Direct; you'll need them later when checking routing.

Import a Subscription Link and Config File

iOS clients support three import paths: a subscription URL, the clipboard or a QR code, and a local YAML file. The subscription URL is the everyday route; local files are for temporary debugging.

Import from a Subscription URL

1. Open the Config tab in the client's bottom tab bar; some clients label it Subscriptions.
2. Tap + in the top-right corner and choose Import from URL.
3. Paste the subscription address. It starts with https:// and usually includes a token or uuid parameter.
4. Give the config a name you'll recognize, such as home, then confirm and the client starts fetching.
5. Once the fetch succeeds, the config appears in the list and is selected automatically; tap the button to the right of the entry to update it manually.
6. Turn on Auto Update, usually with a 24-hour interval; some clients can check on every launch.

Clipboard and QR Codes

• Long-press the subscription link in Safari to copy it, then choose Import from Clipboard in the client; most clients read the clipboard automatically.
• Generate a QR code from the subscription link and scan it with the client — handy for moving a config between an iPad and an iPhone.
• A QR code is as good as a credential; don't screenshot it and send it around.

Local YAML Files

• Save the .yaml file to the Files app, long-press it → Share → choose the client.
• You can also use Import from File in the client and pick the file from iCloud Drive or On My iPhone.
• If you have single-node links such as ss:// or vmess://, add them manually on the client's Nodes page, or assemble them into a proxies section in YAML and import that.
• Local files don't follow subscription updates, which makes them useful for debugging; switch back to the subscription once everything checks out.

The fields in a subscription file that matter for local use look roughly like this; after importing, you can check them one by one in the client:

mode: rule
log-level: warning
dns:
  enable: true
  nameserver:
    - https://223.5.5.5/dns-query
rules:
  - DOMAIN-SUFFIX,cn,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

First Connection: VPN Permission and On-Demand

The first time you tap Connect after importing a config, iOS runs its VPN authorization flow. This happens only once.

1. Return to the client's main screen and tap the connection switch.
2. iOS asks whether the client wants to add a VPN configuration; tap Allow, then verify with Face ID or your passcode.
3. A VPN badge appears in the status bar, and the client shows the current node and its latency.
4. After that, the configuration shows up under Settings → General → VPN & Device Management → VPN, where you can also toggle it manually.

On-Demand Connection

• Once enabled, the system brings the extension up automatically when the conditions are met, so there's no need to tap Connect every time.
• The usual options are Always, Wi-Fi Only, and Cellular Only; exact names depend on the client. For everyday use, Wi-Fi Only is a good choice — or simply leave it off.
• With Always selected, a weak network can cause repeated reconnects, and the VPN icon in the status bar will flicker.

Two Settings That Differ from Desktop

• On iOS, traffic capture is handled by TUN. The desktop approach of a system proxy on port 7890 doesn't apply here, and there's no port number to fill in.
• Some clients offer an option such as Allow LAN Connections, which listens on a local port so other devices on the same Wi-Fi can use it. Leave it off when you don't need it.

Notifications and Background Refresh

• With notifications allowed, subscription update results and connection status appear in Notification Center.
• Keep the client enabled under Settings → General → Background App Refresh for more reliable automatic subscription updates. The VPN extension is managed by the system and needs no keep-alive.

Verify That Rule Routing Works

A successful connection doesn't mean routing is correct. Run through the five checks below and you'll have an answer within two minutes.

Every line on the log page carries a rule name and the final policy; the usual format looks like this:

[TCP] 192.168.1.7:52134 --> www.google.com:443 match DomainSuffixRule(google.com) using PROXY
[TCP] 192.168.1.7:52188 --> api.weibo.cn:443 match GeoIP(CN) using DIRECT
[UDP] 192.168.1.7:5353 --> 223.5.5.5:53 match Match using DIRECT

Three Common Reasons Routing Fails

• Mode stuck on Global: all traffic goes through the proxy, so mainland China sites take a detour too, which shows up as slower access to domestic sites.
• Rule sets didn't download: rule-providers in the subscription need a network fetch, and when that fails only the final MATCH rule remains, which amounts to a global proxy.
• A local override replaced the rules section: some clients support overrides, and if the override file defines new rules, the rules from the original subscription stop working.

Use a Rule Lookup Instead of Opening Sites One by One

Some clients offer a domain lookup on the Rules page: entering www.google.com should match a proxy policy, while www.icbc.com.cn should match DIRECT. This is faster than opening pages one by one and makes it easier to tell whether the problem is the rules or the node.

Common Issues and the Order to Handle Them

The five cases below cover most connection problems on iOS. Work from the outside in: first confirm the subscription downloads, then that the extension connects, and only then look at the rules.

What Latency Test Numbers Mean

Latency tests in the client usually hit a probe address such as http://www.gstatic.com/generate_204 and only reflect TCP handshake time, not real bandwidth. The test itself uses data, so on cellular it's best to turn off automatic testing and tap it manually when needed.

Uninstalling Wipes Local Configs

The iOS app sandbox is deleted along with the app, so you'll need to import the subscription link again after reinstalling. Keep the subscription address in a password manager or your own notes, not only inside the client.