Official Guide · Feature Reference

Shadowrocket Features and Settings

Check Global Routing first, then review the active configuration and server. On Demand, DNS, and testing each address different issues. Change one setting at a time before assessing the result.

Instructions for iPhone and iPad
Interface labels remain in English
Check rules and settings separately

The steps below describe the iPhone and iPad workflow. Check the App Store listing and the current app interface for available options, locations, and system requirements. If a setting isn't shown, don't change another option just because its name looks similar.

Global Routing: Choose How Traffic Is Handled

For everyday rule-based use, choose Config. Switch to Proxy or Direct temporarily when troubleshooting. Open Global Routing in Home and check the current selection. This setting controls how traffic is handled overall; it doesn't import servers or replace the connection toggle. After changing it, check the selected server and connection status in Home.

Interface option	How it works	When to use it	Notes
Config	Handles traffic according to the rules and policies in the active configuration.	Everyday use when traffic should be handled differently based on criteria such as domain or IP address.	First confirm that Config has the intended file enabled, then check the match results.
Proxy	Routes traffic handled by the client through a proxy.	Compare results to see whether a rule is causing access issues for a particular destination.	The server must still be available. This does not mean all system traffic necessarily follows the same route.
Direct	Handles traffic managed by the client as a direct connection.	Compare with direct access on the current network.	Direct does not turn off the connection or confirm that the server is reachable.

Change one option at a time

If a destination has issues in Config, temporarily switch to Proxy and try the same destination on the same network with the same server. If the result changes, check the rules and policies. If the issue remains, check the server settings, DNS, and network conditions. Restore the original mode after testing so a temporary troubleshooting setting doesn't become your everyday setup.

Don't take one successful visit in Proxy as proof that the entire configuration is correct, or a failed visit in Direct as proof that the app is at fault. Network conditions can differ by destination. For a meaningful comparison, keep the destination, network, and test window consistent.

Traffic Rules: Match Conditions vs. Actions

A rule defines what to match; a policy defines what to do when it matches. Open Config and check the active configuration file before reviewing its rules. With Global Routing set to Config, rules are generally evaluated in order. Broad conditions placed near the top may prevent more specific rules below them from taking effect.

Choosing a Rule Type

Use DOMAIN for an exact domain, DOMAIN-SUFFIX for a domain and its subdomains, and DOMAIN-KEYWORD to match a keyword in the domain. When adjusting a rule for a specific service, start with a domain you can verify. Avoid short keywords that could match many unrelated destinations.

IP-CIDR and IP-CIDR6 specify IPv4 and IPv6 address ranges, respectively. GEOIP matches against an IP geolocation database; results depend on the database and the resolved address. USER-AGENT relies on identifiable request information and cannot identify every type of encrypted traffic.

Policies and the Final Fallback

DIRECT handles traffic directly, PROXY routes it through a proxy, and REJECT blocks matching traffic. A configuration can also refer to named policy groups; check each name character by character. FINAL is the fallback policy for traffic that matches no earlier rule. Place it at the end and specify how unmatched traffic should be handled.

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT

This example illustrates rule syntax only: example.com and its subdomains use PROXY; all other unmatched traffic uses DIRECT. It is not a complete configuration and does not define a server. Back up the current file before editing. If the configuration updates remotely, check whether your local changes will be overwritten.

Subscriptions and Servers: Import, Then Check the Details

A subscription provides a way to update a set of server details; an individual server entry contains specific connection parameters. Neither is the same as traffic rules in Config. Manage servers in Home: open the add option, then choose Add Server. If you have a QR code, use Scan QR Code. Get subscription links and server details from your provider.

What to Check After Importing

For a subscription, choose Subscribe during the add flow and enter the address and a label as prompted by the current interface. After importing, check that the expected server list appears, then select the server you want to use. To add a server manually, choose the correct protocol first, then enter the address, port, authentication details, and transport parameters. Don't identify the protocol by the server label alone.

Shadowsocks, VMess, VLESS, Trojan, Hysteria2, and other protocols require different fields. TLS, SNI, transport type, and path settings should match the details you were given. Don't disable verification or replace authentication details just to get one test to pass. If the supplied fields don't match the form, check the protocol type and its parameter requirements first.

What Updates and Deletions Affect

A subscription update fetches the server details provided remotely, so names, counts, and parameters may change. If you edited an item in a subscription, check whether that change persists after an update. Before deleting an old entry, check which server is selected and whether any policy group refers to it. Deleting a server does not remove the subscription entry.

Subscription URLs may contain access credentials. Don't include the full URL in public screenshots, chat messages, or troubleshooting reports. Connectivity Test can give you an initial look at results on the current network, but it doesn't verify every website, protocol feature, or overall transfer speed. For first-time setup, see the setup guide.

On Demand: Connect Based on Network Conditions

Confirm that a manual connection is stable before configuring On Demand. On Demand triggers connection behavior based on configured network conditions; it doesn't fix server settings. Find the On Demand options in Settings and review the conditions and actions available in the current interface. Don't assume that enabling it is the right choice for every network.

Before configuring it, define what you expect: which Wi-Fi networks should trigger a connection, what should happen when switching to cellular, and when the connection should stay off. Set each supported condition separately, then test by switching between networks. Check the system connection status and the status in Home, not just whether a webpage opens.

