Official Guide · Features

Shadowrocket Features and Settings

Check Global Routing first, then verify Config and servers. This guide explains what common features do, where to find them, how to configure them, and what to watch for—especially for everyday setup and troubleshooting on iPhone and iPad.

View the Setup Guide Read the Protocol Guide

01 · Connection Modes

Global Routing: Choose How Traffic Is Routed

Global Routing determines how traffic is handled overall. Config, Proxy, and Direct are the interface options; they are not three different servers.

Option	What It Does	When to Use It	What to Check First
Config	Handles requests according to the active configuration's rules and policies.	When requests need different handling based on domains, addresses, or other matching criteria.	The active Config, rule order, and final policy.
Proxy	Routes all traffic handled by the app through a proxy.	When you want to briefly check whether the selected server and proxy route are working.	The server selected in Home, its connection parameters, and service status.
Direct	Routes all traffic handled by the app directly.	When you want to check direct access over the current network.	Whether the current network can reach the same destination.

Where to Switch and Which Mode to Choose

In Home, find Global Routing, choose a mode, then return to confirm the selected option. Use Config when you have routing rules and want requests handled according to them. Briefly switch to Proxy to check whether a server can establish a connection, or use Direct to test the same destination over your local network. When troubleshooting is done, restore the mode you intended to use so a temporary test setting doesn't become your everyday setup.

Global Routing and the connection toggle operate at different levels: Global Routing determines how traffic is handled, while the toggle controls the app's connection state. Selecting Proxy doesn't guarantee that a server is available, and selecting Config doesn't mean every rule is correct. If a destination works in Proxy but fails in Config, check the rules and policies first. This is a troubleshooting clue, not proof of the cause.

02 · Matching and Policies

Rule-Based Routing: Match First, Then Choose a Policy

Rules specify which policy applies to which requests. In Config, check which configuration is active, then confirm that Global Routing is set to Config.

Rule Types: What to Match

DOMAIN matches an exact domain; DOMAIN-SUFFIX matches a domain suffix and its subdomains; DOMAIN-KEYWORD matches a keyword in the domain. IP-CIDR and IP-CIDR6 specify IPv4 and IPv6 address ranges, respectively. GEOIP matches against an IP geolocation database.

USER-AGENT matches available User-Agent information, which not every request provides. It isn't a universal app-identification switch; the information available depends on the request type and configuration.

Policies: How to Handle a Match

PROXY applies a proxy policy, DIRECT connects directly, and REJECT blocks the request. A configuration may also refer to a custom policy group. If so, check what that group actually selects instead of relying on its name at the end of the rule.

Rules are generally evaluated from top to bottom, so put specific conditions before broader ones. FINAL is the fallback policy when no earlier rule matches. Setting it to reject requests or use an unavailable route may affect many requests without a dedicated rule.

How to Configure and Verify Rules

In Config, confirm which file is active and keep a restorable copy before making changes. When adding a rule, check its type, match value, and policy. Save it, make the target request again, and check the logs to see which rule matched. Change one rule at a time; don't alter DNS, servers, and the final policy all at once. The example on the right demonstrates syntax only: its domain is not a server address, and PROXY does not provide a server automatically.

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT
GEOIP,CN,DIRECT
FINAL,PROXY

FINAL Applies when no preceding rule matches; this snippet is not a complete configuration.

Rule Keywords and Policy Terms ›

03 · Connection Details

Subscribe and Server Management

A subscription imports and updates existing server entries; an individual server entry stores the parameters for one connection. Successful import means the details are in the list—it doesn't confirm that a remote connection works.

Add Server: Check Parameters Manually

From Home, open Add Server using the add button. Choose the protocol type that matches your existing details, then enter the address, port, and required authentication fields. Shadowsocks, VMess, VLESS, Trojan, HTTP, SOCKS5, WireGuard, and Hysteria2 use different fields and transport requirements. Changing only the protocol name while keeping the other parameters is not enough.

If your details are provided as a QR code, import them with Scan QR Code and then check the fields. Make sure the server address, authentication details, TLS, and server name match the original information. Importing details does not verify that the service is still active.

Subscribe: Update an Existing List

To add a subscription, choose Subscribe in the relevant add screen, enter your full subscription URL, and save it. Then update the list. Return to Home to check that entries appear in the group, and select the server you want to use. Updating the list and selecting a server are separate steps; don't assess the connection after only completing the first one.

Subscription URLs may contain access credentials, so keep them secure. If the list is empty, first check that the URL was copied in full, then review the subscription status and response format. Don't add the same URL repeatedly. Updates may change entry names or list contents, so record any important manual changes beforehand.

Connectivity Test Results Aren't the Same as Real-World Performance

Use Connectivity Test in the Home server list to check how the selected entry responds under the chosen test method. Before testing, check Test Method in Settings. Different methods measure different things, so their results aren't directly comparable. Lower latency doesn't guarantee access to every destination or faster sustained transfers. After selecting a server, test it against a destination you actually need to reach.

When organizing servers, use clear names to distinguish their purpose and keep a secure backup of the original parameters. Before deleting an entry, check whether it was added manually or created by a subscription. For subscription-generated entries, consider how subscription updates will affect them. Don't confuse a Config file with a server subscription: Config can contain rules and other settings, while a subscription is mainly used to update server details.

04 · Connection Triggers

On Demand: Set Connection Behavior by Condition

What it does: On Demand triggers connection behavior based on configured conditions. It's useful when manual connections work and you want connections to respond as expected when network conditions change. It doesn't guarantee server availability or fix incorrect authentication details or rules.

