Official Shadowrocket Manual

Shadowrocket Features and Settings

Understand settings by connection mode, rules, servers and automatic triggers. Decide which layer you need to change, then adjust the relevant option to make troubleshooting easier.

Global Routing: Choose a connection mode

What it does: Global Routing determines how requests are routed. Config mode follows Config, proxy mode uses Proxy, and direct mode uses Direct. This is separate from the connection toggle on Home: the toggle turns the connection on or off, while Global Routing determines how requests are handled when it is on.

Where to find it and how to set it: Go to Home, open Global Routing and choose a mode. For everyday routing by domain or destination address, select Config and make sure the intended configuration is selected on the Config screen. To temporarily check whether the selected server can reach a destination, switch to Proxy. To compare against your local network connection, temporarily use Direct.

What each mode does and what to check
Mode How it works When to use it Keep in mind
Config Handles requests according to the active configuration's rules and policies. Everyday rule-based routing with PROXY, DIRECT or REJECT. Check the active configuration, rule order and final match.
Proxy Routes requests covered by proxy handling through the selected server. Temporarily test server connectivity or rule out the effect of a routing rule. This does not guarantee that all system traffic goes through the server.
Direct Connects to the destination directly over the device's network. Compare network reachability to see whether the proxy route is causing the issue. This does not turn off the connection toggle or override system network settings.

What to watch for: After changing modes, make a fresh request to the destination and check the result. Browser caches, existing connections and background activity may retain their previous state, so one refresh is not enough to conclude that a rule failed. Restore the original mode once you finish troubleshooting. In particular, don't mistake a temporary switch to Proxy for continued routing through Config.

Rules: Match conditions and policies

What they are: A rule consists of a match type, match value and policy. For example, DOMAIN-SUFFIX,example.com,PROXY matches a domain suffix and applies the PROXY policy. The match type identifies the request; the policy determines how it is handled. Check them separately.

Where to find them and how to set them: Check the active configuration in Config and save a copy before editing. To route a domain, first determine whether you need to match one exact hostname or an entire domain suffix, then choose DOMAIN or DOMAIN-SUFFIX. More specific rules generally belong before broader ones. Put FINAL at the end of the rule list as the fallback policy for requests not matched earlier.

Common match conditions
TypeMatchesScope
DOMAINAn exact domain name.Use it to change routing for one specific hostname.
DOMAIN-SUFFIXA domain and its subdomains.Covers more than one exact domain name.
DOMAIN-KEYWORDA keyword in a domain name.May match similarly named domains with different purposes.
IP-CIDR / IP-CIDR6An IPv4 / IPv6 address range.Check the address range against the actual destination; the website domain alone may not be enough.
GEOIPGeographic information associated with an IP address.Results depend on the database used and the resolved address.
FINALRequests not matched by earlier rules.Sets the final action; it should not come before specific rules.

The snippets below illustrate rule order only. They are not a complete configuration and contain no usable server details. The example domain example.com does not represent an actual route.

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT
FINAL,PROXY

What to watch for: PROXY sends a request through the proxy policy, DIRECT connects directly, and REJECT blocks the request. If a destination becomes unreachable after selecting REJECT, that may be the expected result. A page can also request resources from multiple domains, so a rule for its main domain may not cover everything. Use connection records to identify the specific requests rather than continually broadening keyword matches.

Subscribe and Add Server: Manage connection details

What they are: A server entry stores the address, port, protocol and authentication details needed to connect. Subscribe manages a set of server details that can be updated. Updating a subscription and updating Config are separate actions: refreshing the server list does not update the rules file, and importing a configuration does not select the right server for you.

Where to find them and how to use them: On Home, use Add Server to enter your existing server details manually. Match each field to the actual protocol; don't reuse parameters from another protocol. To add your own subscription with Subscribe, paste the complete link, save it and check that the entry appears in the expected group. If you have a QR code or share details, use Scan QR Code or the relevant import option. After importing, verify the server type and connection details.

Shadowsocks, VMess, VLESS, Trojan, Hysteria2, WireGuard, HTTP and SOCKS5 use different fields. For TLS, transport settings and other options, follow the requirements of your existing server; changing its display name does not change the connection destination. If you're unsure about a field, keep the original details and verify each setting rather than guessing from its name.

What to watch for: Note which entry is selected before updating a subscription, then check that it is still there afterward. If multiple subscriptions contain entries with the same name, identify their source by group before deciding what to keep or delete; matching names alone do not prove they are duplicates. Connectivity Test is useful for an initial check, but a passing test does not guarantee access to every destination. Back up your data before deleting a group, and don't share authentication details from configurations or share links.

This site does not provide, sell or recommend servers or subscriptions. A one-time app purchase is not a server plan; app availability and the terms for using your own server are separate. See the subscription and server management guide for importing, updating and organizing your details.

On Demand: Trigger connections automatically

What it does: On Demand triggers connection behavior based on conditions such as the network. It controls when to connect, not which route a request takes. Once connected, requests are still handled according to the active Global Routing mode and configuration, so On Demand does not replace rule-based routing.

Where to find it and how to set it: Find the On Demand options in Settings. First decide what you want to happen—for example, use a different connection state on a particular Wi-Fi SSID or connect on Cellular—then create rules using the conditions available in the current interface. Read the interface's explanation for each Domain condition; it is not the same as a DOMAIN-SUFFIX rule in Config.

  1. Connect manually first and confirm that your existing server and Config work as expected.
  2. Add one trigger condition at a time, noting the network and expected action for each.
  3. Switch to that network, wait for the system to respond, check the connection status and make a test request.
  4. Once the behavior is as expected, add other conditions and check for overlap.

