Shadowrocket Official Guide · Features

Shadowrocket
Features and Settings

First choose how connections should be routed, then check your servers, rules, and system settings. Change one type of setting at a time so you can assess the results and revert if needed.

Global Routing · Routing mode Config · Matching rules Settings · Connection behavior

Home / Global Routing

Global Routing: Config, Proxy, and Direct

What it does: Global Routing determines how connections handled by Shadowrocket are processed. Config uses rules in the active configuration to select a policy; Proxy routes connections through the selected proxy; Direct connects without a proxy server. These are separate from server selection and the connection toggle: selecting a server does not turn on the connection, and turning on the connection does not mean every request will use a proxy.

Where to find it: In Home, find Global Routing and check which of Config, Proxy, or Direct is selected. Note the current mode and server before testing. Avoid changing the server and configuration at the same time, or it will be difficult to tell which change affected the result.

What each mode does and what to check
Option How it works When to use it What to check
Config · Configuration Routes traffic according to the rules in the active configuration. For everyday routing that distinguishes between proxy, direct, or rejected traffic. Make sure the configuration is enabled and the policies referenced by its rules are valid.
Proxy Routes connections primarily through the currently selected proxy server. To temporarily check whether a server can handle a specific request. A reachable server does not guarantee that every destination will be accessible.
Direct Sends connections directly, without a proxy server. To check whether the local network is working and narrow down the cause of a problem. A successful direct connection does not confirm that proxy settings are correct.

How to use it: For everyday rule-based routing, select Config and make sure the intended configuration is selected on the Config screen. If some requests fail, temporarily switch to Proxy and test the same destination through the selected server. Then switch to Direct and compare the result over your local network. Restore your usual mode when you finish. Start a new request for each test; existing connections may continue using the route they were established with.

Keep in mind: Proxy is not a long-term substitute for fixing rules. If Proxy works but Config does not, check the matching result, policy name, and DNS settings. If both fail, check the server details, network conditions, and status information from your service provider.

Config / Rule

Rule-based routing: match conditions and actions

What it does: Each rule specifies what to match and what to do when there is a match. DOMAIN matches a specific domain; DOMAIN-SUFFIX matches a domain suffix; DOMAIN-KEYWORD matches a keyword in a domain. IP-CIDR and IP-CIDR6 match address ranges, while GEOIP checks an IP geolocation database. USER-AGENT relies on information available in a request, so it is not a general-purpose condition that can match every connection.

Where to find it: In Config, review the active configuration and its rules. Check not only whether a rule exists in the file, but also whether that file is in use, whether Global Routing is set to Config, and whether the request provides the information the rule needs.

DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
FINAL,PROXY

These are syntax examples, not a complete file to replace your current configuration with. PROXY, DIRECT, and REJECT route through a proxy, connect directly, and reject a request, respectively. Custom policy names must match their definitions in the configuration. FINAL handles connections not matched by earlier conditions; it is not a domain rule.

How to configure it: Back up the current configuration first, then add a clear condition through the rule editor. Rules are generally evaluated in order, so put specific exceptions before broader rules and the final handling rule at the end. Save your changes and confirm that the edited configuration is active. Test a known destination again, then check the logs or connection records to see which policy was actually used.

Keep in mind: A destination may use multiple domains and addresses, so changing only its homepage domain may not cover every request. Address-based rules can also depend on DNS results. Do not judge whether a rule matched solely by whether a page loads; check the connection record, and avoid adding many rules whose effects you cannot explain.

Home / Subscribe / Add Server

Manage subscriptions and servers separately

What they do: Subscribe imports and updates a server list you already have; Add Server lets you enter one server manually. A subscription provides server entries, not a complete routing policy in Config. Updating a server list does not automatically change all your routing rules.

Where to find them: Choose the appropriate type from the add menu in Home. Use Add Server to enter details manually or Subscribe to import a subscription. You can also import existing data with Scan QR Code or from the clipboard; recognition depends on the content format and support in your current version.

