Official Manual · Features and Settings

Shadowrocket
Modes and Settings

Use Global Routing to choose a routing mode, then check rules and servers. On Demand controls connection triggers, while Data and Diagnostics help verify results. These settings serve different purposes and are not interchangeable.

Compare the Three Modes Follow the Setup Steps

Global Routing: The Three Modes

Config, Proxy, and Direct are the corresponding in-app mode names.

Global Routing selects how traffic is routed; it does not create servers or turn the connection on or off. Find Global Routing on Home and choose Config, Proxy, or Direct. Then check the selected SERVER and connection status. If you’re new to the app, first verify your existing server details. Run a brief test to see whether the connection works, then return to Config to check the rules. After switching modes, make a new request; an existing long-lived connection is not a reliable way to confirm the change took effect.

Mode and In-App Name	Routing Behavior	When to Use It	Notes
Configuration · Config	Routes connections using the active configuration and applies policies matched by [Rule].	For everyday rule-based routing or to check whether a domain uses DIRECT, PROXY, or REJECT.	First confirm which Config is active, then check the rule order and FINAL.
Proxy · Proxy	Routes the main connections through the currently selected proxy server instead of applying ordinary rules one by one.	Briefly test whether a server can handle a target request and narrow down rule-related issues.	System routing, necessary bypasses, and network conditions still apply. This does not guarantee that every connection on the device will use the proxy.
Direct · Direct	Routes the main connections directly without forwarding them through a proxy server.	Compare access over your local network to distinguish direct-connection issues from proxy-path issues.	Direct does not turn off the VPN connection. To disconnect, use the connection switch on Home.

Compare the Same Target; Change One Setting at a Time

If Proxy works but Config doesn’t, check the matched rules, policies, and DNS settings in Config first. The issue may be with the routing path rather than all server settings. If both Proxy and Config fail, check the server, local network, and protocol parameters. The result in Direct only reflects the direct connection path; it cannot confirm whether a proxy server is working.

For each test, note the current mode, selected server, and target domain. Restore the original settings afterward. Don’t leave the app in a mode that differs from your intended setup just to troubleshoot one issue. After changing the configuration file, check Global Routing again instead of relying only on the connection switch on Home.

Rule Types and Policies

A rule type specifies what to match; a policy specifies what to do when it matches.

Check [Rule] in Config

Under Config, routing rules select a path for each connection based on conditions in the configuration. Open the active configuration in Config and read [Rule] from top to bottom. Ordinary rules typically stop further matching once a match is found, so put specific conditions before broader ones. Place FINAL at the end to handle requests that do not match an earlier rule.

DOMAIN matches an exact domain; DOMAIN-SUFFIX matches a domain and its subdomains; DOMAIN-KEYWORD matches a keyword in the domain. IP-CIDR and IP-CIDR6 specify IPv4 and IPv6 ranges, respectively. GEOIP uses an IP geolocation database. USER-AGENT matches available User-Agent information; don’t assume it can identify every connection’s app.

The PROXY policy routes traffic through the proxy path, DIRECT connects directly, and REJECT blocks the request. A policy name does not indicate server health or provide server settings. First check which rule matched, then determine whether the resulting connection succeeded.

Rule Example, Evaluated Top to Bottom

# Example syntax only; not a general-purpose configuration
[Rule]
DOMAIN,api.example.com,PROXY
DOMAIN-SUFFIX,example.com,DIRECT
DOMAIN,blocked.example.net,REJECT
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
FINAL,PROXY

api.example.com matches the first line and won’t reach the example.com suffix rule. Other example.com subdomains can match the second line; remaining requests continue to the next rule.

no-resolve prevents an extra domain lookup solely to match this IP rule; it does not disable DNS globally.

Check Rule Order, Not Just Keywords

Two syntactically valid rules can still produce opposite results. For example, a broad DOMAIN-SUFFIX rule placed before a specific DOMAIN rule can prevent the latter from matching. Back up the current configuration before editing. Change only the relevant rule order or policy, then verify with a new connection. IP rules also depend on the available resolution results. GEOIP relies on a database and should not be treated as precise proof of a service’s actual deployment location. For full syntax and configuration sections, see the rules and configuration reference.

Subscribe and Server Management

