Official Manual · Features and Common Settings

Shadowrocket Features and Settings

Choose a Global Routing mode first, then check servers, rules, and DNS. The connection toggle, routing mode, and On Demand each serve a different purpose and should be checked separately.

Shadowrocket is a closed-source commercial app for Apple platforms, primarily used on iPhone and iPad, and available exclusively on the App Store. Refer to the App Store listing for system requirements and device compatibility. For app and purchase details, start with the official App Store purchase guide; first-time users can begin with the setup guide.

Routing

Global Routing: Config, Proxy, and Direct

Global Routing determines the overall routing mode for requests. Open Global Routing on Home and choose Config, Proxy, or Direct as needed. Config applies rules from the active configuration; Proxy routes traffic through the selected proxy; Direct uses a direct connection. Use Config for routing by domain or address, Proxy to briefly check whether the selected server is reachable, or Direct to compare with a direct connection.

Option What it does When to use it What to check
Config Uses rules in the active configuration to determine how requests are handled. Routes different destinations through PROXY, DIRECT, or REJECT. The active configuration, rule order, and final matching policy.
Proxy Routes traffic through a proxy, subject to app- and system-level exceptions. Temporarily troubleshoot server connectivity while reducing the effect of rule differences. The selected server, authentication details, and whether it can connect successfully.
Direct Uses a direct connection instead of routing ordinary requests through the selected proxy server. Check whether the same destination is reachable directly over the local network. The local network, destination service, and domain name resolution.

Note the original setting, change only Global Routing, then retry the same destination. If Proxy works but Config fails, check the rules and active configuration first. If both fail, check the server settings, DNS, and local network. This helps narrow down the cause; one test alone cannot confirm it.

Global Routing is not the connection toggle. Selecting Proxy does not mean a tunnel has been established, and selecting Direct does not disconnect a VPN connection in the system. Check the connection status on Home as well. When troubleshooting is complete, restore your preferred mode so a temporary setting does not become your permanent configuration.

Rules and Policies

Rule: Choose a Connection Path Based on Conditions

Rules match requests; policies determine how matched requests are handled. In Config, confirm which configuration is active, then review or edit its [Rule] section. When Global Routing is set to Config, rules are evaluated from top to bottom, and the policy on the first matching rule is applied. Put specific conditions first and the catch-all FINAL rule last to make the configuration easier to read and troubleshoot.

DOMAIN matches a specific domain; DOMAIN-SUFFIX matches a domain and its subdomains; DOMAIN-KEYWORD matches a keyword in a domain. IP-CIDR and IP-CIDR6 match address ranges, while GEOIP checks the destination IP's associated region. USER-AGENT relies on available request header information and should not be treated as a universal way to identify an app in every connection.

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
DOMAIN-KEYWORD,ads,REJECT
IP-CIDR,192.168.0.0/16,DIRECT
GEOIP,CN,DIRECT
FINAL,PROXY

The snippet above demonstrates syntax and rule order; it is not a complete configuration for every network. PROXY applies the proxy policy, with the actual route determined by the current selection and configuration; DIRECT connects to the destination directly; REJECT blocks the request. The keyword ads is also just an example: it matches a string and does not accurately represent a particular type of content.

Keep a copy of the original configuration before editing, and after saving, confirm that the edited file is still selected. Test with a new request and, when available, check the destination and matching rule in the connection log; existing connections may continue using their previous handling. For an explanation of configuration sections, policies, and priority, see the rules and configuration reference. Avoid adding many rules at once if you cannot explain what they do.

Connection Details

Subscribe and Add Server: Manage Existing Details

Server entries store connection details; subscriptions retrieve and update multiple entries. On Home, use Add Server to add your own server details, or select Subscribe under Type and enter your existing subscription URL. If the app offers options such as Scan QR Code, you can use them to import your own connection details. Before saving, check that you selected the right type: a subscription URL and a single server's shared details are different kinds of data.

When entering details manually, the protocol must match the server. Shadowsocks, VMess, VLESS, Trojan, WireGuard, Hysteria2, HTTP, and SOCKS5 each require different fields. Enter the address, port, authentication details, and transport settings according to your own information. For TLS, also check certificate validation and related domain settings. Do not swap fields just because their names look similar, or disable validation simply to get a connection through.

Updating a subscription fetches its contents again, so local entry names, counts, or settings may change. If you need to keep manually edited entries, check whether they are managed by the subscription and keep a backup if needed. Use clear names for entries with different purposes to make the selected item easier to identify on Home; the name itself does not affect routing.

After importing, select a server, run Connectivity Test, and then verify it with an actual request. A test response only confirms that the chosen test method received a response; it does not prove that authentication, domain resolution, and access to the destination are all working. Subscription URLs may contain access credentials, so do not include them in public screenshots, diagnostic files, or shared configurations. Before sharing troubleshooting details, redact sensitive parts of URLs and server authentication fields.

Connection Triggers

On Demand: Connect Based on Network Conditions

On Demand lets the system trigger a connection based on configured conditions; it does not choose a route for each request. Find the On Demand options in Settings and configure them using the Wi-Fi, cellular, or specified network conditions available in the app. The exact location and options depend on what appears on your device. Before enabling On Demand for the first time, make sure a manual connection works.

Start with a clear condition, such as enabling On Demand only for a particular type of network, then switch networks to check how it behaves. During testing, check the connection status on Home and in the system VPN settings: does it connect when the condition is met, and behave as expected when you leave that network? If you use a specific Wi-Fi condition, verify the network name so similarly named networks are not mistaken for the same one.

On Demand and Global Routing can work together: On Demand determines when to trigger a connection, while Global Routing determines how requests are handled once connected. If you disconnect manually while the trigger condition still applies, the system may reconnect. To pause connections, check On Demand as well instead of repeatedly toggling the connection.