How to configure them: Get the subscription URL from your service provider. Copy it in full and check for missing parameters, spaces, or line breaks. To add a server manually, select its protocol first, then check the address, port, authentication, and transport settings one by one. Shadowsocks, VMess, VLESS, Trojan, WireGuard, and Hysteria2 use different fields; do not apply one protocol's setup steps to another.

  1. Give each subscription a descriptive name and keep a record of where it came from.
  2. After importing, check the groups and server entries, then run Connectivity Test on one entry.
  3. Once you have tested an actual connection, organize the list or remove duplicate manual entries.
  4. After updating a subscription, check that the selected server is still there and that names referenced by your configuration remain valid.

Keep in mind: An update may overwrite manual changes made to subscription entries. Manage custom entries separately if you need to keep them. Subscription links may contain account credentials, so handle full URLs carefully in logs, screenshots, and backups. Before deleting a subscription, make sure you can restore it from a backup. See the subscription and server management guide for details.

Settings / On Demand

On Demand: trigger connections by condition

What it does: On Demand triggers connection behavior based on network conditions supported by the system. It determines when to attempt a connection; it does not replace Global Routing or fix an unavailable server. Rule-based routing answers “where should a request go?” On Demand answers “when should a connection start?” Treat them as separate settings.

Where to find it: In Settings, look for On Demand and its rule options. Available conditions depend on the device's operating system and the current interface. Before enabling it, verify your subscription, server, and configuration manually to make sure the connection works.

How to configure it: Keep a record of your current settings, then choose from the network conditions available in the interface, such as behavior for different Wi-Fi networks or network types. Add one condition at a time. Test what happens when joining and leaving that network, and when switching to mobile data. Add other conditions only after verifying the first; do not enable multiple overlapping rules at once.

Keep in mind: After you manually turn off the connection, On Demand may turn it on again the next time a condition is met. If a connection starts again after being turned off, check On Demand first, then review the system's network settings. Also test network changes and waking from sleep, and account for system permissions. One test does not prove that every scenario is covered.

Data

Data: monitor traffic, not your provider's bill

What it does: Data displays traffic recorded by the client. Use it to check whether data is being transferred after connecting or to compare usage before and after a test. The statistics' scope, reset behavior, and breakdown depend on what the screen shows. A displayed counter should not be treated as the total for all network activity on your device.

Where to find it: Open Data and identify which statistic is displayed and its time range before checking upload and download figures. If the screen offers a reset option, record any values you need before resetting so you can refer to them later.

How to check it: Note the current figures before testing, pause unrelated background transfers, and visit a known destination. Return to Data and compare the numbers. If you are also using logs, keep the test period consistent. This can help distinguish a connection with no application traffic from one where traffic is flowing but the destination is returning an error.

Keep in mind: Client statistics may use a different basis from your provider's billing, including differences in measurement periods, protocol overhead, and reset cycles. Traffic in Data does not mean every request succeeded, and a low count does not mean the connection is down. Assess traffic alongside actual results, matching policies, and logs; do not use it to estimate your remaining subscription allowance.

Settings

Settings: DNS, test methods, and sync

DNS: distinguish name resolution from connectivity

What it does and where to find it: DNS resolves domain names to addresses. Check related options in Settings or the DNS section of the active Config; which setting takes effect depends on the configuration. If a server connects but domain access fails, DNS is one thing to check, but not every failed request is a DNS problem.

How to configure it and what to check: Note the current settings and check whether the configuration file contains overriding options before making changes. Change one DNS option at a time, then start a new request and check the logs for resolution and connection results. Do not change DNS, Global Routing, and server settings together. Existing connections or cached results can affect a test, so reconnect before comparing results.

Test Method: know what the test measures

What it does and where to find it: Test Method is in the relevant test settings and selects how the client checks connectivity or latency. Different methods do not test exactly the same things, so interpret each result in the context of the method used. Do not compare the displayed times alone.