If the connection comes back after you disconnect manually, first check whether On Demand is still active, then review the system's VPN settings. Deleting a server is usually not the right first step for stopping automatic reconnections. To temporarily stop automatic connections, disable the relevant condition, disconnect, and then test again.

Network changes, system scheduling, and the active configuration can all affect when On Demand triggers. Avoid setting multiple overlapping conditions. After making a change, note what you expected and what actually happened to tell whether the condition wasn't met or the connection itself failed.

Data: View Traffic Recorded by the App

Data shows the app's usage statistics; it does not replace your provider's usage records. Open Data from the bottom of the app. Before reviewing the numbers, check the selected range, time period, and categories. Totals from different ranges aren't directly comparable, and connection time isn't the same as active transfer time.

To check whether an action generated traffic, note the current statistics, visit the destination once, then return to Data and check for a change. Before resetting statistics, save anything you need to keep. A reset affects only the relevant local statistics; it does not reset usage on your provider account.

Local statistics may differ from provider usage measurements because of measurement boundaries, protocol overhead, time ranges, or activity on other devices. Don't judge a problem from a single cumulative number. Compare the connection status, destination, and usage change over the same time period; use Diagnostics if you need more evidence.

Settings: What Common Options Do

Settings brings app preferences and utility tools together, but some network behavior may also be determined by Config. Before changing anything, identify whether the issue concerns rules, a server, or a global preference. If the active configuration already includes a related setting, check how it interacts with the app setting to avoid repeatedly overriding it in two places.

DNS: Check Name Resolution

DNS resolves domain names to addresses. Check DNS if an address is reachable but its domain isn't, or if resolution results differ significantly across networks. First look for DNS settings in the active Config, then review the related options in Settings. Keep the original values and change one factor at a time, testing the same domain after each change.

Changing DNS won't fix an incorrect password, port, or rule order. Also consider whether DNS requests can reach their resolver, the IPv4 and IPv6 results, and how rules affect the resolution path. A resolver's name alone doesn't tell you whether it will work on your current network.

Test Method: Understand the Results

Test Method determines how connectivity tests are performed. In Settings, check the selected method and the related test target shown in the interface. Different methods check different parts of the connection, so different results for the same server aren't necessarily contradictory. For a useful comparison, keep the network, target, and method consistent; otherwise, changed conditions may look like a change in server performance.

A test result describes only that particular test. It doesn't necessarily reflect how an app will perform, and it can't establish overall bandwidth or long-term reliability on its own. If a test succeeds but access still fails, check the destination's rules, DNS, and server transport parameters.

Today Widget: Quick Status and Actions

Today Widget options control what appears in the system widget or which quick actions are available. Check the options in Settings, then add the widget using the method provided by the system. Availability and supported actions depend on the current system and app interface. The widget is a shortcut, not a separate configuration.

After using the widget, return to Home to check the connection status and selected server. If the widget doesn't match the app, first check whether its status has refreshed. Don't immediately delete a configuration or import the subscription again.

iCloud: Sync and Backup Are Different

iCloud settings sync app data within the supported scope. Before using them, check iCloud status and app access permissions on the device, as well as the sync options in Shadowrocket. Then check what actually appears on the other device. Don't assume every item or system permission will transfer.

Sync is not a separate backup: changes or deletions on one device may propagate to others. Keep a separate recoverable copy of important configurations. When moving to a new device, confirm that subscriptions, servers, and configurations are all present before restoring automatic connections. Even after the app is restored, the system may ask you to approve the VPN configuration again.

Diagnostics: Gather Details About a Specific Issue

Diagnostics helps investigate connection and network issues. Open the relevant tools in Settings and choose one that fits the problem. Test a specific domain, address, or connection behavior. Recording the network type, Global Routing selection, active configuration, and steps to reproduce is more useful than collecting unrelated test results.

Logs and diagnostic results may contain destinations, server addresses, or authentication details. Review them and remove sensitive information before sharing; include only the fields needed to explain the issue. Interpret each successful or failed test in the context of the network and configuration at the time. Don't generalize one result to all connections.

Troubleshooting Order: From Connection Status to the Destination

When a connection fails, preserve the current state and check one thing at a time. Don't update the subscription, replace the configuration, change DNS, and adjust On Demand all at once. Even if access starts working again, you won't know what fixed the problem.

Check the network. Confirm that the device's current network is working and note whether you're on Wi-Fi or cellular.
Check Home. Confirm the connection status, selected server, and whether the system has allowed the VPN configuration to be added.
Check Global Routing. Confirm that Config, Proxy, or Direct is appropriate for this test.
Check Config. Confirm the active file, destination-matching rules, policy names, and FINAL fallback.
Check the server. Compare the existing address, port, authentication, and transport parameters one by one. Check whether a subscription update changed the entry.
Check supporting settings. Review DNS, Test Method, and On Demand, then use Diagnostics to retest the same destination.

Once the issue is resolved, undo temporary troubleshooting changes one at a time and keep only the changes you need. Back up unfamiliar configurations before editing. Remove sensitive details from credential-bearing data before sharing it. For first-time connection steps, see the setup guide. To troubleshoot by symptom, visit Troubleshooting.