Official Guide · Features

Shadowrocket Features and Essential Settings

First decide how traffic should be handled, then when to connect. Global Routing controls the overall routing mode, rules in Config determine where requests go, and On Demand controls when the system starts a connection automatically. These are separate controls.

Home Select a server and routing mode
Config Manage rule configurations
Settings Review general settings
Data View traffic statistics

This guide focuses on iPhone and iPad. Each feature is explained in terms of what it does, where to find it, how to set it up and what to watch for. Interface labels and locations may vary by language or app update. If you can’t find a setting, check the current screen and the in-app guidance first; there’s no need to change several controls at once.

Global Routing: Config, Proxy and Direct

Global Routing is on Home and sets the overall routing mode for the current connection. Config, Proxy and Direct correspond to the options in the interface. Use Config for everyday rule-based routing. You can temporarily switch to Proxy to check whether a request works through the selected server, or to Direct to compare results and see whether the proxy route is involved.

Mode	How it works	When to use it	What to check first
Config	Handles requests according to the rules and policies in the active configuration.	Everyday rule-based routing, including separating local network traffic from other requests.	Active configuration, rule order and policy targets.
Proxy	Routes traffic through the proxy rather than applying Config’s standard rules individually.	Briefly test the connection path through the selected server.	Whether the selected server is valid and its protocol settings are correct.
Direct	Handles traffic using a direct connection.	Compare results with direct access over the current network.	Whether the current network can reach the destination directly.

How to set it up: choose a mode, then test a new request

Open Home, go to Global Routing, select a mode and return. With Config, also check in Config that the expected configuration is active. With Proxy, confirm that the expected server is selected on Home. Return to the target app and make a new request, then check the result. This avoids mistaking an existing connection or cached page for a fresh test.

Direct does not turn off the system VPN connection; it describes how requests are handled, not the connection’s on/off state. Proxy won’t fix incorrect server settings either. When comparing modes, keep the network, destination and selected server the same, and change only one condition. Restore the original routing mode when testing is complete so temporary troubleshooting settings don’t affect later use.

Config: Rule Types, Order and Policies

Config manages configuration files, which include rules for routing traffic. Rules determine which requests match; policies determine what happens to matching requests. With Config selected in Global Routing, open the active configuration and check its rules and referenced policies. Importing a file without activating it does not mean the connection is using it.

Common rule types

DOMAIN matches an exact domain. DOMAIN-SUFFIX matches a domain suffix and its subdomains. DOMAIN-KEYWORD matches a keyword in the domain. Use IP-CIDR or IP-CIDR6 to match an address range; GEOIP classifies traffic using an IP geolocation database. USER-AGENT matches readable User-Agent information in a request; it is not a general-purpose way to identify all encrypted requests.

PROXY, DIRECT and REJECT are common policies for proxying, direct connections and rejecting requests. A configuration may also reference custom policy groups. If you see a custom name, check which member is actually selected rather than assuming the route from the name alone.

[Rule]
DOMAIN-KEYWORD,ads,REJECT
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
DOMAIN-SUFFIX,example.com,PROXY
FINAL,PROXY

The examples above illustrate rule syntax and order; they are not a complete configuration. example.com is an example domain. Keyword rules may also match unintended domains, so narrow their scope to fit your needs. no-resolve means not to trigger an additional domain lookup for that IP rule; it does not disable DNS globally.

How to edit rules: specific matches first, catch-all handling last

Rules are generally evaluated from top to bottom, and the matching policy is applied as soon as a rule matches. Put more specific exceptions before broader rules. FINAL handles requests that did not match any preceding rule. Save a copy of the original configuration before editing. Afterward, make a new request and, if request logs are available, check which rule matched and which policy was applied.

Remotely maintained configurations may replace local content when updated. Before making changes you want to keep, check how the configuration updates and how it relates to your local copy. Avoid adding many rules from unknown sources at once. When something goes wrong, the most useful detail is which rule matched a request—not the total number of rules.

Home: Manage Subscriptions and Servers

A server entry stores the protocol, address, port and authentication details for one connection. Subscribe updates a group of entries using subscription details you already have. Server information and Config serve different purposes: the former specifies where to connect; the latter determines how requests are routed. After importing a subscription, check the selected server and Global Routing too.

Add Server: Check Your Existing Server Details