What to watch for: System scheduling, network changes and existing connections can affect when you see a result. If the connection comes back after you disconnect it manually, the On Demand condition may have become true again; the toggle may not be broken. To troubleshoot, temporarily turn off On Demand and test a manual connection. Once the basic connection works, restore conditions one at a time. See the On Demand setup guide for help with combining conditions.

Data: Check traffic and connection records

What it does: Data shows traffic recorded by the app, helping you understand uploads, downloads and connection activity. These figures reflect what the app can observe; they are not your mobile carrier bill or your server provider's billing records.

Where to find it and how to use it: Open Data and check the available statistics, time range and categories before noting the figures. To measure traffic from a specific action, record the current totals, pause unrelated background downloads, perform the action once and compare the change. If the app offers a reset option, save any data you need before using it.

What to watch for: The direction of traffic, the starting point for the totals and whether the connection passes through the app all affect how to interpret the figures. Avoid subtracting totals collected over different periods, such as before and after switching networks or servers. Check connection records to see which rules matched; a rise in total traffic alone does not prove that a domain used PROXY.

When describing an issue, include only what is needed: the time, network type, destination domain and selected policy. Logs and connection details may contain server addresses, request paths or authentication information. Review and redact sensitive data before sharing.

Settings: Know what each option affects

Settings includes options for DNS, testing, shortcuts, syncing and diagnostics, each with a different scope. Some behavior may also be defined by the active Config. To understand what is happening, check both the configuration and app settings rather than relying on one screen. The sections below cover common tasks; available options depend on the current app.

DNS: Check how domains are resolved

What it is and where to find it: DNS resolves domain names to addresses. Check DNS options in Settings and look in Config for entries such as dns-server. Different DNS results can send the same domain to different IP addresses, affecting rules that match by IP.

How to set it and what to watch for: Keep the current settings and note the affected domain first. Determine whether the problem is a DNS resolution failure or a connection failure before changing how DNS works. Change one setting at a time, then make a fresh request and compare. Don't replace an address just because it looks familiar, and don't assume every access problem is caused by DNS; an unavailable destination server, a rule that rejects the request or a local network issue can look similar.

Test Method: Keep test conditions consistent

What it is and where to find it: Test Method determines how connection tests are run and can be checked in Settings. It affects the process and meaning of Connectivity Test results; it does not fix server settings automatically or promise real-world connection speeds.

How to set it and what to watch for: When organizing your server list, choose a method suited to the check you want to perform, then test under the same network conditions. After changing Test Method, don't compare the old and new results as if they were collected the same way. If a test fails, try the actual destination too, to distinguish an unreachable test target from a server connection problem.

Today Widget: Add a quick access option

What it is and where to find it: Today Widget is a setting for system widget shortcuts. Find the option in Settings, then add the widget in the relevant area supported by your system. Its visibility and available actions depend on the current system and app.

How to set it and what to watch for: First confirm that a manual connection works in the app, then set up the shortcuts you want to see. After using the widget, check the actual connection status on Home rather than relying on a cached display. If you can't find the option, check how your system manages widgets; there's no need to delete your existing configuration.

iCloud Sync: Syncing is not a backup

What it is and where to find it: iCloud sync shares supported app data across devices that support the feature. Check the relevant option in Settings and your system's iCloud settings. Sync depends on your account, network and system status; it does not keep a separate copy of your configuration from every point in time.

How to set it and what to watch for: First confirm that the data you need is intact on the original device, then enable the relevant sync option. On the other device, check the actual entries and Config instead of relying on the sync toggle alone. Export a separate backup before deleting or reorganizing large amounts of data, since deletions may sync to other devices. If something is missing, check the account and sync scope before importing again to avoid duplicate entries.

Diagnostics: Gather clues for reproducible issues

What it is and where to find it: Diagnostics provides tools to help investigate network and connection problems. Find it in Settings. Interpret the results in context—network, Global Routing mode, server and destination all matter. A single result is rarely enough to identify the full cause.

How to use it and what to watch for: Record the steps that reproduce the issue, then run the checks relevant to it. Change one condition at a time and keep the before-and-after results. Remove subscription links, passwords and other credentials before reporting the issue. Don't enable unfamiliar options just to generate longer logs, and don't mistake a destination address in diagnostic output for a usable server.

Troubleshooting order: From manual connection to automatic triggers

If you can connect but a page won't load, or the connection comes back after you disconnect, check one layer at a time. This is usually more effective than changing servers, DNS and rules all at once. Keep a copy of a configuration that reproduces the issue so you have a clear baseline for each change.

  1. Check the basic network: Confirm that Wi-Fi or Cellular has a working connection and note the network where the issue occurs.
  2. Check the server: Verify the selected entry, protocol and parameters on Home. Don't confuse entries with similar display names.
  3. Check the mode: Review Global Routing. For rule-based routing, use Config and make sure the intended configuration is active.
  4. Check the route: Use connection records to verify the destination domain, match condition and policy. Then check DNS and rule order.
  5. Check automatic triggers: Once manual connections are stable, re-enable On Demand and review its conditions one by one.

For your first setup, follow the getting started guide to import details, choose a mode and test the connection. For subscription updates, duplicate entries or backups, see server management. This page explains what each feature does; you can also check the FAQ for specific questions.