Shadowrocket
Features and Common Settings
First, check how traffic is being handled, then adjust your configuration and connection conditions. This page explains common features on iPhone and iPad in terms of what they do, where to find them, how to set them up, and what to watch for. Available options and menu locations may vary; check the app for details. See the App Store listing for system requirements.
Global Routing：Config / Proxy / Direct
Global Routing determines how connections are handled overall. On Home, tap Global Routing and choose Config, Proxy, or Direct. This is neither a server protocol nor a connection toggle: after choosing a mode, check your server, configuration, and main connection switch. Use Config for everyday routing based on domains or addresses. You can temporarily switch to either of the other modes for troubleshooting, then restore your original setting.
| Option | How it handles traffic | When to use it | What to check first |
|---|---|---|---|
Config mode |
Handles traffic according to the rules and policies in the active configuration. | Everyday routing; send requests through a proxy or connect directly as needed. | Active configuration, rule order, policy targets, and the final rule. |
Proxy mode |
Routes traffic handled by the client through a proxy instead of applying everyday rules. | Temporarily check whether the selected server can handle a request to a target. | Whether the selected server is available, and whether its authentication and transport settings are correct. |
Direct mode |
Connects traffic handled by the client directly. | Check whether the local network can reach the same target directly. | Local network, DNS resolution, and reachability of the target service. |
Before testing, note the current mode. Use the same network and target for each test, and avoid changing multiple settings at once. If Proxy works but Config does not, check whether a rule matches and whether its policy points to the right server. If Direct works but Proxy fails, check the server details and connection logs. These results can narrow down the cause, but no single test is conclusive.
Direct does not turn off the system VPN configuration, and Proxy does not guarantee that all device traffic will use a proxy. Assess mode tests alongside actual request records. After testing, switch back to Config and confirm the active configuration so a temporary troubleshooting mode isn't left in place for everyday use.
Rules: Match Conditions and Actions
Traffic-routing rules separate which requests match from how those requests are handled. Open Config, confirm which configuration is active, then open its editor to review the rules. Rules are generally evaluated in order, so put specific conditions before broader ones. When Global Routing is set to Config, the active configuration's rules are what determine everyday routing.
Choose a rule type, then check its policy
DOMAIN matches an exact domain, DOMAIN-SUFFIX matches a domain and its subdomains, and DOMAIN-KEYWORD matches a keyword in the domain. IP-CIDR and IP-CIDR6 specify address ranges, while GEOIP uses geographic IP data. Domain-based and address-based rules rely on different conditions, and DNS results can affect address-based matches. Don't infer the match result from the rule name alone.
The policy at the end of a rule specifies how to handle a request. DIRECT means connect directly, and REJECT means reject the request. PROXY should point to an available proxy policy or policy group in the active configuration. If the group has its own selection, check which option is selected. A policy named PROXY alone does not provide a working server connection.
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECTThis example sends example.com and its subdomains through PROXY, while FINAL sends requests that didn't match earlier rules to DIRECT. example.com is a documentation domain; this example is not a complete configuration for every network. FINAL should be the last rule, not a rule placed before conditions that still need to be checked.
Verify changes with a real request
Before editing, save a restorable copy of the configuration. Change one condition or policy at a time. After saving, make sure you edited the active configuration, then send a new request to the target and check the matching rule and policy in the available connection records. Existing connections may keep using their previous handling, so start a new connection to compare results. For rule types such as USER-AGENT, check whether the condition applies to the actual request; don't treat it as a general way to identify apps.
- Specific rules first
- Policy name is valid
- FINAL goes last
Subscribe and Add Server
A server entry stores the address, port, authentication, and protocol settings needed to connect. Subscribe retrieves a group of server details from a subscription URL you already have. You can use both, but they have different sources and are managed differently. On Home, tap Add Server to create an entry and choose the protocol specified in your connection details. To import a subscription, choose Subscribe and enter your existing subscription URL. Don't enter a subscription URL in a single server's address field.
Add a server manually: match each field
Shadowsocks, VMess, VLESS, Trojan, HTTP, SOCKS5, WireGuard, and Hysteria2 use different authentication and transport fields. Fill them in using your existing connection details; don't guess based on the protocol name. Check the server address and port, password or UUID, and any required TLS, transport type, Host, or SNI values. Only fill in options shown in the app and required by your connection details.
After using Scan QR Code or importing a link, open the entry and check the parsed details. Successfully scanning a QR code only means its contents were recognized; it doesn't mean the server is reachable. Remarks help identify entries and aren't used for authentication. Name entries by purpose, but don't put passwords or full subscription credentials in a remark.
Subscription updates: manage the source and local changes separately
After adding Subscribe, update it and check that server entries appear, then select the server you want to use. If the update fails, first check that the URL is complete, the credentials are valid, and the current network can retrieve the subscription. A successful update only means the content was retrieved and parsed; you still need to test the connection.
Entries in a subscription may change when it updates, and new content may overwrite local edits. Before deleting a subscription, check which entries depend on it and whether you have a backup configuration. After an update, recheck the selected server and policy groups. A token in a subscription URL is an access credential; redact it when sharing troubleshooting details. Examples in this manual are not valid connection details.
On Demand: Connect Based on Conditions
On Demand uses system-supported rules to trigger a connection when configured conditions are met. It serves a different purpose from Global Routing: On Demand controls when to connect, while Global Routing controls how traffic is handled during a connection. In Settings, look for On Demand options and follow the conditions and switches shown in the app. Before changing them, complete a manual connection to confirm that the server and configuration work.
First decide which network conditions should trigger a connection, then enable the relevant options. If the app offers network type or Wi-Fi conditions, check what each option includes, excludes, or does when disconnected. Don't assume from an option's name that it connects automatically on every network. After saving, check the connection status in environments that do and don't meet the conditions, then verify with an actual request.
On Demand does not guarantee a continuous connection. System state, network changes, and server reachability can all affect the result; a trigger cannot fix an incorrect password or unavailable server. If the connection repeatedly drops and reconnects, first check whether the On Demand conditions are still met, then check the main connection switch. Avoid toggling it repeatedly while leaving the original trigger conditions in place.
To troubleshoot connection issues, you can temporarily turn off On Demand and run a manual comparison test on the same network. Restore the conditions you need once you identify the cause. In everyday use, also check for other enabled VPN configurations and compare the connection shown by the system with the status in Shadowrocket.
Data: Uploads, Downloads, and Traffic by Group
Data lets you review traffic recorded by the client. Open Data and check the current reporting scope and groups before reading the upload and download figures: uploads are data sent from the device, and downloads are data received. Cumulative totals and current rates are different metrics. Before comparing readings, check the units, time range, and whether the statistics have been reset.
If the current view groups traffic by server or by app, the server view can help identify which server handled traffic, while the app view can show its distribution by source. App identification and reporting scope have limitations, and a group name alone doesn't prove that a rule matched. To verify routing, also check request records, the active configuration, and the selected policy.
Compare readings with a repeatable test
First note the current figures, then perform a specific action, such as reloading the same page, and check the changes in uploads and downloads. Background sync, media preloading, and system traffic can also use data; repeated visits to cached content may show little change. Keep the network and server the same during testing so network changes and ordinary background traffic don't skew the comparison.
Client readings should not be treated as a service provider's bill or as a measure of all device traffic. Connection coverage, reporting periods, protocol overhead, and provider billing methods may differ. To compare figures, first align the time range and units, then check how your existing service provider measures usage instead of expecting the numbers on both screens to match exactly.
If you need to reset the statistics, save any readings needed for troubleshooting first, then use the reset option shown in the current interface. Resetting statistics does not update a subscription, switch servers, or fix a configuration. When documenting an issue, note the readings before and after the reset and what you did to test; this is more useful than a cumulative usage screenshot alone.
Settings: DNS, Tests, Widgets, and Sync
Settings brings together connection options and diagnostic tools; some parameters may also be defined in the active Config. Before changing anything, note the original value and check whether the setting is global or belongs to the current configuration. This helps prevent conflicting changes in two places. Menu locations may vary; widget and sync availability also depends on device and system support.
DNS: Coordinate Resolution and Configuration
DNS translates domain names into addresses used to connect. Check DNS-related options in Settings and the active Config to determine which one controls resolution, then change the relevant setting. If an existing configuration includes DNS servers or domain-specific rules, understand what they do first. Don't change every DNS option just because one domain won't load.
After changing a setting, test domain resolution and the target connection separately. Successful resolution means an address was returned, not that the connection will work; address-based rules may also depend on the result. If problems arise, restore the original value for comparison, then check the address and policy in the request records. When sharing diagnostic details, include only the domain and error information needed, and remove personal browsing history.
Test Method and Connectivity Test
Test Method lets you choose how to test a connection. Find the relevant option in Settings, choose a method offered by the current interface, then return to the server list and run Connectivity Test. Different methods measure different stages. A result may reflect connection setup or the time taken to request a specific target, not actual download speed.
When comparing servers, keep the test method, target, and network the same. A failed test may mean the target was unreachable or the network briefly fluctuated; it doesn't mean all requests will fail. After selecting an entry, also test a target you actually need to access to verify that authentication, transport, and routing work together.
Today Widget: System Widget Access
Today Widget provides a quick way to view or control the app from a system widget. Check the relevant option in Settings, then use the widget setup process supported by your device to add the app's widget to the available area. Widget formats and compatibility depend on the current system and app; don't assume similarly named system widgets offer the same features.
Widgets can reduce the need to reopen the app, but they don't replace initial setup or authorization. After changing a server or configuration, return to the app to confirm the current selection. If a widget's reading or status hasn't refreshed, rely on the status in the app and a connection test.
iCloud: Requirements for Syncing Across Devices
iCloud settings control syncing for content supported by the app. Find the sync option in Settings and check that Shadowrocket is allowed to use iCloud in the system settings. Make sure your data is correct on the current device before enabling sync. The other device must also meet the relevant account, system permission, and network requirements.
The app lists what can be synced; don't assume that all passwords, statistics, logs, or system VPN authorization will transfer. Keep a restorable copy of important configurations before syncing, then check your servers, configurations, and current selection on each device. iCloud sync and restoring an App Store purchase are separate processes; synced data does not replace your purchase record.
Diagnostics: Identify Where a Connection Fails
Diagnostics lets you view or collect diagnostic information. Find the relevant option in Settings and follow the instructions shown. Before reproducing an issue, note the network, Global Routing mode, selected server, and steps you took. This makes it possible to match log timestamps to what actually happened.
When reviewing results, distinguish between subscription retrieval, DNS resolution, server connection, authentication, and the request to the target. A single error may not reveal the root cause; use surrounding records for context. Before sharing diagnostics, redact subscription tokens, passwords, UUIDs, personal addresses, and unnecessary browsing history. Include only the information needed to reproduce the issue.
From Connection Details to a Verified Request
Features work together, but troubleshooting is easier when you check one layer at a time. Verify the connection details first, then the connection, and finally rules and auxiliary settings. Change only one thing at a time so you can tell what affected the result. This sequence is for users who already have subscription or server details; you don't need to enable every feature first.
- Check the source. Confirm the Subscribe update, or review the protocol, address, port, and authentication fields in Add Server. Note which server is selected.
- Check the configuration. In Config, confirm which configuration is active. In Config mode, check the Rules order, policy group selection, and FINAL.
- Connect manually. Check system authorization, turn on the connection, and make an actual request. If needed, temporarily compare Proxy and Direct, then restore the original mode.
- Check DNS and logs. Change DNS or test settings only when the symptoms point to them. Use Diagnostics to identify which stage is failing.
- Enable convenience features afterward. Once the connection is stable, set up On Demand, Today Widget, and iCloud, then use Data to record traffic changes for the same action.
To start with your purchase and initial authorization, read the download guide. If you already have connection details but haven't connected yet, read the setup guide. If rule keywords are unfamiliar, start with the glossary, then return to check the conditions in your configuration.