Official Manual · Features and Settings

Shadowrocket
Proxy Modes and Settings

First choose how Global Routing should work, then check your server and configuration. The connection switch, routing rules, and On Demand each control a different part of the process, so verify them separately.

Home
Config
Data
Settings

01 · Choose a routing mode

Three Global Routing modes

Use Config for everyday rule-based routing, Proxy to test the proxy connection temporarily, and Direct to compare with a direct connection. Open Global Routing on Home and select the mode you need. This setting determines how requests entering the app are handled. It does not turn the connection on or fix server addresses, authentication details, or DNS settings.

Mode	How it works	When to use it	What to check
Config `Config`	Routes traffic according to the rules in the active configuration.	When different domains or addresses need different policies.	Whether the configuration is enabled, rule order, and the final fallback policy.
Proxy `Proxy`	Handles traffic entering the app in proxy mode. Keep system traffic scope and app-specific exceptions in mind.	To check briefly whether routing rules are causing an issue.	Whether the selected server is available and can connect to the destination.
Direct `Direct`	Handles traffic entering the app as direct connections.	To compare direct connectivity on the current network.	Whether the current network can reach the destination and DNS is working.

Config: rules determine where traffic goes

In Config, confirm which configuration is active, then return to Home and set Global Routing to Config. A matching rule may use PROXY, DIRECT, REJECT, or a policy group defined in the configuration. Selecting a server on Home does not mean every request will use it: a rule that specifies DIRECT sends the request over a direct connection.

Proxy and Direct: narrow down the cause

If the same destination works in Proxy but fails in Config, check the matching rule and its policy reference first instead of immediately changing every server field. If Direct works but Proxy fails, check the selected server, authentication, and transport settings. Comparing modes can help narrow down the issue, but one test alone cannot establish the cause.

After switching modes, close and reopen the test page. If needed, reconnect in the app to avoid existing connections affecting the result. Restore your intended mode when testing is done. Leaving Proxy enabled as a temporary troubleshooting setting will change your usual routing behavior.

02 · Check what the rules match

Rule Types and Policies

Rules specify what to match; policies specify what to do with a match. Open the active configuration in Config and review or edit its Rule section. Rules are generally evaluated in the order they appear, and the first match determines the result. Place specific rules appropriately and use FINAL as the last-resort rule.

Rule type	What it matches	Notes
`DOMAIN`	The exact domain specified.	Useful when you want to handle one specific domain.
`DOMAIN-SUFFIX`	The domain itself and its subdomains.	Enter a domain, not a full webpage URL or path.
`DOMAIN-KEYWORD`	A keyword in the domain.	May match more broadly than expected; watch for unintended matches.
`GEOIP`	The geographic region associated with an IP address.	Results depend on the address database in use.
`IP-CIDR` / `IP-CIDR6`	An IPv4 or IPv6 address range.	Check the address type and prefix length.
`USER-AGENT`	Recognized User-Agent information.	A match depends on whether the relevant information is visible in the request.
`FINAL`	Requests not matched by earlier rules.	Place it at the end of the rules to define the final outcome.

PROXY, DIRECT, and REJECT explained

PROXY routes traffic through a proxy, DIRECT connects without a proxy, and REJECT blocks the request. These uppercase keywords are configuration syntax, not the same level of control as the Proxy and Direct options in Global Routing: the keywords define the outcome of an individual rule, while the interface options set the overall routing mode. If you use a custom policy name, make sure it is defined in the configuration.

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

This example demonstrates syntax; it is not a complete configuration for every network. The first rule matches only example.com; the second matches example.org and its subdomains. Keyword rules have a broader scope, so understand which requests they affect before copying them. Don’t add duplicate rules just to increase the rule count, and don’t place FINAL before rules that still need to take effect.

Save a copy of the original configuration before editing. Change one small group of rules at a time, then check the actual policy for the target domain. For a section-by-section guide to General, Rule, Host, and URL Rewrite, see the complete rules and configuration reference →

03 · Connection details

Subscriptions and Server Management

Server entries store connection parameters; subscriptions fetch and update those entries in batches. This section assumes you already have your own subscription or server details. On Home, use Add Server to add them. Choose Subscribe to enter your own subscription URL. To add a server manually, select the correct protocol first, then enter the fields from your source details.

Add Server: match each protocol to its fields

