Official Manual · Features & Settings

Shadowrocket Settings Guide

Start in Home by checking Global Routing, then adjust rules, refresh an existing subscription or enable On Demand as needed. The interface paths in this guide use iPhone / iPad as examples; locations on desktop and Android may vary by app interface.

01 / Global Routing

Choosing Config, Proxy or Direct

Open Global Routing in Home and choose Config, Proxy or Direct for the task at hand. This setting controls how requests are handled when the connection is on; it does not establish a connection or modify the configuration file.

How the three Global Routing modes work, when to use them and what to check
Mode How requests are handled When to use it What to check before and after switching
Config Routes requests according to the rules and policies in the active configuration. For everyday use when different requests need different policies. Confirm which configuration is active, then check the relevant rules and FINAL.
Proxy Sends requests handled by the client through the selected proxy server, without choosing a route rule by rule as Config does. To temporarily check whether the current server can handle a specific request. Check which server is selected in Home; switch back to your usual mode when testing is done.
Direct Sends requests handled by the client without forwarding them through a proxy server. To check whether the proxy route behaves differently from a direct connection on the current network. Direct does not turn off the connection switch in Home. To compare with traffic that is not handled by the client, turn the connection off before testing.

For a meaningful comparison, use the same network, destination and server, and send a fresh request after each mode change. If Proxy works but Config does not, check which rule matches and where its policy points. If Direct fails too, turn off the connection and try again to distinguish a network issue from a client setting. Existing connections may continue using the previous route, so an already-open page alone cannot confirm the result of a mode change.

02 / Rule

Rule Types, Match Order & Policies

Each rule consists of a match condition and the policy applied when it matches. Open Config, confirm which configuration is active, then check its [Rule] section. Rules are evaluated in order; the first match determines the policy for that request. The rule list controls routing only when Global Routing in Home is set to Config. Keep a copy of the original configuration before making changes so you can compare or restore it.

  • DOMAIN matches an exact hostname; DOMAIN-SUFFIX covers a specified domain and its subdomains; DOMAIN-KEYWORD matches a keyword in the domain name, and shorter keywords are more likely to match unintended domains. For domain rules, enter only the domain—not a scheme, path or query string.
  • IP-CIDR and IP-CIDR6 match IPv4 and IPv6 ranges, respectively; GEOIP matches based on IP geolocation data. These rules evaluate IP addresses, not domain suffixes. Results may change if the destination IP changes or a different address family is used.
  • USER-AGENT relies on a recognizable User-Agent in the request, so it is not suitable for matching all app traffic. FINAL handles requests that did not match any earlier rule and should be placed at the end of the rule list.
[Rule]
DOMAIN,status.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT

This example sends status.example.com directly with DIRECT, then routes other matching requests under the same domain through PROXY. If you swap the first two lines, the broader suffix rule matches first and the exception no longer applies. PROXY uses the proxy route, DIRECT bypasses the proxy server, and REJECT blocks matching requests. Before using REJECT, narrow the target scope to avoid blocking login or resource requests that rely on the same domain.

After saving, test the address that should be handled separately, then another address on the same domain that should remain unaffected, and finally a destination that should fall through to FINAL. For field formats and more examples, see the configuration fields guide.

03 / Server

Importing Existing Subscriptions & Managing Servers

A subscription updates a group of server entries from a source; if you have connection details for just one server, you can add it manually. Both methods require subscription or server details you already have. Subscription URLs may contain access credentials, so protect them like passwords and never include them in public screenshots, logs or shared documents.

  1. Open Add Server in Home. If you already have a subscription URL, choose Subscribe, enter the full URL provided by your service provider, and save. To refresh it, find the subscription’s update option in Home, then confirm that its entries have loaded. Do not enter a subscription URL in the address field for an individual server.
  2. If you already have the details for a single server, choose the protocol listed in your information—such as Shadowsocks, VMess or Trojan—in Add Server, then enter the host, port and authentication details in the corresponding fields. If the details are provided as a QR code, use Scan QR Code to import them; still verify the protocol and destination address before saving.
  3. Return to Home, select the entry you want in the SERVER list, then run Connectivity Test. After refreshing a subscription, check the selected entry again. An entry with the same name may have a different address or settings; a matching name does not prove it is still the same server.

