Shadowrocket Official Guide

Shadowrocket
Proxy Modes and Settings

First choose how Global Routing should handle connections, then adjust rules, DNS, and On Demand. This page explains what each feature does, where to find it, how to configure it, and what to watch for.

For users who already have a subscription or server details. The steps below refer to the iPhone / iPad interface; layouts and available options may differ on other platforms.

Global Routing

How modes affect connection routing

Illustration of the processing logic, not an app screenshot.

Config
Active config → rules checked in order → matching policy
Proxy
Connections handled by the app → current proxy policy
Direct
Connections handled by the app → connect directly

Changing modes does not replace server details or fix an expired subscription.

Config / Proxy / Direct

Global Routing: Config, Proxy, and Direct

Global Routing determines how connections are handled; it is not a server list. Find Global Routing on Home, then choose Config, Proxy, or Direct. In this guide, “configuration,” “proxy,” and “direct” refer to those exact interface labels. If a server is selected but the mode is Direct, switching servers usually will not change the connection route. With Config selected, the server name alone does not tell you whether a particular site is routed through a proxy.

Interface optionHow it worksWhen to use itCheck before use
Config (configuration)Handles connections according to the rules and policies in the active config.For everyday use when you have rules ready and need to route different destinations differently.Check which config is active and whether its policies can find the required servers.
ProxyRoutes connections handled by the app through the current proxy policy.For temporarily checking server connectivity or comparing rule-matching behavior.Make sure the current server is valid and all protocol parameters are set.
DirectConnects destinations directly for connections handled by the app.To check whether the local network can reach a destination directly and establish a troubleshooting baseline.Check whether the destination is reachable directly on the current network.

Keep everyday use separate from temporary tests

If you have a verified config, Config is usually the right starting point. If a site will not load, note the current mode, then temporarily switch to Proxy and test the same destination. If it works in Proxy but not Config, focus on rule matching and policy references. If both modes fail, check the server parameters, local network, and DNS rather than repeatedly changing rules. Restore the original mode after testing.

DOMAIN-SUFFIX

Routing: Match Conditions and Policies

Rules specify which policy handles a connection. In Config, check which config is active, then open it for editing and review its rules. Rules are the primary basis for routing decisions when Global Routing is set to Config. Rules are generally checked in config order, so put specific matches before broader ones and fallback rules last. Save a copy of the original config before adding rules.

Understand match conditions before checking policy names

DOMAIN matches an exact domain; DOMAIN-SUFFIX matches a domain and its subdomains; DOMAIN-KEYWORD matches a keyword in the domain. IP-CIDR and IP-CIDR6 apply to IPv4 and IPv6 address ranges, respectively. GEOIP matches based on IP geolocation data. USER-AGENT depends on the request information available, so it should not be treated as a universal way to identify app connections.

The policy at the end of a rule determines what happens when it matches. DIRECT connects directly, REJECT blocks the connection, and PROXY routes it through a proxy policy. A config may also refer to custom policy group names. Custom names must match groups defined in the config; example names are not automatically available policies.

# Rule syntax example; example.com is for illustration only
DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
FINAL,PROXY

This example checks example.com and its subdomains first, then the GEOIP condition, and finally sends remaining connections to FINAL. It is not a complete config for every network. DNS results, rule order, and policy availability all affect the route. After making a change, start a new connection to the same destination and check the connection logs; the Home switch being on is not enough to confirm the result.

To block a destination, start with a narrow match. A broad DOMAIN-KEYWORD or IP range can also affect sign-ins, images, and API requests. For a single issue, change one rule at a time. Existing connections may continue using their previous route, so reopen the destination app if needed to compare results. For more on the modes, see Global Routing: Config, Proxy, and Direct explained.

Subscribe

Subscriptions and Servers: Sources vs. Configs

Subscriptions maintain server lists; Config determines how connections are handled. They are not the same thing. View servers and subscription groups on Home. To add details you already have, open Add Server and choose the relevant protocol or Subscribe. You can import a QR code with Scan QR Code, but first make sure it comes from a source you trust and already use.

Adding and updating a Subscribe entry

Enter your existing subscription URL in the Subscribe field, add a recognizable name, and save. Then update the subscription to retrieve its server list. Importing does not connect you automatically: select a server on Home, check Global Routing, and turn on the connection switch. If the list is empty after an update, check that the URL is complete and still valid and that the current network can reach it. A subscription URL is not a server address.

Updating a subscription may replace entries created by that subscription. Before temporarily changing parameters, note the original values or keep a separate copy so your changes are not lost on the next update. Before deleting anything, confirm whether the action applies to one server or the whole subscription group. If unsure, keep the original entry and label the test item with a note.

Checking manual Add Server details

When adding a server manually, choose the protocol specified in the server details, such as Shadowsocks, VMess, VLESS, Trojan, WireGuard, Hysteria2, or another supported protocol. The server address, port, authentication details, and TLS and transport fields must all match. Similar protocol names do not mean their fields are interchangeable. Do not disable certificate verification just to clear an error. Save the entry and test it on its own before changing rules.

On Demand

On Demand: Connect Automatically Based on Network Conditions

On Demand controls when the app attempts to connect; it does not replace Global Routing rules. Look for On Demand in Settings. If your interface lists it separately, open it from there. First connect manually and confirm the server and config work, then enable only the Wi-Fi or Cellular conditions you need. Available conditions depend on the platform and the options shown in the app.