Server settings determine how to connect; routing rules determine when to use a connection.

Add Existing Details with Add Server

On Home, tap Add Server, choose the matching Type for your existing details, then enter the address, port, authentication, and transport parameters. Fields vary by type, including Shadowsocks, VMess, VLESS, Trojan, HTTP, SOCKS5, WireGuard, and Hysteria2. Don’t copy settings from another type just because the address is the same. TLS, the server name, and transport options must also match the requirements of your existing server. Don’t hide incorrect settings by disabling verification.

After saving, return to Home and check the selected item under SERVER. A server appearing in the list does not mean the connection is using it. When adding a server manually, choose a recognizable name, but don’t include passwords, keys, or a full subscription URL. They could be exposed in the list or when sharing diagnostic information.

Subscribe Updates Existing Subscription Content

You can usually add an existing subscription by choosing Subscribe under Add Server. Enter your own subscription URL, save it, and use the update action for that entry. Then check that the server entries appeared and that the current selection is still what you expect. Treat access credentials in a subscription as sensitive: don’t paste them on public pages or into unrelated testing tools.

A failed subscription update is different from a failed server connection. Updating depends on whether the subscription URL is valid, the current network can reach it, and the returned content can be read. A server connection depends on its protocol, authentication, and transport. A successful update does not mean every server can connect. Before deleting a subscription, check whether its associated entries will also be removed. Manually edited entries generated by a subscription may be overwritten by a later update.

Connectivity Test Checks Specific Test Conditions

Before using Connectivity Test on Home, check Test Method in Settings. Different methods may check only for a port response or also make a request to a specified target. A passing test doesn’t mean every website and app will work, and a failing test may be caused by the test target or method. Consider the result alongside an actual request to the target rather than relying only on the test indicator in the list.

On Demand Connections

Controls when connections are triggered; it does not replace Global Routing or [Rule].

Verify a Manual Connection Before Enabling Conditions

On Demand lets the system trigger or maintain a VPN connection based on configured conditions. First connect manually on Home and confirm the server and Config work. Then check the On Demand switch and available conditions in Settings. Available conditions depend on what the app currently displays. If conditions involve Wi-Fi or cellular networks, confirm each one’s scope. Automatic connection does not mean automatic selection of the fastest server.

After setup, test again under the expected network conditions and check the connection status on Home. Switching between Wi-Fi and cellular may rebuild the existing connection; a brief interruption does not necessarily indicate a rule syntax issue. First check whether the trigger conditions were met, then review routing after the connection is established.

Check On Demand When Pausing a Connection

If the connection returns after you disconnect manually, first check whether On Demand is still enabled and whether the system retriggered it under an existing condition. To pause it, adjust On Demand before using the connection switch, then confirm the status stays as expected. Don’t repeatedly change settings in different places without noting the order.

On Demand cannot fix expired credentials, an incorrect port, or an invalid configuration. If the connection still doesn’t work after it is triggered automatically, return to the manual connection steps to find the cause. For work networks with specific connection requirements, check network policies and local resource access before enabling automatic connections.

Data Usage Statistics

Use counter changes as a cross-check, not as a substitute for your network bill.

Data shows traffic information the app can record. Open Data, review the displayed scope and counter descriptions, then check how values such as upload and download change before and after connecting. Different views may cover different periods or items; don’t add a session, an individual entry, and a long-term total together. Counters may update with a delay, so no visible change over a short period does not prove that no request was made.

Track Changes During a Repeatable Test

First stop unrelated background network activity and note the current counters in Data. Open a fixed page or make a known request, then return to Data to compare the change. Before clearing counters, save any information needed for troubleshooting, then use the reset option provided on the page. For comparable tests, use the same target, roughly the same duration, and the same statistics scope. Otherwise, differences in test conditions can be mistaken for differences in mode performance.

Data counters are not the same as cellular carrier billing or the usage allowance for a connection service you already have. Protocol overhead, retransmissions, the statistics source, and the billing period can all affect the numbers. To check whether a domain matched PROXY or DIRECT, review connection records alongside the active rules. An increase in traffic alone does not show that every request used the same path.

Common Settings

Use the labels and options currently shown in the app; change one variable at a time.

