Shadowrocket Official Manual

Modes and Settings

Choose how traffic is handled before adjusting automatic connections, DNS, and test methods. This page uses the iPhone / iPad interface labels to explain each path. Menus and available system integrations may differ on Mac, Windows, Android, and Linux; check the interface on your version instead of applying mobile-only settings to other devices.

Global Routing Rules and Policies Settings Reference

Global Routing: Config, Proxy, and Direct

What it does: Global Routing determines how requests handled by Shadowrocket are routed. Config uses the active configuration, Proxy sends traffic through a proxy, and Direct connects without a proxy. This is separate from the connection switch on Home: choosing a mode does not establish a connection or verify server settings. The mode names describe traffic handling, not connection quality.

Where to find it: Open Global Routing on Home to see the selected mode. Use Config for rule-based routing. Choose Proxy temporarily to bypass rule matching and check whether the selected server is available. Choose Direct to test access without a proxy server. Note the original setting before switching, then restore it when testing is done.

Mode	How It Handles Traffic	When to Use It	Check First
Config	Handles requests according to the Rules and policies in the active configuration.	Route selected sites through PROXY; handle other requests according to the rules, including direct connections or blocks.	The correct configuration is active in Config, with rule order and the final policy clearly defined.
Proxy	Routes traffic handled by the client through a proxy. System routes and exclusions may still affect the path.	Temporarily check whether rule matching is causing an issue.	A working server is selected on Home, and the service is available.
Direct	Connects directly to the destination without a proxy server.	Compare with a direct connection to see whether the proxy path affects access.	The current network can reach the destination. Direct does not disconnect the client.

How to set it: First select a server on Home, then choose a mode under Global Routing. Return to Home, turn on the connection, and allow Shadowrocket to add a VPN configuration if prompted. Test access to the same destination. If a problem starts only after switching from Proxy to Config, check the configuration before re-entering all server details.

Keep in mind: Proxy does not guarantee that every connection on the device goes through the proxy. System services, local network access, excluded routes, and app behavior can all affect the path. To see how a request was handled, check the connection log and matched rule. Direct is not a disconnect button; use the connection switch on Home to stop the client from handling connections.

Rules: Match Conditions and Policies

What a rule contains: A rule typically consists of a type, a match value, and a policy. DOMAIN matches an exact domain, DOMAIN-SUFFIX matches a domain and its subdomains, and DOMAIN-KEYWORD matches a keyword in the domain. GEOIP uses IP geolocation data. IP-CIDR and IP-CIDR6 specify IPv4 and IPv6 ranges, respectively. USER-AGENT depends on the request information available in a given context; it is not a universal way to identify traffic from every app.

Where to find it: Check which configuration is active in Config, then review its Rule list. PROXY sends matching requests to the proxy policy, DIRECT connects directly, and REJECT blocks the request. Global Routing's Proxy and Direct are mode names; PROXY, DIRECT, and REJECT in rules are policies applied after a match. Pay attention to capitalization and context.

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
DOMAIN-KEYWORD,ads,REJECT
GEOIP,CN,DIRECT
FINAL,PROXY

How to set it: Back up the current configuration first. In Rule, put narrowly scoped, specific rules before broader ones, then use FINAL for requests that have not matched earlier rules. In the example above, example.com and its subdomains match PROXY first; unmatched requests continue to the next rule. The example domain illustrates syntax and is not a proxy server.

Keep in mind: Rules are generally evaluated from top to bottom, so the first match can determine the result. A broad DOMAIN-KEYWORD rule may catch unrelated domains, and an early IP range rule may override later exceptions. When testing, keep Global Routing set to Config and check the matched rule; a page loading successfully does not prove that it used the intended policy. See the rules and configuration reference for full field and ordering examples.

Subscribe and Server Management

What they are: A server entry stores the address, port, protocol, and authentication details needed for a connection. Subscribe stores the URL for an existing subscription and can update a group of server entries. A subscription and a Config are different kinds of data: subscription updates maintain the server list, while a configuration controls DNS, rules, and other traffic handling. Importing one does not mean the other is set up.