Shadowsocks, VMess, VLESS, Trojan, HTTP, SOCKS5, WireGuard, and Hysteria2 do not all use the same parameters. Matching addresses and ports do not make entries interchangeable. Use your own server details for the password, UUID, TLS, transport method, and related fields. Some fields appear only after you select the relevant protocol or transport method.

If you have a single server share link, use the import option provided in the app. For a QR code, use Scan QR Code. After importing, open the entry and check its protocol, address, port, and authentication fields. Don’t rely on the display name alone to confirm an import succeeded: the entry’s parameters determine the connection.

Subscribe: understand updates and local edits

Refreshing a subscription fetches its contents again from the URL. If a subscription manages an entry, local edits may be overwritten during a later refresh. Before making changes you need to keep, check where the entry came from and how the app currently saves it. If you have multiple subscriptions, use clear labels and check the group before deleting obsolete items to avoid mistaking similarly named entries for duplicates.

A successful subscription refresh means its contents were fetched and parsed; it does not mean every server is reachable. Likewise, a failed refresh does not necessarily make saved entries unusable right away. Check subscription retrieval and server connectivity separately.

See how to import an existing subscription and connect for the first time →

04 · Automatic connection conditions

On Demand connections

On Demand asks the system to establish a connection when configured conditions are met; it does not replace routing rules. Open On Demand in Settings and review the available conditions and switches. Options depend on the current app interface. First confirm that a manual connection works, then enable On Demand so you can distinguish connection issues from trigger-condition issues.

How to configure and verify

On Home, select a server and Global Routing mode, connect manually, and open the destination you want to test.
Open On Demand, read what each available condition does, and enable the options you need. If a condition refers to a network name, make sure it matches the network your device is actually connected to.
Switch to the target network or meet the trigger condition again. Check the system connection status and confirm that the request succeeds.
If the result isn’t what you expected, turn off On Demand temporarily and verify the connection manually. Don’t change rules and server parameters at the same time.

On Demand and Config can work together: On Demand controls when a connection is established, while Config determines the policy for requests after the connection is up. A system connection indicator does not mean every request goes through a proxy; Config may still contain DIRECT or REJECT rules.

If the connection comes back after you disconnect manually, check whether an On Demand condition is still active instead of repeatedly deleting configurations. On the first connection, authorizing the system VPN configuration is part of the system setup flow; after allowing it, you still need to verify the app settings. Network changes, system scheduling, and condition matching can all affect what you observe. On Demand is not a separate switch for each app request.

05 · Check usage

Data usage statistics

Data shows traffic recorded by the app; it is not a bill from your service provider. Open Data and review uploads, downloads, and related records for the range shown in the interface. To compare a test, note the starting value, perform one clearly defined action, then check for changes. Before using a reset option, confirm you no longer need the existing statistics.

What traffic totals can tell you

An increase means the app recorded data activity within the displayed statistics scope. By itself, that does not prove a webpage loaded fully or show which server handled the traffic. Background apps, sync tasks, and repeated requests may all generate traffic. To determine how a particular destination was routed, check the current mode, matching policy, and connection records—not just the total.

Why totals may differ from your service provider’s records

The two sides may use different billing periods, reset times, protocol overhead calculations, or billing rules. Treat app statistics and your service provider’s records separately. For remaining allowance, refer to your own service provider’s information. Resetting local statistics does not reset the provider’s usage records.

For troubleshooting, use a consistent test: pause unnecessary background activity, note the current Data value, visit a known destination, then compare the change. This helps reduce interference, but it is not a precise measure of billable traffic. Check for personal browsing information before sharing statistics that include destination details.

06 · Common options

Settings guide

Settings brings together options for testing, shortcuts, sync, and diagnostics. Some network behavior is also controlled by the General section of the active configuration. For any issue, first identify where the relevant setting lives, then change it there. Similar setting names do not necessarily affect the same part of the request path. Whether an option appears and where to find it depend on the current app interface.

DNS: check the resolution path first

DNS translates domain names into addresses needed for a connection. Check DNS options in Settings alongside the General section of the active Config. Focus on which resolver is used, which path requests take, and whether the configuration specifies anything else. Note the original values before making changes. After saving and reconnecting, compare results using the same domain.