Battery use with On Demand depends on how often the network changes, actual traffic, and reconnection behavior; the toggle alone does not tell the whole story. Check battery usage in system settings over a suitable period and for your usual usage. If connections keep restarting, check the network conditions and server stability before adjusting the trigger rules. Change one variable at a time.

Usage

Data: Check Traffic Statistics

Data shows traffic recorded by the app and can help you track usage trends or investigate unexpected increases. Open Data and check the current view's scope, time range, and distinction between uploads and downloads before reading the figures. Different views may cover different connections or totals, so use the labels shown in the app. A partial statistic should not be treated as the total traffic for the entire device.

To estimate the traffic generated by an activity, note the current figures, pause other obvious network activity, then perform the same activity once and compare the change. Background sync, media preloading, and system network activity may also occur, so a short-term difference may not come entirely from the page you just opened. Save any readings you need before changing the statistics scope or clearing records.

Data, system cellular usage statistics, and usage records from your own service may use different time periods and measurement methods. Transfer overhead, reporting scope, and refresh timing can all cause discrepancies. Data is useful for local observation, but it does not replace usage records from the service, and an increase in traffic alone does not prove that a particular rule matched. Check connection details and the applied policy to investigate rule matching.

Common Settings

Settings: DNS, Testing, Widgets, and Diagnostics

Settings covers several areas: DNS affects domain name resolution, Test Method determines how tests are run, Today Widget provides a widget entry point, iCloud syncs supported data, and Diagnostics provides troubleshooting information. Identify the issue first, then open the relevant setting. Exact names, locations, and availability depend on what appears in the app.

DNS: Check Where the Setting Comes From

DNS translates domain names into destination addresses. When checking DNS options in Settings, also review the [General] section of the active Config for settings such as dns-server. If both interface options and the configuration file affect how requests are handled, seeing a value in one field does not mean all requests use the same resolution path.

Note the original value before making a change, modify one setting at a time, then test the same domain. If the server responds but a webpage will not load, include DNS resolution in your troubleshooting; also check the matching route and the destination's status. Do not stack multiple DNS addresses from unknown sources, or assume the DNS server's location is the same as the request's final exit location.

Test Method: Know What Is Being Measured

Test Method determines how Connectivity Test runs. Choose a method currently available in Settings, then return to Home and test the selected server. To compare results, keep the test method, network, and test destination the same; otherwise, the numbers are not directly comparable.

Different methods may cover only connection setup or part of a test request; the reported value is not the time it takes to load a complete webpage. If a test responds but an app request fails, continue checking protocol authentication, TLS, DNS, and rules. If a test fails but actual requests work, check the test destination and method before deleting the server entry.

Today Widget: Check Widget Availability

Today Widget lets you configure related information or actions shown in a system widget. Check the widget settings available in the app, then add or adjust the widget in the corresponding area of the system. Its location, appearance, and available actions depend on system support; refer to what your device actually displays.

After configuring the widget, check the connection status on Home and confirm that the widget shows the same status. Widgets are useful for quick checks or supported actions, but return to the app for detailed server selection, configuration edits, and rule troubleshooting. When the device is locked, consider what information the system allows it to display.

iCloud: Check Both Devices Before Syncing

iCloud settings let the app sync supported data. Before using them, check that iCloud is enabled on the system, that Shadowrocket is allowed to use the relevant service, and which data types the app can sync. Refer to the in-app description for the sync scope; do not assume server entries, configurations, and statistics are all handled in the same way.

Before enabling iCloud on another device for the first time, back up anything you need to keep on both devices and identify which data is local and which is in iCloud. Avoid repeated actions until you understand how merging or overwriting works. A successful sync does not confirm that the selected server, Global Routing mode, or connection toggle is correct. After switching devices, check each one and test the connection again.

Diagnostics: Gather Clues for a Specific Failure

Diagnostics helps you investigate connection issues and review diagnostic information provided by the app. Open the relevant option in Settings, note the network, Global Routing mode, and active configuration when the issue occurs, then reproduce the failure once. Diagnostic information should correspond to that attempt; a large collection of old records can make the cause harder to pinpoint.

When reviewing the information, distinguish between domain resolution, server connectivity, authentication, and rule handling, then identify which stage first shows a problem. Before sharing diagnostic files, check for access domains, server addresses, subscription details, and authentication fields, and include only what is needed for troubleshooting. Diagnostic records provide clues; a single error message does not necessarily identify the cause.

How to Troubleshoot

Check Settings in a Consistent Order

Start with the smallest scenario that reproduces the issue, then restore your usual settings one at a time. If you change the server, configuration, DNS, and test method all at once, even a changed result will not show which setting made the difference. Note what happens after each change and keep the original values so you can restore them.

  1. Check the details. On Home, confirm that the server entry is based on your own valid information and that the protocol, address, port, and authentication fields are complete.
  2. Check the connection. Confirm that authorization for the system VPN configuration is complete and check the actual connection status. An enabled connection toggle does not mean the destination is reachable.
  3. Check the routing mode. In Global Routing, confirm whether Config, Proxy, or Direct is selected. If Config is selected, also check which configuration is active.
  4. Check the request. Send a new request to the same destination, then use the matching rule, DNS, and Diagnostics to identify where the failure occurs.
  5. Restore automation. Once the basic connection works, re-enable On Demand, widgets, and sync, then check the statistics scope in Data.

For a step-by-step first connection, read the Shadowrocket setup guide. To look up a keyword's syntax, see the configuration reference. For questions about purchases, importing, or connection behavior, visit Troubleshooting. Each page covers a different part of the process; you do not need to rewrite the entire configuration to change one setting.