Official Guide · Features and Settings

Shadowrocket Features
and Common Settings

First decide how traffic should be handled, then check the rules, servers, and connection conditions. Verify your setup against the results for actual requests—not just the connection toggle.

Routing: Global Routing
Request logs: Data
Connection conditions: On Demand

This guide focuses on using Shadowrocket on iPhone and iPad. Follow the English names shown in the app for menu paths and options. Check the App Store page for system requirements.

Traffic handling

Three Global Routing modes

Config, Proxy, and Direct determine the overall handling mode. Having rules in a configuration file does not mean current traffic is using them.

What it is: Global Routing is where you choose a routing mode. Config uses the rules in the active configuration; Proxy sends traffic handled by the app through the selected proxy policy; Direct uses a direct connection. Proxy and Direct here are interface options, while PROXY and DIRECT in rules are policy keywords. They operate at different levels.

Where to find it and how to set it: On Home, open Global Routing, select a mode, then return and confirm the selected server and connection status. For first-time use, make sure an existing server connects. For everyday rule-based routing, switch to Config and check which file is active on the Config page. Importing a file alone does not make it active.

Mode	How traffic is handled	When to use it	What to check
Config	Rules and their assigned policies in the active configuration	Everyday routing by domain, address, or other criteria	Whether the file is active, rule order, and the final matching policy
Proxy	The selected proxy server or policy	Temporarily checking the proxy path without interference from routing rules	Server settings, authentication details, and connectivity to the target
Direct	The direct connection path on the current network	Comparing baseline network behavior and checking local connectivity	Local network and DNS; this does not verify proxy connectivity

Keep in mind: Existing long-lived connections may retain their original state after you switch modes. To verify a change, make a new request; if needed, close and reopen the test app. Proxy is useful for comparison, but it does not prove that every rule in Config is correct. If a site works in Direct, that only confirms the direct path worked for that particular test.

Separate match conditions from policies

Rule-Based Routing and Match Order

Rules first define what to match, then specify how to handle it. When using Config, check both the order and the policy names.

What it is: Rule-based routing selects a policy based on information such as a request's domain or destination address. DOMAIN matches a specific domain, DOMAIN-SUFFIX matches a domain suffix, and DOMAIN-KEYWORD checks for a keyword in the domain. IP-CIDR and IP-CIDR6 match address ranges, while GEOIP uses IP geolocation data. Rules rely on different information, and DNS resolution can affect address-based matches.

Where to find it and how to set it: In Config, open the active configuration for editing and check the [Rule] section. In general, put more specific conditions before broader ones and default handling rules near the end. DIRECT means direct connection, PROXY routes traffic through a proxy policy, and REJECT blocks it. If you use a custom policy name, make sure it exists in the active configuration.

Rule syntax example · Not a complete configuration file

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

The example first matches a specific domain suffix, then handles a private-network address range. If no earlier rule matches, FINAL determines what happens next.

Keep in mind: Rules are checked in order, so an earlier broad condition can prevent a later, more specific one from being reached. FINAL handles requests that do not match earlier rules; do not place it before rules that still need to be checked. Conditions such as USER-AGENT also depend on information available to the client, so they may not apply to all traffic. After making changes, check the actual match in Data—this is often the quickest way to spot an ordering issue.

If a configuration includes DNS, Host, or other sections, consider how they affect requests too. Don't replace the entire configuration to fix one website. Back up the current file, change only the relevant rules, then make the same request again for comparison.

Connection details and configuration files

Subscriptions and Server Management

Server entries store connection details; configuration files control behavior such as routing rules. Updating a subscription and switching configurations are separate actions.

What it is: Server entries store the address, port, protocol, authentication, and other connection details. Subscribe is for managing subscriptions you already have. Shadowrocket supports protocols including Shadowsocks, VMess, VLESS, Trojan, WireGuard, Hysteria2, HTTP, and SOCKS5. The protocol name is only one part of the setup: transport, TLS, and authentication settings must also match your server details.

Where to find it and how to set it: From Home, open Add Server. If you already have a subscription, choose Subscribe, enter your subscription URL, and add a label to identify it. For a single server, select its protocol and enter the details field by field. If you have a QR code, use Scan QR Code. Before importing from the clipboard, confirm that it contains the connection details you intend to add.

After importing, check that the expected entries appear in the list, then verify the protocol, address, port, and required security settings. Select an entry and run Connectivity Test, then make an actual request. A test response only confirms a result under those test conditions; it does not prove that authentication, DNS, rules, and the destination service are all working.

Keep in mind: Subscription updates may change server names, counts, or settings, and can overwrite manual edits to subscribed entries. Use separate labels for manual entries and subscriptions, keep any necessary backup before updating, and check the selected entry afterward. Never share a failed subscription URL, QR code, or complete connection link in screenshots or discussions; it may contain credentials.

Check subscriptions and routing configurations separately: updating the server list does not necessarily change the rules in Config, and switching Config does not refresh server details. For managing multiple subscriptions, sharing, backups, and deletion, see the Subscription and Server Management Guide.

Manage connections based on network conditions

On Demand Connections on Demand

On Demand controls when a connection is attempted. Global Routing controls how traffic is handled after connection. They are not interchangeable.

What it is: On Demand works with system triggers to start a connection when specified network conditions are met, reducing the need for manual actions when switching networks. It does not guarantee that a server is available and is not a routing ruleset. Once connected, requests are still handled according to the current Global Routing mode and configuration.

Where to find it and how to set it: In Settings, open On Demand and review the conditions available on your device. Start with one easy-to-check scenario, such as setting connection behavior for the current Wi-Fi network. After saving, leave Settings, switch networks once, and check both the system connection status and Shadowrocket's status. Add more conditions only after confirming the behavior is as expected.

