Official Guide · Settings Reference

Shadowrocket Settings
Check routing, rules, and connections

First check Global Routing and the active configuration before changing DNS or automatic connection settings. Change one item at a time and retest the same destination to distinguish rule, server, and local network issues.

This guide follows the iPhone / iPad interface. Layouts and available options may differ on other platforms; refer to the interface on your device. Shadowrocket is available for iPhone / iPad, Mac, Windows, Android, and Linux. Mac downloads are available for Apple Silicon and Intel.

The iPhone / iPad version is a one-time $2.99 purchase on the App Store. The Mac / Windows / Android / Linux versions are free. See the download page for the app and platform-specific installation guidance. Desktop and Android installers are available from this site at /dl/shadowrocket/.

01 · Routing

Global Routing: Config, Proxy, and Direct

The three modes determine how traffic is routed. They do not replace server settings or fix an unavailable service.

Open Global Routing from Home to choose Config, Proxy, or Direct. For everyday use, Config is usually the starting point: rules in the active configuration determine where requests go. After choosing a mode, check the selected server and connection toggle on Home. The mode name alone does not mean a connection is active.

ModeWhat it doesWhen to use itWhat to check
Config · ConfigurationRoutes requests according to the rules and policies in the active configuration.Everyday use that requires different routes for domains, addresses, and unmatched traffic.Check that the correct file is selected in Config and that the rule order is as expected.
Proxy · ProxyRoutes traffic through a proxy rather than applying the usual per-rule routing in Config.Temporarily check whether the server route is available.Check that the selected server is valid; local network resources may be affected.
Direct · DirectRoutes traffic directly.Temporarily compare access over the local network.Direct does not turn off the connection toggle or guarantee network reachability.

How to test: hold conditions steady and switch modes

Note the current mode and server, then choose one destination to test. On the same network, test with Config first, then briefly switch to Proxy for comparison. If Proxy works but Config does not, check rule matches and policy references before re-entering server details. If both modes fail, check the server information, DNS, and local connection.

Use Direct to observe behavior without a proxy route, but don't assume that one successful direct connection means every service is working. Different destinations may depend on different DNS and connection conditions. After comparing, restore Config if that was the original mode. Leaving a temporary test setting in place can make local network access or everyday routing behave unexpectedly.

02 · Config

Rules: match conditions, then apply a policy

In Config mode, rules route requests according to conditions such as domains and IP addresses. Open Config, confirm which file is selected, then review its rules. Importing a file does not make it active, and editing a different file will not change the routing of the current connection.

Rules are generally evaluated from top to bottom, and the first match determines what happens next. Place specific domains and local network addresses appropriately, with broad conditions later. Use FINAL to handle requests that have not matched earlier rules. A rule being present does not guarantee it will take effect; check whether an earlier condition matches first.

KeywordWhat it matchesNotes
DOMAINThe exact domain specified.Useful for precise control of a single hostname.
DOMAIN-SUFFIXThe specified domain and its subdomains.Do not enter a full webpage URL or include a path.
DOMAIN-KEYWORDA keyword contained in the domain.Can match broadly; watch for unintended matches.
GEOIPThe geographic classification of an IP address.Results depend on the resolved address and the data used.
IP-CIDR / IP-CIDR6IPv4 / IPv6 address ranges.Check the address family and prefix length.
FINALRequests that did not match earlier rules.Place it at the end to define the default route.

How to test: start with a few clear rules

This snippet demonstrates syntax and order only. It is not a complete configuration and does not include a connectable server. PROXY routes matching requests through a proxy, DIRECT routes them directly, and REJECT blocks them. If you reference a custom policy name, make sure it exists in the active configuration; don't just copy a name from the example.

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

Save the original file before editing. Afterward, confirm it is still selected, reconnect if needed, then visit the destination and check the logs. A browser may reuse an existing connection, so refreshing the page alone may not verify a new rule. For more on matching, see How rule keywords are matched.