On Home, open Add Server, choose the protocol listed in your existing details, then fill in the corresponding fields. Fields for protocols such as Shadowsocks, VMess, VLESS, Trojan, Hysteria2 and WireGuard are not interchangeable. In addition to the address and port, you may need to check authentication, transport, TLS and Server Name. Use your existing server details and the fields shown in the app as your reference.

To import a QR code, use Scan QR Code and review the parsed details before saving. A QR code only carries information; it doesn’t guarantee that the settings are correct. When entering details manually, check for extra spaces, the port number and complete authentication information. A display name can help identify an entry, but changing it won’t fix connection settings.

Subscribe: Check Entries and Selection After Updating

To add a subscription you already have, select Subscribe, enter its address and save, then update it. A successful update means the address could be read and recognizable entries were found; it does not mean every server will connect. First check that entries appear, then select a server and run Connectivity Test, and finally verify with an actual request.

If a subscription update fails, first check that the link is complete and active and that your current network can access it. Don’t repeatedly delete all entries. Entry names or counts may change after an update, so you may need to confirm your selection again. Subscription addresses and QR codes may contain authentication details; redact sensitive information when reporting a problem.

On Demand: Connect Automatically Based on Conditions

On Demand uses the system’s on-demand connection mechanism to start a connection when specified conditions are met. It controls when a connection starts; it does not replace routing rules in Global Routing. The app may offer conditions related to Wi-Fi, cellular networks or domains. Available options depend on the current On Demand screen.

How to set it up: start with one clear condition

Open the On Demand settings under Settings. Review the existing conditions, then add or edit one to match your needs. For an initial setup, use a single condition that’s easy to verify—for example, check connection behavior on a specific Wi-Fi network. After saving, connect to that network, wait for the system to respond, then check the system connection status and make an actual request.

If conditions have an order or override one another, follow the guidance in the interface. Don’t add multiple conflicting connect and disconnect conditions at once, or change conditions while also switching servers, DNS and configuration files. Otherwise, even if behavior changes, it will be hard to tell what caused it.

What to check if the connection returns after you disconnect manually

If the connection comes back after you disconnect manually, first check whether On Demand is still triggering under the current conditions instead of assuming the switch is malfunctioning. To troubleshoot with a stable manual connection, temporarily turn off On Demand, note the original conditions, and restore them when you’re done. Enabling it does not necessarily reduce battery use; the effect also depends on how often it triggers, background requests and network changes.

For combinations of Wi-Fi, cellular and domain conditions, see On Demand Setup Guide. To check background battery use, follow the Background Battery Use Checklist and compare results under similar conditions.

Data: View Traffic Statistics

Data shows traffic information recorded by the app. Use it to observe changes in uploads, downloads or individual entries during a period of use. It is not the same as your carrier’s bill or the usage measurement from a service you already have. Different measurement ranges, reset times and network overhead can cause figures shown in different places to vary.

How to check: compare changes over a consistent time period

Open Data and check the statistics range and available categories. Note the values before testing, perform an action in the target app, then return to check the difference. Before clearing records, make sure you don’t need the history. Clearing statistics does not restore any data allowance already used with an external service.

To check whether a particular server is actually carrying traffic, consider the selected server, routing mode and rule match—not just the total. Direct requests, background sync and requests from other apps can all affect the figures. A larger download total alone doesn’t prove a better connection; throughput, latency and request success rate measure different things.

If Data changes differently than expected, first check that the target request was newly made and wasn’t served from cache. Then confirm that the connection stayed active and the network didn’t change. Don’t infer how all requests are handled from a single page refresh.

Settings: DNS, Test Method and Supporting Features

Settings brings together general behavior and supporting options. When troubleshooting, first identify whether a setting affects DNS resolution, testing, a system entry point or data syncing. Some options may also be controlled by the active Config, so check whether it specifies its own settings before changing general ones. This helps avoid assuming a change took effect when actual behavior remains unchanged.

DNS: Check the Configuration Source Before Changing Resolution Settings

DNS resolves domain names to addresses. A DNS lookup failure and a server connection failure can look similar while a page loads, but they require different fixes. Review DNS options in Settings and the DNS settings in the active Config to determine which resolution settings are actually in use. Don’t rely on the address shown on just one screen.

Use DNS settings whose purpose you understand, keep a copy of the original values, and change one variable at a time. After a change, set up the test again and make a new domain request; cached results may persist. Local network devices, internal domains and public domains may need different handling. Avoid routing every DNS request the same way and then trying to diagnose each case.

