Shadowrocket
Features and Settings
Choose Global Routing first, then check Config and SERVER. After connecting, verify the result with a real request.
This page covers using Shadowrocket on iPhone and iPad, organized around what each feature does, where to find it, how to configure it, and what to watch for. Interface locations may vary by device layout; follow the names and options shown in the app. For a first-time setup starting with import, see the Getting Started guide.
Global Routing: Three Modes
Config routes requests according to rules, Proxy sends them through a proxy, and Direct connects directly.
What it does: Global Routing determines how the client handles requests entering its network tunnel. It is not a server list or a connection toggle. Choosing a server selects the endpoint used when a request needs a proxy; choosing Config, Proxy, or Direct determines how requests are handled. Each mode serves a different purpose when testing. Switching modes does not fix incorrect server settings.
Where to find it and how to use it: Open Home, tap Global Routing, and choose Config, Proxy, or Direct for your current needs. To route traffic by domain, address, or other criteria, first confirm the active configuration in Config, then select Config. To check whether the selected server can carry requests, select Proxy. To compare access over your current network without a proxy, select Direct. After switching modes, make a new request to the target; do not rely on a connection that was already open.
| Mode | How It Works | When to Use It | What to Check |
|---|---|---|---|
| Config Rules-based |
Handles requests according to the rules and policies in the active configuration. | When different destinations need different policies, such as DIRECT, PROXY, or another defined policy. | Whether the configuration is enabled, rules are in the right order, and the referenced policy names exist. |
| Proxy Proxy |
Routes requests handled by the client through a proxy. | To temporarily check whether the selected server and proxy connection are working. | SERVER selection, protocol settings, and whether the destination service is reachable. |
| Direct Direct |
Connects directly to destinations for requests handled by the client. | To compare direct access over the current network and help diagnose routing issues. | Whether the local network is working and whether any automatic connection conditions remain active. |
Rule Routing: Match Conditions and Policies
What it does: A rule has two parts: what to match and what to do with a match. Keywords such as DOMAIN and DOMAIN-SUFFIX define match conditions; DIRECT, PROXY, and REJECT define handling policies. Rules are checked in order, and a request that matches an earlier rule generally does not reach later rules. Rule order matters as much as rule content. Check the active configuration’s rules when Global Routing is set to Config.
Where to find it and how to configure it: Open Config, confirm which file is active, then review its [Rule] section. Keep a copy of the original configuration before making changes, and edit only the entries relevant to the target request. Place specific, narrow exceptions early where appropriate, and check the final FINAL rule. If a policy refers to a group defined in the configuration, make sure the name matches exactly and that the group has an available selection.
| Keyword | What It Matches or Does | What to Watch For |
|---|---|---|
DOMAIN | Matches an exact domain. | Use when you need to handle one specific hostname. |
DOMAIN-SUFFIX | Matches the domain and its subdomains. | Covers more than a single DOMAIN rule; check whether the subdomains should also be included. |
DOMAIN-KEYWORD | Matches domains containing the specified keyword. | A short keyword may match unrelated destinations. |
IP-CIDR / IP-CIDR6 | Matches an IPv4 or IPv6 address range. | Check the address family, mask, and actual connection address. |
GEOIP | Matches based on an IP geolocation database. | IP geolocation is not the same as a domain’s region, and results depend on the database. |
DIRECT / PROXY / REJECT | Used to connect directly, route through a proxy, or reject a request, respectively. | These are policies, not domain-matching types. |
FINAL | Handles requests that did not match any preceding rules. | Usually placed at the end to define the destination for all remaining requests. |
Minimal Rule Example
[Rule]
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECTThis snippet illustrates matching behavior only: requests to example.com and its subdomains go to PROXY; everything else goes to DIRECT. It is not a complete configuration for every user. The actual PROXY endpoint depends on the active configuration and selected server. After editing, revisit the test destination and check the connection log for its destination and policy to confirm that the expected rule matched.
Note: A webpage may load resources from multiple domains. The main page opening does not mean its images, sign-in requests, and API calls all use the same policy. When troubleshooting, note the specific destination that fails instead of adding an overly broad rule based only on the site name. For more on rule keywords, see the glossary.
Subscriptions and Server Management
What they are: A server entry stores the address, port, protocol, and authentication details needed to connect. Subscribe uses a subscription link you already have to retrieve a set of server entries. Subscriptions, servers, and Config are separate things: importing servers does not mean a rules file is enabled correctly, and enabling Config does not mean every server it references is valid.
Where to find them and how to set them up: On Home, tap Add Server. If you already have a subscription, set Type to Subscribe, paste the full link provided by your service provider, save, and check the imported entries. If you have details for a single server, choose the matching Type and enter each setting as provided. Shadowsocks, VMess, VLESS, Trojan, Hysteria2, WireGuard, and other protocols use different fields; do not reuse settings from another protocol just because the names look similar.
- First make sure the input is complete, especially any parameters at the end of a subscription link. Do not include explanatory text when pasting it.
- After saving, check the groups and server entries on Home to confirm the expected content was imported, then run Connectivity Test.
- Select the SERVER you want to use, then check Global Routing. If you use Config, also confirm that the rules reference the intended policy.
- After updating a subscription, check the current selection again. Entry names or contents may have changed, so do not assume the previous selection is still valid.
Note: A failed subscription update and a failed server connection are separate issues. For an update failure, first check that the link is valid and the current network can retrieve its content. For a connection failure, check the server address, port, authentication, and transport settings. Subscription links may contain access credentials, so redact the full link and authentication fields from screenshots, logs, or support messages. Before deleting an entry, make sure you have retained its original details. Manually edited entries created by a subscription may also be replaced during a later update.
On Demand: Connect Automatically Under Conditions
What it does: On Demand lets the system initiate a VPN connection when configured conditions are met. It controls when a connection starts; Global Routing and Config control how requests are handled after the connection is established. Enabling On Demand does not supply server details or make an invalid configuration work.
Where to find it and how to configure it: Open Settings and look for On Demand options. Set them according to the network conditions available in the app. First connect manually and confirm that the current SERVER and Config work. Then add one clearly needed trigger condition, save, and test on the corresponding network. If the interface offers separate conditions for Wi-Fi or cellular, test each one; do not assume results on one network apply to the other.
Note: After On Demand is enabled, manually disconnecting does not necessarily prevent the system from reconnecting later. If the connection comes back after you turn it off, check On Demand and the corresponding on-demand connection settings in the system, then observe what happens after switching networks. To prevent automatic connections temporarily, disable the relevant conditions before using the connection toggle.
On Demand alone does not determine battery usage. Signal quality, how often the network changes, request volume, and keeping the connection active can all affect battery life. Keep other conditions similar and compare actual usage over time in the system’s battery settings instead of judging only by whether the VPN indicator appears. Once the connection is stable, add conditions gradually so you can identify which change affects its behavior.
Data: Usage Statistics and Request Activity
What it does: Data shows traffic and connection information recorded by the client. Use it to check whether requests are being made, whether traffic keeps increasing, and how behavior changes after adjusting settings. It is a client-side monitoring view, not a service provider’s billing statement; total traffic alone cannot confirm whether a particular rule is working.
Where to find it and how to use it: Open Data and check the displayed statistics range and time period first, then perform a repeatable access test. To investigate one issue, note the current statistics or save any records you need, then open the same destination and compare the results. Before clearing records or resetting statistics, check the scope of the action so you do not erase evidence you still need.
Note: Uploads and downloads, direct and proxied connections, and current-session and cumulative records may use different measurement methods; follow the labels shown in the app. A service provider may include protocol overhead in its usage totals and use a different billing period, so the figures may not match exactly. System cellular usage is tracked over its own time period; align the date ranges before comparing.
If traffic is increasing but a page will not load, do not assume the server is working. The traffic may come from background apps or other domains; check the specific request and error details. If no new records appear, first check the connection toggle, make sure you have repeated the test request, and confirm that the request is being handled by the client. When sharing records, include only what is needed for troubleshooting and redact private domains, addresses, and authentication details.
Settings: Check Common Options One by One
Note the current value and change one setting at a time; also check settings in the configuration file.
DNS: Distinguish Resolution Issues from Connection Issues
What it is and where to find it: DNS resolves domain names to addresses. Check related options in Settings under DNS and in the DNS-related parts of the active Config. How DNS actually works depends on the configuration in use, so checking just one screen is not enough.
How to configure it and what to watch for: Keep the current working settings and note the affected domain and network. Change DNS only after confirming a resolution issue, and then reconnect and make a new request to verify the result. Resolving to an address does not guarantee the destination can be reached, and an address change does not necessarily indicate a problem. Do not change DNS, server settings, and rules at the same time, or you will not know which change affected the result.
Test Method: Keep Connectivity Test Results Comparable
What it is and where to find it: Test Method determines how servers are tested. Check it in Settings. It affects what Connectivity Test results mean; it does not replace testing a real request.
How to configure it and what to watch for: Choose a method offered in the app that suits your test. When comparing servers, keep the method, test destination, and current network consistent. Different methods check different parts of the connection, so their results should not be compared directly. After a successful test, still open the actual destination. If a test fails, check the server protocol and network conditions before drawing conclusions; do not delete every entry based on one result.
Today Widget: Check Status After Using a Shortcut
What it is and where to find it: Today Widget provides a system shortcut to view or control client status. Check the relevant options in Settings and add the corresponding widget wherever the system allows. Whether the widget is available and how it appears depends on the current system and app support.
How to configure it and what to watch for: Set up the server and routing in the app first, then configure the shortcut. After using it, return to Home and confirm the connection status, selected SERVER, and Global Routing mode. A system widget may take time to refresh, so its last displayed content does not confirm the current status. When troubleshooting, rely first on the in-app status and the results of a real request.
iCloud: Check What Syncs; Do Not Treat Sync as a Full Backup
What it is and where to find it: iCloud features sync content supported by the app when the required conditions are met. Open Settings to review sync options, and make sure the system iCloud settings allow Shadowrocket to use the relevant service.
How to configure it and what to watch for: First check the iCloud account used on the device and its network connection, then enable the options for the content listed in the interface. After moving to a new device, check the configuration, servers, and selections individually; do not assume all data and system permissions will be restored. Syncing may take time. Keep a recoverable copy of your configuration before editing it on multiple devices, and continue to treat content containing subscription or authentication details as sensitive.
Diagnostics: Gather Information About One Issue
What it is and where to find it: Diagnostics provides tools to help narrow down an issue; look for it in Settings. Diagnostic information helps identify where to investigate, but does not replace checking server settings or testing a real request.
How to use it and what to watch for: Note the network type, Global Routing mode, and selected SERVER when the issue occurs, then run the relevant checks as prompted. If you need logs, capture only what is necessary to reproduce the issue. Save the required results, then restore your everyday settings. Before exporting or sharing, check for subscription links, authentication fields, private destinations, and other sensitive information. A clear, repeatable test is usually more useful than a long log without timestamps or details of what happened.
Verify Settings: Troubleshoot in a Consistent Order
After configuring the app, verify the shortest path first, then expand your checks. An enabled connection toggle only shows that a connection was initiated. A Connectivity Test result only shows the outcome of the selected test. Only opening the target successfully confirms that specific request worked. Each observation serves a different purpose; do not treat them as interchangeable.
- Check the input: On Home, confirm that the server or subscription was imported completely. Check the address, port, protocol, and authentication details, then confirm the current SERVER.
- Check how requests are handled: Review Global Routing. If you use Config, open Config and check the active file, rule order, and FINAL. After testing with Proxy or Direct temporarily, note the original setting and restore it.
- Check the connection and automatic triggers: Check the connection toggle and system permissions. If the connection comes back on its own, check On Demand. If the issue occurs only after changing networks, reproduce it separately on Wi-Fi and cellular.
- Check the target request: Open the same destination again and use Data, connection records, and Diagnostics to determine whether the failure occurred during DNS resolution, server connection, or the request itself.
- Revert and test again: Change one setting at a time and note its previous value. If the change does not help, restore the original value before checking the next setting. This keeps separate issues from getting mixed together.
If you have not completed your first connection, follow the Getting Started guide. For purchase, restoration, or App Store visibility issues, see Getting the App. To check the meaning of a setting, use the glossary. Shadowrocket is available only through the App Store on Apple platforms. Check the App Store listing for system requirements.