Check subscription refresh and server connectivity separately. A successful refresh only means the client retrieved the list. If an entry still cannot connect, verify the protocol, address, port and authentication details provided by your service provider. If the refresh itself fails, first check that the subscription URL is complete and that the current network can reach it. For the first connection after importing, see Quick Start.

04 / On Demand

On Demand & Network Changes

On Demand lets the system start a connection when its configured conditions are met. It is useful when you want a connection to start automatically after a network change. It controls when to connect, not how requests are routed; routing is still determined by Global Routing and the active configuration.

Find On Demand in Settings. First, manually verify the current server and routing mode in Home. Then enable On Demand and narrow its scope using the available conditions, such as Wi-Fi or cellular networks. After saving, send requests on networks where the connection should and should not be triggered, then check the connection status in Home. Allow time for the system to reconnect after switching networks; a failure immediately after a switch does not necessarily mean the rules are not working.

If the connection starts again after you disconnect manually, check whether the trigger conditions are still met. To temporarily compare behavior while disconnected, turn off On Demand first and restore it after testing. When investigating battery drain, do not rely on the toggle alone: compare system battery records across similar networks and usage periods to see whether repeated reconnections are occurring.

05 / Data

Traffic Statistics: Scope & Readings

Data shows traffic recorded by Shadowrocket; it may differ from carrier billing or a service provider’s usage figures. In Data, first check the displayed measurement period and units, then review sent and received traffic. For a single test, there is no need to clear existing records: note the starting reading, perform one operation, then subtract the starting reading from the result.

If usage increases faster than expected, repeat the observation on the same network and separate background activity—such as video streaming, cloud sync or large downloads—from the test. If the reading does not change, first confirm that the connection is established, then check whether the request is passing through the client. A page served from the local cache may not generate new network traffic. Data shows how much traffic was recorded, but a change in usage alone cannot tell you which rule matched a domain or estimate the remaining allowance on a service plan.

06 / Settings

DNS, Testing, Widgets, Sync & Diagnostics

Record the original settings and change only one item relevant to the issue. After each change, retest the same destination. Changing DNS, servers and test methods at the same time makes it difficult to identify the cause.

DNS: Separate Resolution from Routing

DNS resolves domain names to addresses. When troubleshooting, first check Global Routing in Home, then open Config and review the active configuration’s [General] section, including its dns-server setting. If needed, adjust it to suit the current network, save, reconnect and test both a known-working domain and the domain that is failing. Internal domains on work or home networks may rely on that network’s resolver; if you switch to a public resolver, resolving external domains successfully does not mean internal domains will work too. For more fields, see the General configuration guide.

Test Method: Compare Under the Same Conditions

Check Test Method in Settings and choose from the options shown in the app, then return to Home and run Connectivity Test. Checking whether a connection can be established is not the same as verifying a complete request. Even a successful test does not prove that a particular service domain is accessible. When comparing servers, keep the network, method and any configurable test destination the same. If a test times out once, repeat it unchanged before switching servers or checking settings.

Today Widget: Check Status from a System Widget

Today Widget is a system widget entry point, not a standalone connection configuration. If Today Widget appears in Settings, first check the available options, then add the Shadowrocket widget using a method supported by the current system. If the widget is missing from the device’s widget list or its status does not refresh promptly, check the connection and selected server in Home. Routing modes, subscriptions and configuration files are still managed in the app.

iCloud: Check What Will Sync

To sync data between your own iPhone and iPad, first make sure both devices are signed in to the same Apple Account and that Shadowrocket is allowed to use iCloud in system settings. Then check the iCloud-related switches in the app’s Settings. Keep important configurations before enabling sync; change one item on one device first, then check whether it updates on the other. Sync is not a standalone backup, and seeing a synced entry does not mean a connection has been established. Confirm system permissions and connection status on each device separately.

Diagnostics: Capture Reproducible Issues

Diagnostics collects information to help investigate the current connection. Before opening Diagnostics in Settings, note when the issue occurred, the current network, the Global Routing mode and whether it affects only a particular destination. Reproduce the issue once using the same steps, then compare the diagnostic results with DNS, server test or rule-check results. Before sharing details, remove the full subscription URL, passwords and authentication information; include only the environment and symptoms needed to reproduce the issue. If you are unsure what to try next, see connection troubleshooting.