Keep in mind: With On Demand enabled, the system may reconnect when its conditions are met. So if the connection appears again after you manually disconnect, the toggle may not be broken. Check the On Demand conditions first. To temporarily stop automatic connections, adjust those conditions and verify the result after switching between Wi-Fi and cellular. Don't judge by a single manual disconnect.

If other network configurations are present during testing, note their current state and rule out possible interference one item at a time. Change only one condition per test and keep settings easy to restore; this helps identify whether the cause is On Demand, the local network, or the server connection.

Use results to review your setup

Data Usage and Request Logs

Data helps you review connections and traffic handled by the app. When troubleshooting, details for the target request are usually more useful than cumulative totals.

What it is: Data provides views of traffic and connection records, helping you check request destinations, handling policies, and related connection details. It reflects data the app can record; it is not a provider's billing statement, and a summary total alone cannot show all network activity from an app.

Where to find it and how to use it: Open Data and check the available statistics and log views. To verify a rule, note the test time, open just one target page, then return to Data and find the corresponding request. Check its destination domain or address and the displayed policy. To compare two Global Routing modes, make a fresh request in each mode and keep the results separate so an older log is not mistaken for a new test.

Keep in mind: A page may contact multiple domains, and an app may keep background connections open. Seeing the main domain use PROXY does not prove that every page resource uses the same path. Statistics periods, log retention, and caching can also affect what you see. Before clearing data, check whether you still need it for troubleshooting.

When sharing logs, include only entries relevant to the issue and hide subscription URLs, authentication fields, and other personal information. Describe the routing mode, network type, test destination, and steps to reproduce the problem instead of posting a full configuration.

Check common settings one by one

Settings and Diagnostic Tools

Configure each feature according to its purpose. If an option is not shown on your device, follow the interface on that device rather than assuming settings from another environment apply.

DNS: Separate name resolution from connectivity

What it is and where to find it: DNS resolves domain names to addresses. Check both DNS-related options in Settings and DNS settings in the active Config. Looking at only one location is not enough to determine the final behavior.

How to set it and what to check: Note the current values first, then check the resolution method and whether the specified server is reachable from your current network. If a test responds but a website won't load, check separately whether the domain resolves, whether the returned address looks appropriate, and how the DNS request is routed. Don't change the resolution method, rules, and server all at once. Restore a known working setup, then compare one change at a time. For more steps, see DNS Resolution Troubleshooting.

Test Method: Keep test conditions consistent

What it is and where to find it: Test Method determines how relevant connectivity tests are performed. Check the current selection in Settings. Different methods check different parts of the network, so their results are not directly comparable.

How to set it and what to check: Use the same Test Method and local network when comparing servers. If the selected method requires a test target, check its settings too. A method may fail because of the target or protocol response; that alone is not a reason to delete a server. A faster test result also does not mean faster large-file transfers. Use real requests to confirm that the connection meets your needs.

Today Widget: Check status before acting

What it is and where to find it: Today Widget settings control related system widget shortcuts or status displays. Check the corresponding option in Settings. Available widget locations and interactions depend on what your device currently supports.

How to set it and what to check: First select a server and confirm the initial connection in the app, then add an available widget through the system's widget management screen. Return to Home and check the actual connection status. If the widget has not refreshed, don't rely on its appearance alone to determine whether the connection is active, and avoid repeated toggling that could confuse test results.

iCloud: Keep a backup before syncing

What it is and where to find it: iCloud options are for saving or syncing data across devices. Open the corresponding option in Settings, read the current on-screen description, and distinguish what each sync, import, or restore action will do.

How to set it and what to check: Check your device's iCloud status first, back up the configurations and records you want to keep, then enable or run the relevant action. On another device, check Config and server details individually rather than assuming everything synced. Syncing does not restore an app purchase; app access is through the App Store. Before overwriting or deleting anything, confirm what the action affects.

Diagnostics: Trace issues by layer

What it is and where to find it: Diagnostics is the troubleshooting section in Settings. Review the tools and output available on your device. Diagnostics can provide clues, but it does not replace checking server details and configuration files.

How to use it and what to check: Reproduce the issue with as few steps as possible, then run checks relevant to the problem. Check the local network, DNS, server connection, rule match, and destination response in turn. Note which layer fails instead of saving only the final error message. Before exporting, check for credentials or personal information, and keep before-and-after results for comparison.

Verify your settings

Change only one condition at a time

Check connection status, DNS resolution, rule matches, and destination responses separately. Don't use the result of a single test to judge the entire path.

Check your details. On Home, verify the selected server and confirm that its address, port, protocol, and authentication fields match your own details. If you use a subscription, check that the latest update retrieved the expected entries.
Check the mode. Confirm whether Global Routing is set to Config, Proxy, or Direct. To verify rule-based routing, use Config and check which file is active and the rule order on the Config page.
Make a fresh test request. Revisit a clearly defined destination to avoid reusing an old connection. Note the local network and test time; don't change the server, DNS, and rules at the same time.
Review the result. In Data, check the request destination and handling policy. If connection behavior keeps changing, check On Demand. If domain resolution is failing, troubleshoot DNS.
Keep a way to revert. Record the purpose of any change that helps; revert changes that do not improve the issue. If further investigation is needed, document the minimum steps to reproduce it and share diagnostic results with sensitive information hidden.

For the complete process, from first import to connection testing, see the Getting Started guide. For organizing existing subscriptions, updates, and backups, see Server Management. Shadowrocket is available only on Apple platforms, exclusively through the App Store. Check the App Store page for purchase, compatibility, and system requirements.