Start by defining the use case, such as different connection behavior on a specific Wi-Fi network, then check whether any conditions overlap. If you use Wi-Fi names in conditions, verify spelling and spaces and account for networks with the same name. Avoid broad, conflicting conditions: when switching from Wi-Fi to Cellular, it can be difficult to tell which one triggered the connection.

To pause automatic connections, check whether On Demand is enabled rather than only turning off the Home switch. If its conditions are still met, the system may attempt to reconnect. If the app keeps reconnecting, note the conditions, temporarily disable On Demand, and test a manual connection for stability before restoring conditions one at a time. On Demand does not guarantee that existing connections will survive a network change; an app may need to make a new request.

Data

Data: Review Traffic and Test Changes

Data shows traffic information the app can record; it is not a carrier bill. Open Data and check the time range, direction, and category labels shown on the page before reviewing upload and download records. If connection details are available in your version, compare the relevant time with the destination you accessed. Do not assume a rule worked based only on a cumulative total.

For a single test, note the current statistics and time, pause other ongoing transfers, then access a known destination and watch for changes. If you use the page’s reset option, save any records you need first and confirm what the reset covers. Totals, current sessions, and figures for a reporting period mean different things; compare them only over the same time range.

A difference between Data and the system’s cellular usage does not necessarily indicate a problem. The time ranges, protocol overhead, background connections, and traffic visible to the app may differ. To check whether traffic is proxied, review Global Routing, rule matches, and connection records. To check a plan’s remaining allowance, refer to the account records for the service you already use; Data is not a billing source.

Settings

Settings: DNS, Tests, and Shortcuts

Settings controls general app behavior, though some related options may also be specified in the active Config. Before changing a setting, check the config to avoid overlooking its effects. Option locations may differ across platforms, system permissions, and versions. If you cannot find an option, follow the interface you have; there is no need to reimport a config just to match this guide.

DNS: Check Name Resolution and Routing Separately

DNS resolves domain names to IP addresses. First review the DNS options in Settings, then check whether the Config also includes DNS settings. If a site will not load but Connectivity Test returns a result, distinguish between server reachability and whether the destination domain resolves correctly. Keep a copy of the original settings and change one DNS-related option at a time, testing the same domain after each change.

A reachable DNS resolver does not guarantee that a destination is reachable, and changing DNS will not fix an incorrect server password or transport settings. Enter addresses and choose resolution methods as the interface requires; do not put a URL with a path into a field that accepts only a server address. If only some domains fail, continue checking rules and IPv4 and IPv6 routes. For step-by-step help, see Troubleshooting DNS resolution failures.

Test Method: Keep Connectivity Test Comparisons Consistent

Test Method determines how Connectivity Test runs. Find Test Method in Settings, confirm the selected method, and check whether the interface lets you configure a test target before testing. When comparing servers, use the same local network, method, and target, and test around the same time. Otherwise, you may be comparing results from different conditions.

A test result applies only to that test. Getting a response does not mean every site, protocol, or sustained transfer will work; one timeout is not enough to conclude that a server is permanently unavailable. If the test and real-world access do not agree, reproduce the issue with the actual destination, then check DNS and connection records.

Today Widget: Shortcuts and System Permissions

Today Widget provides quick views or actions where supported by the system. Check the related option in Settings, then add the widget through the system’s widget management screen. Whether it appears and which actions it supports depend on the system version and the widget types available in the app. If it does not appear, first make sure you have opened the app and check whether the system allows the widget to run.

Shortcuts and the main app share the same connection state. After using a shortcut, return to Home and check the server, mode, and connection switch instead of relying on a brief widget display. For automatic connection issues, check On Demand.

iCloud: Check What Syncs Before Switching Devices

If your version supports iCloud sync, find the option in Settings and confirm that the system is signed in to the intended account and allows Shadowrocket to use iCloud. Before enabling sync, review the listed scope. Do not assume that server details, configs, statistics, and connection state will all sync.

When moving to another device, wait for sync to finish, then review each config on the new device. Avoid editing the same content on both devices at once. Sync is not a substitute for a separate backup, and it cannot make server credentials work if they have expired. Treat content containing subscription URLs or authentication details as sensitive data, and clear it using the system and app features before handing off a device.

Diagnostics

Diagnostics: Troubleshoot by Layer, Not by Changing Settings at Random

Diagnostics helps collect troubleshooting clues; it cannot automatically confirm that a server or rule is correct. Find Diagnostics in Settings and run the checks available in your interface. Before reproducing the issue, note the local network, selected server, Global Routing mode, and active config. If you temporarily enable logging, restore the original logging level after testing.

  1. Check the local network first. Confirm that the device can reach a known working destination. If needed, compare Wi-Fi with Cellular, without changing client settings at the same time.
  2. Next, check the server. Run Connectivity Test on the same entry and verify the protocol, address, port, and authentication details. If several entries fail at once, check for a shared network issue first.
  3. Then compare modes. Record the difference when accessing the same destination with Config and Proxy. If only Config fails, focus on rule order, policy references, and DNS settings.
  4. Finally, review the records. Use the time of the issue to locate the destination domain, error, and policy actually applied. After changing one setting, start a new connection and check whether the result is consistently reproducible.

Diagnostic data may contain visited domains, server addresses, subscription URLs, and authentication details. Before saving or sharing troubleshooting data, remove complete subscription URLs, passwords, and personally identifying information. Do not publicly post a full config or complete logs. Once troubleshooting is complete, keep a record of the final changes, remove temporary test entries, and restore your usual Global Routing mode and On Demand conditions.

For step-by-step setup starting with import, see Getting Started. If you have already identified a specific error, visit Troubleshooting. For iPhone / iPad, see the App Store page for system requirements.