03 · Home / Add Server

Subscriptions and server management

A server entry stores the address, port, protocol, and authentication details needed for a connection. A subscription imports and updates a set of server entries. These steps assume you already have your own subscription or server details. This site does not provide, sell, or recommend servers or subscriptions. A one-time app purchase is not a service plan.

From Home, use the add option to open Add Server. To add a single server, select the correct Type and enter the details you already have. To import a subscription, select Subscribe, enter your existing subscription URL, and save it. Required fields vary by protocol; don't apply VLESS fields indiscriminately to Trojan or Shadowsocks.

Updating a subscription is not the same as switching servers

Updating a subscription refreshes its list; it does not guarantee that Shadowrocket will switch to the entry you want. After updating, return to Home and check the current selection, especially if an entry was removed or renamed. Do not enter a subscription URL in the Config file URL field: a subscription usually provides a server list, while a configuration file contains rules and settings. Handle each according to its source instructions.

Before deleting a subscription, check whether you still need its entries. Manual edits to subscription-generated entries may be overwritten by a later update. Subscription URLs, QR codes, and authentication fields may contain credentials; hide them before sharing screenshots or troubleshooting details. Follow the getting started guide for the full import process.

04 · Automatic Connection

On Demand: connect when conditions are met

On Demand triggers a VPN connection when specified conditions are met. It does not choose an available server for you or change the order in which rules match. Check the available conditions in the app's On Demand settings. The location and options may vary with the system and app interface; refer to what appears on your device.

How to set it up: enable it after manual connection works

First turn off automatic triggering and confirm that the selected server and Config work with a manual connection. Then open On Demand, set conditions for your needs, and enable the feature. If the interface lets you specify Wi-Fi names, check each name exactly. If a network is renamed, review the condition rather than assuming it still matches.

To verify the settings, make an actual network change—for example, switch between networks that do and do not meet the conditions—then check the system VPN status and the app's connection logs. Turning on the switch in Settings alone does not show that a condition was matched. Keep the server and configuration unchanged during testing so you can tell whether On Demand caused the change.

Other VPN configurations and system network conditions may also affect triggering. If connections keep cycling, disable On Demand, restore a stable manual connection, then re-enable conditions one at a time. Automatic triggering cannot guarantee continuous network availability; check separately after waking from sleep, switching networks, or changes in server status.

05 · Usage

Data: monitor traffic, not service billing

Data displays traffic statistics recorded by the app. Open Data and check the time range, period, or connection shown before watching upload and download changes. Statistics using different measurement scopes should not be compared directly, and app records are not a service provider's billing totals.

How to use it: track changes over a set time window

To check whether an action generated traffic, note the current figures, keep other app activity as steady as possible, make one specific request, then return to Data and check for changes. If the interface offers a statistics reset, record anything you need before using it. Resetting the app's statistics does not change server-side records or restore any service allowance.

Traffic indicates that data was transferred, not that the destination content loaded successfully. Little or no increase may be due to caching, an existing connection, or a mismatch in what is being measured. Consider Data alongside access logs, Global Routing, and the actual result. If traffic increases unexpectedly, check background app activity and the current network; don't infer a server problem from a cumulative figure alone.

06 · Settings

Common settings: change one variable at a time

Use the current interface as your guide. Some options depend on system capabilities or the active configuration. When troubleshooting, first confirm where a setting takes effect instead of changing several similar toggles at once.

DNS: check how domain names resolve

DNS resolves domain names to addresses used for connections. Check DNS options in Settings, then see whether the active Config defines settings such as dns-server. This avoids changing one place while overlooking another. Note the original value before making changes based on your network and configuration. Don't enter several addresses from unknown sources just to troubleshoot.

After changing a setting, retest the same domain and use the logs to distinguish a DNS failure from a connection failure. If an IP address works but a domain does not, investigate DNS first, while keeping in mind that TLS and the destination service may depend on the domain name. The example below shows syntax for using system DNS in a configuration; it is not a recommendation for every network.

