Official Guide · Features and Settings
Shadowrocket Features and Common Settings
First decide how traffic should be handled, then check the server, connection conditions and diagnostic results. Each setting controls a different part of the process, so there’s no need to change everything at once.
This page focuses on using Shadowrocket on iPhone and iPad. The layout and available options may vary; check the App Store listing for system requirements.
Choose rule-based routing, proxy routing or a direct connection.
Apply traffic policies according to rule order.
Use real-world access attempts to pinpoint where a connection fails.
Home → Global Routing
The Three Global Routing Modes
For everyday rule-based routing, choose Config. Use Proxy or Direct for targeted, temporary checks.
Global Routing determines how traffic within the client’s scope is handled. Open Global Routing from Home, select Config, Proxy or Direct, then return to confirm your selection. These three interface labels describe the configuration, proxy and direct modes. They are not server profiles and do not fill in connection details for you.
| Mode | How it works | When to use it | What to check |
|---|---|---|---|
| Config · Configuration | Applies policies according to the rules in the active configuration. | When different destinations need different policies, such as PROXY, DIRECT or REJECT. | The active configuration, rule order and final matching policy. |
| Proxy · Proxy | Routes traffic within the mode’s scope through a proxy. | To temporarily check whether a server can reach a specific destination. | The selected server, authentication details and actual access result. |
| Direct · Direct | Connects directly to destinations within the mode’s scope. | To check whether the issue also occurs on the current local network. | Local network, DNS resolution and destination reachability. |
How to verify a mode change
Note the original mode and selected server, then test the same destination in each mode. If Proxy works but Config does not, check the configuration and rules. If both fail, first verify the server details and basic network connection. If a destination works in Direct, that only confirms it was reachable under those direct-connection conditions; it does not verify your proxy settings.
Global Routing does not guarantee identical results for all system traffic. System network behavior, related configuration options and existing connections can all affect what you observe. After switching modes, make a new request to the destination rather than judging the new mode by an existing connection. Restore your usual mode when testing is complete.
Config → Rules
Rule types and policy actions
Rules match requests; policies determine what happens next. Check the order before reviewing individual syntax.
Rule-based routing applies when Global Routing is set to Config. Open Config, confirm which configuration is active, then review or edit its rules. Rules are checked from top to bottom in their configured order; the first match determines the policy. Put FINAL last to handle requests that did not match any preceding rule.
Choose a rule type based on the target
DOMAIN matches an exact domain. DOMAIN-SUFFIX matches a specified domain suffix and related subdomains. DOMAIN-KEYWORD matches a keyword in the domain and generally has a broader scope. IP-CIDR and IP-CIDR6 describe IPv4 and IPv6 address ranges, respectively. GEOIP checks address-location data. These rule types rely on different information, so domain and IP rules are not interchangeable.
USER-AGENT matches information of that type in a request, but not every connection provides it. Don’t treat it as a general-purpose way to identify apps. Before editing rules, check the syntax supported by the current app and whether that rule type applies to the traffic in question.
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT
DOMAIN-KEYWORD,ad,REJECT
FINAL,PROXYThis is an example for explaining rule order, not a recommendation to replace your current configuration. example.com is a sample domain.
PROXY, DIRECT and REJECT: what they mean
PROXY routes a matching request through a proxy policy, DIRECT connects to it directly, and REJECT blocks it. If a policy names an available policy group, check which option that group selects as well. Note the capitalization difference between the Proxy interface mode and the PROXY rule action. Config mode also does not mean every request must use a proxy.
A remote configuration update may overwrite local edits. Before making changes you want to keep, confirm where the current file came from and how it updates, and keep a recoverable copy. For step-by-step instructions, see the user guide.
Home · Subscribe · Add Server
Subscription and server management
This section assumes you already have subscription or server details. After importing, verify the selection and connection settings.
Subscriptions update server entries in one place, while manual entry is useful for managing a specific set of connection details. Get your subscription URL from your service provider and enter it under Subscribe. To add a server individually, open Add Server from Home, choose the protocol based on the details you have, and enter its settings. The exact menu location may vary in the current app interface.
Choose a protocol, then enter its connection details
Shadowrocket supports protocols including Shadowsocks, VMess, VLESS, Trojan, HTTP, SOCKS5, WireGuard and Hysteria2. Each protocol requires different authentication and transport details; copying an address and port alone may not be enough. Check the server address, port, password or other authentication details, then enter TLS, transport and related options as specified in your connection details.
To scan a code, use Scan QR Code. Before importing from the clipboard, make sure it contains the intended share data. QR codes and share links may include authentication details, so don’t post them publicly. Treat subscription URLs as credentials, too. The example https://example.com/sub?token=xxxx illustrates the format only; it is not valid connection information.
Handle updates, selection and deletion separately
Subscribe updates refresh entries using content from their source. This does not update the client or guarantee that the currently selected server still works. After an update, check entry names, changes in the list and the current selection. Then run Connectivity Test and verify access to a real website or service. Manual edits to subscription entries may be overwritten by a later update, so keep important details somewhere safe.
When managing multiple subscriptions, use clear notes to distinguish their purpose and source. Before deleting anything, confirm whether the action affects one server or an entire subscription. Removing entries from the list does not cancel a service with its provider or revoke remote credentials.
Settings → On Demand
On Demand connections
On Demand controls when a connection is triggered; Global Routing determines how requests are routed.
On Demand triggers connection behavior based on configured network conditions, helping reduce repeated manual steps when networks change. Open On Demand in Settings, review the available conditions, then configure them for your needs. For SSID conditions, enter the exact name of the Wi-Fi network you use and check whether the selected condition connects, ignores or performs another available action.
Verify a manual connection before adding conditions
First disable On Demand triggers so they don’t interfere with testing. Confirm that the selected server connects manually and that Global Routing behaves as expected, then add one clearly defined condition. After saving, test on networks where the condition matches and where it doesn’t, checking the connection status and actual access. Changing the server, rules and network conditions at the same time makes it difficult to identify the cause of a problem.
On Demand is not a scheduled task that starts at a fixed time, and it does not guarantee that all existing connections will survive a network change. System scheduling, network availability and VPN configuration status can all affect whether a trigger runs. If it doesn’t trigger, check the conditions and system permissions first. If the connection repeatedly comes back, check whether an On Demand condition is still active instead of repeatedly toggling the main switch.
When a connection starts and how requests are routed are separate settings. Even after On Demand triggers a connection, a DIRECT rule in Config still sends matching traffic directly. Before traveling or switching networks, keep a brief note of your conditions so you don’t forget an old SSID setting.
Data
Data usage statistics
See traffic recorded by the client; these figures are not a substitute for your provider’s billing records.
Data shows traffic statistics from the client’s perspective. Open Data and check the scope, time range and categories shown before interpreting upload, download or total figures. Values from different scopes cannot be compared by simply subtracting one from another. Before resetting statistics, confirm which records will be affected.
Use statistics to help troubleshoot, not as the sole basis for conclusions
First note the current figures, perform one specific access test, then check for changes. If there is upload activity but little or no download, the request may have been sent without receiving the expected response; use diagnostics and the destination’s status to investigate further. Background activity, other ongoing requests and connection retries can also affect the figures, so keep test conditions as simple as possible.
Client statistics may differ from a provider’s bill due to billing periods, protocol overhead and measurement methods. The total shown in Data is not your remaining service allowance and cannot tell you whether a subscription has expired. For service validity or usage limits, check the records for the service you already have.
An increase in traffic does not necessarily mean routing is wrong. First identify which kinds of requests caused the change, then check Global Routing and the matching rules. To preserve useful troubleshooting evidence, note the test time and steps taken. Before sharing records, redact servers, domains and other sensitive details.
Settings
DNS, tests, syncing and diagnostics
Change one variable at a time, save the original settings and retest the same destination.
DNS: first check what manages it
DNS resolves domain names to IP addresses. To troubleshoot it, check the DNS options available in Settings and the DNS section of the active Config file. First determine which layer controls DNS resolution, then change the relevant setting. Don’t change DNS in several places just because a webpage won’t load, and don’t confuse resolving a server address with resolving the destination website.
If a latency test passes but a webpage won’t load, check in order whether the domain resolves, which policy the rules ultimately select, and whether the actual request succeeds. The configured DNS resolution path may differ from the proxy request path, so a single test result cannot confirm that the entire access path is working. Keep the original configuration, make a change, retry the request, then compare the result with the original settings restored.
Test Method and Connectivity Test: keep test conditions consistent
Test Method selects an available testing method and is usually configured in the test-related Settings. Connectivity Test starts a connection test. Different methods measure different parts of the connection, so compare results on the same network, using the same method and at roughly the same time. A lower reading in one test does not mean every website will load faster.
If a test fails, first check the requirements of the selected method, then verify the server settings and network. Even after a test passes, visit the actual destination to confirm that DNS resolution, connection and content loading all complete successfully. If changing Test Method produces a noticeably different result, note the method used rather than comparing results from different conditions.
Today Widget: a quick access point
Today Widget provides quick viewing or controls within the capabilities allowed by the system. Check the related options in Settings, then see whether the corresponding item can be added in the system’s widget manager. Available options depend on the device’s system and what the current app supports; an older layout should not be assumed to appear on every device.
Widgets may refresh periodically rather than immediately. If the status doesn’t match what you expect after an action, return to Home to check the actual connection status, then verify that the system permits the relevant feature. A widget is not a standalone server configuration and does not replace the app’s VPN authorization.
iCloud sync: know the difference between syncing and backup
Check the iCloud options in Settings and confirm that the system allows Shadowrocket to use iCloud. Before enabling sync, check which data the option covers. Don’t assume that server entries, configuration files, selections and other settings are all synced without verifying. For first-time use, keep a local copy and check each item on another device.
Sync keeps supported data consistent across devices, but does not guarantee that every past change is preserved. Deletions or incorrect edits may also sync, so syncing is not a substitute for an independent backup. Synced data may contain subscription URLs or authentication details; protect your devices and iCloud account. Don’t publish your complete sync data while troubleshooting.
Diagnostics: investigate a failed request
Start with Diagnostics in Settings or the diagnostic option available in the current interface. Note the network type, Global Routing mode, active configuration and server, then reproduce the failed request once. Check in order: basic network, server address resolution, connection establishment, rule handling and access to the destination. This narrows down the cause more effectively than repeatedly changing every setting.
Diagnostic records may contain destination domains, server addresses and request details. Before sharing, remove subscription URLs, authentication fields and other private information; keep only the smallest excerpt needed to show the issue. When troubleshooting is complete, restore temporary settings and stop detailed logging you no longer need, so later activity isn’t mixed with old tests.