Settings features and the Config file may both affect connections. Before looking for an option, identify whether you’re changing a global preference, the active configuration, or a system permission. Similar names don’t necessarily mean settings belong to the same layer. App navigation may change; the English names below help you locate options without relying on fixed menu positions.

DNS: Distinguish Resolution Failures from Connection Failures

DNS resolves domain names to addresses needed for connections. Check DNS-related options in Settings and the [General] section of the active Config for settings such as dns-server. Changing one without checking the other may leave a relevant setting untouched. During troubleshooting, keep the original value and determine whether the domain fails to resolve, resolves to an unexpected address, or resolves correctly but still can’t connect before making changes.

For example, dns-server = system is one way to configure the app to use system DNS settings; it is not a recommendation for every network. Changing DNS can affect IP rule matching and the actual connection target, but it can’t fix server authentication errors. Make a new request after testing and account for existing DNS cache. One successful request doesn’t mean all domains are working again.

Test Method: Know What Connectivity Test Checks

Find Test Method in Settings, read the descriptions of the available options, and choose a test method. If it requires a target address, check that the target itself is reachable. A port-level response is not the same as completing an app-level request, so results from different methods are not directly comparable. After changing the method, return to Home, run Connectivity Test again, and verify access to the same target directly.

Test results are intended to help narrow down options and locate problems; they don’t represent sustained throughput or the experience of every request. If a test fails but normal use works, check the method and target before changing all server details.

Today Widget: Quick Access and System Requirements

Today Widget provides quick viewing or controls in supported system widget locations. First check related options in Settings, then see whether the widget can be added from the system’s widget editor. Available forms depend on the device’s system and the features currently supported by the app. Don’t assume a particular widget style is available on every device.

Quick access still depends on saved servers and configurations, as well as connection permissions. After tapping the widget, check the actual status on Home, especially after restoring data or before completing the app’s initial setup. A widget is not a separate source of connection settings and does not replace checking the current SERVER.

iCloud: Handle Data Sync and Restoring Purchases Separately

To keep settings across devices, check the iCloud sync option in Settings and make sure the system allows Shadowrocket to use iCloud. Back up important configurations first and compare the existing content on both devices. Sync is not a versioned archive you can always roll back. Verify the actual entries after syncing; an enabled switch alone does not confirm that sync completed.

App Store purchase history restores your eligibility to get the app; iCloud syncs app data when supported. These are separate processes. After moving to a new device, even if the app is installed, check server details, the selected Config, and VPN authorization. Check the in-app description for sync scope. Server credentials and subscription content may be sensitive, so verify the signed-in account and device access permissions before use.

Diagnostics: Keep Context Before Collecting Diagnostic Data

When an issue occurs, find Diagnostics in Settings and use the diagnostic or logging options provided by the app. Note when the issue occurred, the network, Global Routing mode, selected server, and failed target, then reproduce the issue once. This context helps distinguish DNS, authentication, transport, and rule-matching problems and is more useful than an isolated error message.

Before sharing records, check for domains, IP addresses, subscription URLs, authentication details, and personal browsing information. Remove anything sensitive that isn’t needed. A failed request in the log does not prove that all connections are unavailable; consider the time it occurred and repeat the test with the same target. After troubleshooting, restore any temporary diagnostic settings to avoid keeping unnecessary records.

Verification Order After Setup

Verify the basic connection first, then add routing rules and automatic triggers.

Check existing details. Confirm SERVER on Home. After importing a subscription, check that its entries are complete; after adding a server manually, verify the protocol, address, port, and authentication.
Run a repeatable connection test. Confirm Test Method, briefly compare with Proxy, and access a specific target. If the test fails, troubleshoot the basic connection first.
Return to Config and verify the rules. Confirm which configuration is active, check the order of [Rule] entries and FINAL, then make a new request to the target and review its record.
Enable On Demand next. Once manual connections work, test the trigger conditions. Check the status again after switching networks; automatic triggers and rule matching are separate.
Save results and restore temporary settings. Record the verified configuration and back it up before making further changes. Use Data and Diagnostics as supporting checks, not a single test result as the final verdict.

For an initial setup, continue with the Shadowrocket setup guide. To understand a configuration line by line, see the rules and configuration reference. If you haven’t purchased the app, first review the steps to verify the developer, official icon, and app ID, then get it from the App Store.