Where to find it: In Settings, find the On Demand options and check the main toggle and available conditions. The options shown in the app are authoritative. When setting up a system VPN configuration for the first time, read the system authorization prompt. Check both the system-level connection conditions and the in-app settings.

How to set it up: Note the current state, then add only the network conditions you need and check the connection behavior for each one. Test on networks that match and don't match the conditions, and confirm that the connection state is as expected. If a condition uses a Wi-Fi network name, check the spelling to avoid mistaking a name mismatch for a setting that doesn't work.

What to watch for: After enabling On Demand, existing conditions may trigger a connection even after you disconnect manually. If the app reconnects after being disconnected, check On Demand first, then review the system VPN settings. Don't immediately delete the entire configuration. If you disable it temporarily, note its original state and restore it after troubleshooting if needed. If the issue occurs only when switching networks, record the conditions and connection state before and after the switch.

05 · Usage Monitoring

Data: Review Traffic Recorded by the App

Data shows changes in traffic recorded by the app. It can help you tell whether data was transferred, but it can't by itself confirm that a request to a destination completed successfully.

Where to Look and How to Read It

Open Data and check the statistics' stated scope, time range, and whether historical totals are included. Then review items such as uploads and downloads. To track a particular action, note the current values, make one specific request, and check the figures again instead of relying on the accumulated total.

If the interface offers a way to reset statistics, decide first whether you need to keep the existing records. For troubleshooting, it's more useful to note how much the figures change before and after a test. Avoid frequent resets that make results from different tests hard to distinguish.

Keep Other Usage Charges Separate

Data shows traffic from the app's perspective; it isn't the same as usage billed by your mobile carrier or an existing service. Differences in what is counted, protocol overhead, background requests, and the accumulation period can all affect the totals. A difference between two totals alone doesn't mean a charge is wrong.

An increase in traffic may come from other background activity. No increase may mean a request didn't use the current route, the connection wasn't established, or the statistics cover a different scope. Consider Global Routing, connection status, and request logs together.

06 · Common Settings

Settings: Change the Option That Matches the Issue

Check the options below in Settings and their related menus. Config files can also contain connection-related parameters, so confirm the active Config before changing settings. This helps avoid treating settings from different sources as if they were the same option.

DNS: Domain Resolution

What it does and where to find it: DNS translates domain names into addresses needed for connections. Check the DNS options in Settings and whether the active Config defines resolution parameters. The app's current configuration determines which settings apply.

How to configure it and what to watch for: Keep a record of the current settings, then adjust DNS to match your existing network setup. If some domains are unreachable, distinguish DNS failures from cases where an address is resolved but the connection fails. Don't change several DNS options at once. Changing DNS alone won't fix expired credentials or an unavailable server; an incorrect custom value may make the issue worse.

Test Method: Choose a Test Type

What it does and where to find it: Find Test Method in Settings. It determines how related connectivity tests are performed. It changes the test procedure, not the server's underlying route conditions.

How to configure it and what to watch for: Choose a method provided in the interface for your current troubleshooting goal, then return to Home and run Connectivity Test. Record the method along with the result. When comparing servers, use the same test method and network conditions. A timeout means the test got no response under those conditions; it doesn't prove that every real-world request will fail.

Today Widget: Quick Status and Controls

What it does and where to find it: Today Widget provides a system widget entry point where supported. Check its options in Settings. Whether it appears and which items it can control depend on system support and whether it has been added in the system interface.

How to set it up and what to watch for: First select a server and verify the connection in the app, then add an available widget in the system's widget editor. If its status doesn't update promptly, open the app and check the actual connection state rather than relying on the widget text alone. A shortcut can't replace initial authorization or supply missing server parameters.

iCloud: Sync Related Data

What it does and where to find it: iCloud options provide sync or cloud-data features supported by the app. Check the relevant option in Settings, then confirm your system iCloud account and permissions. Check each data type separately.

How to set it up and what to watch for: Enable the items you need after making a local backup, then wait for sync and verify each item on another device. Don't assume servers, Config, statistics, and every toggle will all sync completely. Syncing cloud data doesn't restore App Store purchases; check those separately.

Diagnostics: Gather Clues Before Changing Settings

What it does and where to find it: Diagnostics provides checks for connection-related status. Find it in Settings and run the checks available in the current interface. Diagnostic information helps narrow down an issue; it doesn't guarantee real-world results.

How to use it and what to watch for: When an issue occurs, record the network type, Global Routing mode, selected server, and symptoms, then run the relevant checks. Keep necessary error details in the results, but remove subscription URLs, authentication fields, and other private information before sharing. If you change networks or configurations for every check, the results won't be comparable. Keep conditions consistent and test one hypothesis at a time.

Setup Checklist

You don't need to enable every feature for everyday use. A safer approach is to verify the basic connection first, then add rules and automatic connection conditions. Keep a verified state at each stage so you have a clear point to return to if something goes wrong.

Check your details: The server type, address, and authentication parameters match the information you have. Subscribe updated successfully, and the intended entry is selected in Home.
Check the mode: Global Routing matches what you're trying to do. With Config selected, also check the active file, rule order, and FINAL.
Check access: Test the actual destination; don't rely only on Connectivity Test or Data figures. Record the test time, network conditions, and results together.
Set up automation afterward: Once the basic connection is stable, configure On Demand, Today Widget, and iCloud options. Test each one separately instead of combining changes.
Keep a way to restore changes: Record the original DNS settings or rules before editing. If a new issue appears, revert the most recent change first, then use Diagnostics to gather clues.

For step-by-step instructions from first launch, read the Shadowrocket setup guide. For specific issues such as an empty list or no access after connecting, see Frequently Asked Questions. For purchases and restoring previous purchases, see the App Store purchase guide. App purchases, server details, and cloud sync are separate.