Where to find them: View servers and subscription groups on Home. To enter a server manually, start with Add Server. To import an existing subscription, choose Subscribe and enter the full URL provided by your service provider. Scan QR Code is for an existing QR code; Import from Cloud JSON is for data in the supported format. Check the content type before importing so you do not mistake an ordinary web address for a subscription.

Confirm that the details you have are for Shadowsocks, VMess, VLESS, Trojan, or the actual protocol in use. Do not guess the type from its name.
For subscriptions, keep the full URL, including any required query parameters. For manual setup, enter the address, port, authentication details, and TLS settings individually.
Save and update, then confirm that the expected entries appear on Home. Select a server and run Connectivity Test.
Use recognizable labels for source groups. Compare the item count and check for inactive entries before and after an update; avoid importing the same source twice.

Keep in mind: An update may replace entries managed by that subscription. Keep a separate record of any server entries you edited manually. Before deleting a subscription, identify its group rather than clearing the entire list. Subscription URLs often contain personal access credentials; do not paste them into public screenshots when asking for help. If the server list is empty, check the URL, the service status, and the returned format before importing again. See Quick Start for the full steps.

On Demand: Connect on Demand

What it does: On Demand triggers or maintains the client connection based on network conditions. It controls when to connect; Rule controls how requests are handled after connecting. They are not interchangeable. Enabling On Demand does not fix server settings or route all traffic through PROXY. Global Routing and the active configuration still determine traffic routing.

Where to find it: Look for On Demand options in Settings. Available conditions and system behavior depend on the device; some versions may let you choose network types or specific networks. Read each condition before saving. Do not treat options that are not shown as required.

How to set it: Connect manually and confirm that access works before enabling On Demand. Set each condition for automatic connections, then save. Switch from Wi-Fi to cellular and back, and check the connection status on Home and actual requests. To stop automatic reconnections temporarily, disable the relevant On Demand conditions before turning off the connection. Otherwise, a system condition may turn it back on.

Keep in mind: Public Wi-Fi may require you to sign in through a captive portal first. If automatic connection interferes with sign-in, temporarily disable On Demand, complete sign-in, and then re-enable it. A short delay after switching networks does not necessarily indicate a rule problem; first check whether the client has reconnected. Before relying on On Demand, test while the device is locked, after waking it, and during network changes—not just on the current Wi-Fi network.

Data: View Traffic Statistics

What it shows: Data displays traffic and connection activity recorded by the client. Use it to check whether data is being transferred over time, whether uploads or downloads look unusual, or whether an action generated a request. These are client-side observations, not a service provider's billing record, and should not be used to estimate the remaining subscription allowance.

Where to find it: Open Data and check the reporting period, what triggers the count, and which categories are available. If the interface lets you filter by server or time, keep those conditions consistent when comparing results. For example, note the selected entry and time before comparing data across servers, or you may mistake a cumulative total for usage from a single visit.

How to use it: When troubleshooting, note the current figures and stop unrelated background downloads. Then perform one specific action, such as opening a page or downloading your own test file. Return to Data to check for changes, and review the connection log for the destination and policy. Before resetting statistics, save any information you still need, then use the reset option in the interface.

Keep in mind: System background activity, retries, and connection overhead may affect the totals. Whether DIRECT requests appear in a category depends on how that statistic is defined. An increase only shows that data was transferred; it does not prove the destination returned a complete response. If traffic is recorded but a page will not open, check DNS, TLS, server availability, and the matched policy instead of treating the total as proof that the service is working.

Settings: DNS and Test Method

DNS: Check the Active Configuration Before Changing Resolution

What it is and where to find it: DNS resolves domain names to IP addresses. Check the related options in Settings and the DNS fields in the active Config. The effect of a setting with the same name may also depend on the configuration, so do not change Settings without checking which configuration is active. Domain rule matching and the results of IP-based rules may also depend on the resolution process.

How to set it: Save the original value before making changes. First determine whether all domains fail or only a few destinations are affected. Change one DNS-related option at a time, retry the same destination, and check the resolution result. If using encrypted DNS, confirm that the current network and selected route can reach the DNS service. If you need a fixed domain mapping, understand what Host does; do not use a temporary IP address as a long-term substitute for normal DNS resolution.