Don’t assume DNS is working just because Connectivity Test shows a result: some tests only check whether a server endpoint is reachable, which is different from resolving a webpage’s domain. If only domain-based access fails, check DNS first. If the domain resolves but the connection still fails, check the destination policy, server path, TLS, and other steps. Stacking DNS options you don’t understand makes troubleshooting harder.

Test Method: know what the test measures

Test Method selects how Connectivity Test runs. Find it in Settings, choose an option based on the available methods and descriptions, then test an existing server from Home. To compare entries, use the same method, destination, and network conditions where possible; otherwise the results may not be comparable.

Test results show reachability or response under the conditions at that moment. They are not a measure of bandwidth and do not guarantee that every website will work. If a test returns a result but a webpage fails, check the webpage domain, rules, and DNS. If a test fails, distinguish an unreachable test target from an actual proxy connection failure before deleting an entry that may still work.

Today Widget: a shortcut for common actions

Today Widget settings configure the related options for a system-supported widget. Check them in Settings. Whether you can add the widget, which actions it displays, and where it appears depend on system and app support. Use the widget list available on your device. First confirm that the connection works in the app, then try the widget controls.

A widget is a shortcut; it does not replace server settings, Global Routing, or system VPN authorization. If the widget display doesn’t match what happens when you connect, return to Home and check the current connection and mode rather than judging traffic routing by the widget’s appearance.

iCloud: check sync and local storage separately

iCloud features save or sync information within the scope supported by the app. Check the iCloud options in Settings, make sure your device is signed in to your own Apple Account, and confirm that the system allows the app to use iCloud. Before enabling sync, save a copy of important configurations. Afterward, check which items the app actually shows as synced and confirm the result.

Don’t assume enabling iCloud syncs every server, authentication detail, configuration, statistic, or temporary state. When using multiple devices, check items individually, especially the active configuration and selected server. App purchase records, iCloud-synced data, and your own service provider account are separate. A completed sync does not replace testing the connection again.

Diagnostics: gather evidence before making changes

Diagnostics lets you view or collect information related to app issues. Open the relevant option in Settings and follow the instructions. First note the network, Global Routing mode, destination, and steps involved when the issue occurred; then review the diagnostic output so you can relate it to the failure.

Don’t treat a single warning as the whole explanation. Compare diagnostic information with Connectivity Test, DNS, and rule results. Before sharing anything, remove subscription URLs, server credentials, personal domains, and other sensitive details. Note original settings before changing them so you can tell whether a change helped.

07 · Verify each layer

Setup Verification and Troubleshooting

Change one condition at a time and retest the same destination. If you change the server, mode, configuration, and DNS all at once, even restored access won’t tell you which change worked. Start with a small, repeatable test, then check the following in order.

Check the current network. Confirm that the device can access the internet normally. Record results separately when switching between Wi-Fi and cellular so you don’t mistake a network change for a configuration change.
Check the server entry. Verify the protocol, address, port, authentication, and required transport fields. Confirm that the selected entry comes from the subscription you expect.
Check the connection status. Verify the connection action on Home and system authorization. A selected server does not mean a connection has been established.
Compare routing modes. Test Proxy and Config against the same destination. If only Config fails, check the rules and policy references. If both fail, continue by checking the connection path and DNS.
Check DNS and diagnostics. Distinguish between a failed lookup, a connection that cannot be established, and a request that fails after connecting. Don’t attribute every symptom to a single rule.
Restore your everyday settings. Keep changes that proved effective, restore any temporary mode switches, then test On Demand and shortcuts.

Why do some requests bypass the proxy in Config mode?

Config routes requests according to the active configuration. A request may match DIRECT or enter a policy group that includes a direct connection option. Check the active configuration, rule order, and the policy actually matched. The server selected on Home alone does not determine where every request goes.

Do I still need to set Global Routing when On Demand is enabled?

Yes. On Demand controls when a connection is triggered; Global Routing controls how traffic is handled. First verify the server and mode manually, then enable On Demand and check its trigger. Confirm each part separately.

Why won’t a webpage load if Connectivity Test succeeds?

The test and webpage may use different destinations and network paths. Check DNS resolution for the webpage’s domain, its policy in Config, the connection from the selected server to the destination, and the failure details in diagnostics. A test result does not replace checking actual access.

To make your first connection, read the import and connection tutorial. To review rules one by one, see the complete configuration reference. For help with purchasing, installation, and common connection issues, browse Troubleshooting by topic.