Don’t treat DNS changes as a general fix for every timeout. If protocol authentication fails, a port is unreachable or the server’s time requirements aren’t met, changing DNS alone usually won’t address the root cause. First distinguish between a domain that won’t resolve and a resolved address that won’t connect.

Test Method: Make Results Comparable

Test Method determines how Connectivity Test runs. Find it in Settings, choose an option available in the current interface and check the relevant test target. Different methods measure different stages: basic round-trip tests and tests that require more network steps are not directly comparable.

When comparing servers, use the same Test Method and test target under similar network conditions. A timeout means that test did not finish within the expected time; it doesn’t necessarily mean all requests are unavailable. Likewise, a successful test doesn’t prove that every destination is accessible. Always verify with an actual request.

Today Widget: Check Whether the System Entry Is Available

Today Widget provides shortcuts or status information through system widgets. First check the related setting in Settings, then open the system widget editor and see whether Shadowrocket is available to add. Availability and appearance depend on the system and the features currently provided by the app; check the device interface for details.

If the status doesn’t change right away after using a shortcut, check Home and the system VPN status instead of tapping repeatedly. A widget is an entry point, not a separate connection configuration. The selected server, Global Routing and On Demand can still affect what happens.

iCloud: Check What Syncs Before Verifying on Another Device

iCloud settings sync app data within the supported scope. First check the system iCloud status and Shadowrocket’s sync options, then review the current interface guidance to see what is included. Turning on iCloud does not mean every server, rule and system permission has been fully copied.

Before using another device, keep a copy of important local configurations, then check the sync results, selected server and active configuration. System VPN authorization must still be confirmed on that device. App Store purchase restoration and iCloud data syncing are separate: the former relates to purchase eligibility, while the latter relates to app data. The status of one does not tell you the status of the other.

Diagnostics: Collect Information That Helps Pinpoint Problems

Diagnostics helps investigate network and connection issues. Find the Diagnostics options in Settings and run the checks available in the current interface. Useful diagnostics start with a specific symptom, such as “an existing subscription won’t update” or “requests to a particular domain time out.” Don’t run every check and compare only which number is lower.

How to troubleshoot: reproduce the issue, then review the relevant records

Note the current network, Global Routing mode, configuration and server. If needed, temporarily turn off On Demand to reduce automatic switching. Reproduce the issue once, then review diagnostics or request records from around that time. Look for clues that distinguish DNS failures, connection timeouts, authentication errors and mismatched rule policies.

For routing issues, match the destination domain to the rule it hit and the resulting policy. For connection issues, start with Connectivity Test and the server settings. If there are no request records, check whether the request was cached, whether it actually used the current connection and whether logging is available.

Settings Check Sequence: Change One Condition at a Time

Features depend on one another. Confirm app access and existing details first, then check the connection, and finally review rules and automatic behavior. This helps avoid repeated changes. The sequence below is useful when the app is set up but access isn’t working as expected.

Confirm your existing details. On Home, check that server entries are complete, the subscription updated successfully and the intended entry is selected. Being able to read a subscription does not prove a server can connect.
Confirm the system connection. Check that the initial VPN configuration was authorized and verify the actual connection status. For information about the authorization prompt, see VPN Configuration Authorization Guide.
Confirm the test conditions. Keep the network unchanged, choose a specific Test Method, run Connectivity Test, then verify with an actual request. For timeouts, see the Connection Troubleshooting Checklist.
Confirm routing and rules. Check Global Routing. If you’re using Config, also check the active configuration, rule order and policy targets. Restore the original settings after temporarily switching modes.
Check automatic and supporting settings last. Once the connection is stable, test On Demand, DNS, custom test methods and sync results one at a time. Keep a record of the settings before and after each change so you can revert if needed.

Proxy works, but Config doesn’t behave as expected. What should I check first?

First check which Config is active, which rule matches the target request and which policy it uses. Then check the members of any custom policy group. A change in results when switching modes helps narrow down the issue, but doesn’t by itself prove that DNS or the server is at fault.

Why do I need to check settings after switching devices?

Purchase restoration, data syncing and system VPN authorization handle different things. Even after restoring the app, check authorization on the device, the active configuration and the selected server. Check the App Store listing for iPhone and iPad compatibility and system requirements.

Where can I find the full steps from import to the first connection?

Follow the Getting Started Guide to import your existing details, choose Global Routing, authorize the system connection and verify access. For purchases and restoring previous purchases, see the App Store & Purchase Guide.