Keep in mind: Changing DNS will not fix an incorrect password or port, or an expired subscription. Cached data may also delay the visible effect of a change. Before retrying, reconnect the relevant connection and, if needed, use the cache controls in the interface. For specific configuration fields and examples, check the configuration fields reference. Avoid replacing the entire configuration and DNS settings at the same time.

Test Method: A Successful Test Does Not Guarantee Access

What it is and where to find it: Test Method in Settings determines how Connectivity Test checks a server. Different methods test different layers: a successful port connection does not confirm that authentication, TLS, and access to the destination website all work. Request-based tests can also be affected by the test destination's status.

How to set it and what to keep in mind: Choose a test method available in your version. Keep the test destination and network conditions consistent when comparing servers. If one test fails, check the server details and test destination before deleting the entry based on a single result. Even if a test succeeds, turn on the connection and verify access to the actual destination. Compare reported times only under the same test conditions; they are not download speeds or a measure of performance across all websites.

Today Widget and iCloud Sync

Today Widget: Verify the Status After Using a Shortcut

What it is and where to find it: Today Widget provides a quick way to view or control Shadowrocket when supported by the system. Look for related options in Settings, then add it using the component management options available on your device. The widget's appearance, location, and available actions may vary by system version. It is not a standard entry point across all platforms.

How to set it and what to keep in mind: First select a server and connect from Home. Then add the widget and test its available actions. The widget may show a stale status; after tapping it, return to Home to confirm the selected server, Global Routing mode, and connection status. If the widget is missing, check system compatibility and app settings. There is no need to delete an existing configuration just to add a shortcut.

iCloud: Sync Scope and Recovery Order

What it is and where to find it: iCloud options support the data sync or cloud import available in your version. They depend on the device's iCloud status and permissions. App purchase history, client data, and subscription services are separate matters: signing in to the same iCloud account does not provide every subscription or guarantee that the same server list will appear on every platform.

How to set it: Check the sync options in Settings, make sure Shadowrocket is allowed to use iCloud on the device, and review the stated sync scope. Keep a copy of your local configuration before enabling sync for the first time. After importing or syncing on another device, check the configuration name, server groups, and active status before connecting. If entries have the same name, compare their fields before proceeding to avoid overwriting existing data with blank values.

Keep in mind: Sync is not a separate backup, and deletions or edits may propagate to other devices. Treat data containing subscription URLs or authentication details as sensitive, and do not store exported files in public folders. When troubleshooting across devices, check the account, permissions, and network before checking app data. Do not repeatedly delete all data to force a sync.

Diagnostics: Narrow Down the Cause

What it is and where to find it: Diagnostics provides tools for gathering clues; look for the options available in your version under Settings. It complements Connectivity Test on Home and the connection log: Diagnostics helps you inspect network and client status, Connectivity Test checks server test results, and the log shows individual requests. Use diagnostic information to narrow down the issue; a single error does not mean the entire configuration is broken.

Check the network first. Confirm that you have completed any network sign-in and that ordinary direct access works. If the network itself is unavailable, restore it before troubleshooting Shadowrocket.
Check the server details. Verify the address, port, authentication fields, and service status. Run Connectivity Test under the same conditions for a useful comparison.
Check the routing mode. Note which destination fails under Config, then switch to Proxy briefly for comparison. If the results differ, review Rule and the selected policy.
Check DNS and the handshake. Review the DNS result, TLS settings, and connection error separately. Do not confuse a resolution failure with an authentication failure.
Reproduce the issue before recording it. Record the steps, network, destination domain, current mode, and visible error. Restore the original settings after testing.

Keep in mind: Change one category of settings at a time. If you switch servers, change DNS, and replace Config together, even a successful fix will not reveal the cause. Before sharing logs or screenshots, hide subscription URLs, passwords, authentication fields, personal addresses, and other sensitive information. Keep only the error type and necessary context. If access fails for one destination, focus on that destination instead of resetting the entire setup.