[General]
dns-server = system

Test Method: understand what Connectivity Test checks

Test Method selects how to run a connection test. Check it in Settings, then return to Home to run Connectivity Test. Different methods check different parts of the network, so results from different methods should not be compared directly. If the interface lets you set a test target, choose a known target that responds reliably.

A successful test does not mean every website is reachable, and a failed test alone does not prove that authentication details are wrong. Note the test method, target, and network conditions, then check them against an actual request. When testing multiple entries, wait for each result to finish to avoid mixing them up.

Today Widget: quick status and controls

Today Widget is a shortcut available on systems that support it. Check the related options in Settings, then add and configure the widget using the system's steps. The status it can show and the actions it can perform depend on what the system and app currently support. Don't treat an old widget status as a live connection record.

For first-time use, open the main app to finish setup and grant any required permissions, then test the widget. If its display does not match the app, return to Home and check the current connection, then review the system's widget settings. Edit server details and rules, and run diagnostics, in the app.

iCloud: check what's synced before resolving conflicts

Check the iCloud section in Settings, along with the Apple Account currently signed in on the device and the app's iCloud access permission. Before syncing, review which items the interface lists. Don't assume that server lists, rule files, statistics, and all preferences are synced. Available items may differ by device; refer to what the interface shows.

Before enabling iCloud on another device for the first time, keep a copy of important local settings. If content differs between devices, stop editing on both, decide which copy to keep, then use the available options to resolve the conflict. Sync is not a standalone backup, and deletions may propagate. Treat files containing authentication details as sensitive.

07 · Diagnostics

Troubleshooting and recovery: trace the failure to a setting

Diagnostics helps collect and review troubleshooting information. Look for the relevant option in Settings, then use the tools shown in the current interface to check connections, DNS resolution, or request logs. Diagnostic information can narrow down the cause, but don't attribute every failure to DNS, rules, or a server without evidence.

How to troubleshoot: keep the steps repeatable

  1. Check the current state. Note the network type, Global Routing mode, selected server, and Config file. First rule out the possibility that you edited a file that isn't active.
  2. Reproduce one request. Make one specific request and note when it happens. Avoid testing from multiple apps at once, which can clutter the logs.
  3. Identify where it fails. Check whether an address was resolved, whether the connection and authentication proceeded, then whether the rule selected the expected policy.
  4. Change one setting and retest. Keep the before-and-after results. If nothing improves, restore the original value before checking the next setting; don't stack uncertain changes.

If Proxy works but Config does not, check the rules and policies first. If switching networks fixes the issue, compare the network conditions and DNS resolution. If a server still cannot connect after import, recheck the original server details. These are troubleshooting leads, not conclusions; rely on current request logs and repeatable tests.

Before sharing diagnostics, hide server authentication fields, credentials in subscription URLs, personal domains, and other sensitive information. Don't send a full configuration file containing credentials. To restore settings, start with the file and notes saved before the changes. Recheck Config, Global Routing, and On Demand, then verify with an actual request.

Rules changed, but nothing happened. What should I check?

First confirm Global Routing is set to Config. Then check the selected file in Config, rule order, and policy names. Reconnect and make a new request to rule out a reused connection, then check the relevant log entry.

Data shows traffic. Why won't the page load?

Traffic may come from connection attempts, other apps, or an existing connection. Check DNS resolution, policy, and connection results for the specific request; cumulative traffic alone cannot show whether the destination loaded successfully.

The connection comes back after I turn it off. How do I pause it?

Check and disable the On Demand trigger conditions first, then disconnect. Watch the system VPN status afterward. To resume automatic connections, enable conditions one at a time and verify each one.

Continue reading: follow the tutorial for first-time setup. For App Store, developer, and purchase record checks, see the genuine app guide.