How to configure it and what to check: Find Test Method in Settings. Keep the test method, destination, and network conditions consistent, then run Connectivity Test on a group of servers. If a test responds but actual access fails, check applicable settings such as the protocol, TLS, and SNI. If every server fails one test method, first confirm that the test destination is available rather than immediately deleting all the servers.

Today Widget: a shortcut where supported by the system

What it does and where to find it: Today Widget is a system widget entry that can show status or offer available actions in supported system interfaces. Check Settings for related options, then open the system's widget manager to see whether the widget can be added.

How to configure it and what to check: Follow the system prompts to add the widget, then return to the client to check the server and connection status and test the shortcut. The operating system version may affect whether the widget can be added, what it displays, and when it refreshes. If its display is delayed, rely on the client and system connection status; widget text is not a real-time diagnostic result.

iCloud: keep a recoverable copy before syncing

What it does and where to find it: iCloud settings support data sync on compatible platforms. First confirm that iCloud is available in your system account settings, then check Shadowrocket's sync options and what they sync. Do not assume that all local data, system permissions, or live connection status will sync to another device.

How to configure it and what to check: Export any configurations you need to keep before enabling sync. Confirm that both devices use the intended iCloud account and wait for syncing to finish. Afterward, check Subscribe, the selected server, Config, and Global Routing, then connect. Sync is not a standalone backup; accidental deletions and unwanted changes may also propagate. For transfers between computers and other operating systems, use the import and export methods supported by each platform.

Settings / Diagnostics

Diagnostics: isolate connection issues layer by layer

What it does: Diagnostics helps collect or review diagnostic information and works alongside Connectivity Test, connection records, and logs to locate problems. It provides evidence; it does not automatically restore a connection. Troubleshoot layer by layer, starting with the local network, then the server, DNS resolution, rules, and destination service.

Where to find it: Look for Diagnostics in Settings; the available logs and tools depend on the current interface. Note the network, time, and symptoms when the issue occurs, then start the relevant logging. Some logs need to be enabled before reproducing the issue; enabling them afterward may not show the full history of earlier connections.

  1. Check the local network: Make sure the device is connected to a working network and that its system clock is correct.
  2. Check the server: Run Connectivity Test on the selected server and verify its address, port, authentication details, and applicable TLS settings.
  3. Compare routing modes: Test the same destination with Config and Proxy, keeping the selected server unchanged.
  4. Reproduce and record the issue: Open the destination again and check where DNS resolution, policy matching, or the connection fails.
  5. Restore your settings: Turn off temporary diagnostic logging, return to your usual mode, and keep only changes you have verified.

Keep in mind: Before sharing diagnostic files, check for subscription URLs, server credentials, visited domains, and personal network information. Redact anything you do not need to disclose. For handshake failures, check the relevant protocol settings and system clock; for rule mismatches, check the matching order. Do not assume every error is a “server timeout.” See the glossary for more terminology.

Feature scope and download options

Client settings and network service are separate

Shadowrocket provides client features for importing servers, proxy connections, rule-based routing, and diagnostics. Check with your service provider whether your servers are available, your subscription is still valid, and which transport methods the service supports. A one-time client purchase does not include a network service plan. This site does not provide, sell, or recommend servers or subscriptions, and changing settings does not replace authorization for services you already use.

There are two ways to get Shadowrocket: The iPhone / iPad version is a one-time $2.99 purchase on the App Store; the Mac / Windows / Android / Linux versions are free. The Mac version is available for Apple silicon and Intel. For iPhone / iPad system requirements, refer to the App Store listing. Verify the developer, Shadow Launch Technology Limited, and app ID 932747118. Installers for other platforms are available from this site at /dl/shadowrocket/.

To get the app or check the steps for allowing it in your system, visit the downloads and installation guide for all platforms. If your device already connects, back up your current configuration before changing features described on this page. Verify each change before moving on, so you can trace the cause if something goes wrong.