Shadowrocket Official Manual / Features & Settings
Shadowrocket Common Settings
Choose a routing mode first, then check your configuration, server and connection status.
This page explains what each feature does, where to find it, how to configure it and what to watch for. Menu locations are based on common iPhone and iPad layouts. Shadowrocket is also available for Mac, Windows, Android and Linux; menu layouts and available system integrations may vary by platform. Follow what appears on your device.
Connection modes
The three Global Routing modes
What it does: Global Routing determines how connections are routed. The three modes—configuration, proxy, and direct—correspond to Config, Proxy, and Direct in the interface. It is not a protocol selector and does not make servers from a subscription usable automatically. Before changing modes, check which server and config are selected.
Where to find it and how to use it: On Home, open Global Routing, select an option and return. Choose Config for everyday use with existing routing rules. To check whether a problem is caused by the rules, temporarily compare with Proxy. To test whether your local network can reach a destination, compare with Direct. Restore your original mode when you're done so a temporary test setting doesn't become your default.
| Interface option | How it works | When to use it | What to check |
|---|---|---|---|
| Config · Configuration | Handles requests according to the rules and policies in the currently enabled configuration. | When you need different routes for different domains or addresses. | Check that the configuration is enabled and that rule order and policy references are correct. |
| Proxy · Proxy | Routes traffic handled by the client through a proxy. | To temporarily rule out differences caused by routing rules. | Check whether the selected server is reachable and its protocol parameters match. |
| Direct · Direct | Uses a direct connection without forwarding through the selected proxy server. | To compare against your basic network connection or check access to local resources. | Check that the local network and destination service are working. |
What to watch for: Proxy does not guarantee the destination is reachable, and Direct does not turn off the system connection switch. Whether a connection is established, whether a request is handled by the client and which policy it follows are three separate questions. System exclusions or an app's own connection methods may also affect what the client handles. Check the request log to see what happened.
Matching and handling
Rule types and policies
What they do: Rules identify destinations; policies determine how to handle them. For example, DOMAIN-SUFFIX matches a domain suffix, while PROXY routes a request through a proxy. Don't confuse the Proxy mode with the PROXY policy in a rule: the former selects an overall operating mode, while the latter is the action for a specific rule in a configuration.
Where to find them and how to use them: In Config, find the currently enabled configuration and open its editor or rule list. Make a backup first. Put narrow, specific exceptions before broader rules, then use FINAL for requests that haven't matched earlier rules. The example domains below illustrate syntax only; they are not server details.
DOMAIN,api.example.com,PROXY
DOMAIN-SUFFIX,example.com,DIRECT
IP-CIDR,192.168.0.0/16,DIRECT
FINAL,PROXY
With this order, api.example.com matches the first rule and isn't evaluated against the suffix rule below it. Other domains ending in example.com match the second rule. Simply adding a rule doesn't mean a request will reach it.
| Keyword | Matches | Notes |
|---|---|---|
| DOMAIN | An exact domain name. | Use for a specific host exception. |
| DOMAIN-SUFFIX | A domain suffix and its subdomains. | This covers more than an exact domain; check that it won't override an earlier requirement. |
| DOMAIN-KEYWORD | A keyword contained in a domain name. | May match unrelated domains. Narrow the condition before using it. |
| IP-CIDR / IP-CIDR6 | IPv4 or IPv6 address ranges. | Consider the address family, subnet mask and how domain resolution affects matching. |
| GEOIP | A region associated with an address in a geolocation database. | The database's region does not necessarily indicate where the service operator is located. |
| USER-AGENT | User-Agent content available to rules. | Can match only when the relevant field is available. |
| FINAL | Requests that haven't matched an earlier rule. | Use at the end of the rule list as a fallback. |
What to watch for: PROXY uses a proxy route, DIRECT connects directly, and REJECT blocks matching requests. A reject rule may also block resources a page depends on. If page content is missing, check the match log before switching servers. Custom policy names must exactly match the names defined in the configuration. For more on rule order, see Custom Rules and FINAL Explained.
Server types
Protocols and their parameters
What they do: A protocol defines how the client communicates with a server. Shadowrocket supports Shadowsocks, VMess, VLESS, Trojan, HTTP, SOCKS5, WireGuard and Hysteria2, each with different server-side settings. A protocol's name alone doesn't tell you whether it will be faster or use less power on every network.
Where to find them and how to configure them: On Home, open Add Server and choose a type based on your existing server details. When editing an entry, first confirm its type, then check the address, port, authentication fields and any transport or TLS options required by the service. Imported subscriptions usually fill in these fields, but make sure the client recognized the type correctly and that the details match the source. Different types showing different fields is normal; don't copy one protocol's settings into another.
What to watch for: The same port number doesn't mean the same protocol, and enabling TLS doesn't guarantee that certificate and hostname requirements are met. Don't loosen certificate checks just to make a test pass. First verify the server name, system time and settings provided by the service. See the protocol reference for field definitions and design considerations. Remove sensitive details from screenshots and logs before sharing them.
Managing service details
Subscribe and the server list
What they do: Subscribe retrieves server details from a subscription you already have; Add Server lets you enter a server manually. The server list determines which connection to use; it isn't a complete routing configuration. A successful subscription refresh means the data was retrieved and parsed, not that every server in the list can connect.
Where to find it and how to use it: In Config, find the Subscribe option, enter the subscription URL from your own service provider, confirm the name and update. Then return to Home to check the list. To add a server manually, use Add Server; to import an existing QR code, use Scan QR Code. Before importing from the clipboard, confirm the content comes from your own service details. After saving, check that the entry types and count are as expected.
When managing an existing list, use clear names to distinguish manually added entries from subscription groups. Test a new entry before removing an old one. Changes to subscription-generated servers may be overwritten at the next update. If you need to keep an adjustment, first check where the entry came from and how updates work so a temporary change isn't mistaken for a permanent one.
What to watch for: Subscription URLs often contain authentication details and should be kept private. Don't post them in public forums or logs. If an update fails, check your current network, the URL, whether the service is still active and the response format, in that order. Don't repeatedly delete the entire list. See How to Import a Subscription for the steps.
Configuration files
Saving and enabling a Config
What it does: Config manages configuration files, which can contain rules, DNS behavior, local mappings and other settings. Saving a file, selecting it as enabled and switching to the Config routing mode are related but separate actions. If a change has no effect, check all three.
Where to find it and how to use it: Open Config, check which file is marked as enabled, then edit that file. Keep a copy before making changes. Adjust one behavior at a time—for example, change a domain rule, save and confirm the configuration is enabled, then test the same destination. Before importing a configuration, distinguish a server subscription from a configuration file; a link's appearance alone doesn't tell you what it contains.
What to watch for: A remote configuration may replace local content when updated, so check what will be overwritten before making long-term customizations. General, Rule, Host and URL Rewrite each serve a different purpose; a rule file isn't just a list of server addresses. Don't replace your current file with an entire configuration from an unknown source. Pay particular attention to its DNS, mapping and URL rewrite settings. See Configuration File Sections Explained.
Automatic connection conditions
On Demand connections
What it does: On Demand uses network conditions supported by the system to trigger connection behavior, reducing the need to toggle the connection manually when switching networks. It controls when to attempt a connection; it doesn't replace Global Routing, which controls routing after connection, or check whether every remote service is healthy.
Where to find it and how to configure it: Look for On Demand in the app's Settings. Available conditions vary by platform, so use the options shown on your device to configure behavior for Wi-Fi, cellular or a specific network. Enable it only after manual connection works, then test connecting to and disconnecting from the target network, as well as resuming use after locking the device. If the system asks you to confirm the connection configuration, read the prompt and follow its instructions.
What to watch for: Don't change several conditions at once and test only once. If the connection turns off and then reconnects, first check whether On Demand is triggering, then check other system automation settings. Background scheduling, network permissions and power-saving behavior vary by system, so don't assume the trigger timing on one device applies to every platform.
Traffic records
Data statistics and what they cover
What it does: Data shows traffic recorded by the client, helping you check whether an action transferred data and whether traffic changed before and after a connection. These figures follow the client's own counting method. They aren't billing records for a network service, and they don't replace the system's cellular data usage statistics.
Where to find it and how to use it: Open Data and check the displayed scope and categories, then watch the upload and download totals. To investigate a single action, note the current figures, stop unnecessary background transfers, then open just one test destination and compare the readings. If the interface offers a reset option, save any records you need before resetting. Clearing the statistics won't fix a connection problem.
What to watch for: Protocol overhead, when counting starts, background activity and traffic handling scope can all cause differences between client and system totals. If the connection switch is on but the numbers aren't changing, no requests may be entering the client's handling scope. An increase in traffic also doesn't mean every page resource loaded successfully. Check the destination and request log together.
Common options
Common Settings options
Settings brings together app behavior and some system integration options. The options below are available only on platforms that show them. If an option isn't on your device, don't look for it based on a screenshot from another platform. Note the original value before changing anything so you can restore it if needed.
DNS: Check resolution and connection separately
What it does and where to find it: DNS resolves domain names to addresses. Check related options under DNS in Settings and in the active configuration. Successful resolution doesn't guarantee the destination port is reachable, and a reachable server doesn't guarantee that all domain names will resolve correctly.
How to configure it and what to watch for: First check whether the active configuration specifies DNS behavior, then review the global options. Avoid changing both at once, or you won't know which setting took effect. Use the resolution method required by your existing network or service settings, then retry the destination. If only some domains fail, distinguish DNS errors from rule-matching and connection errors instead of blaming DNS for everything. Check IPv6 options against your local network's actual capabilities.
Test Method: Choose how to test
What it is and where to find it: Test Method is a Settings option for connectivity tests. It determines how a test is run. Different methods observe different parts of the connection, so their results shouldn't be compared as if they measured the same thing.
How to configure it and what to watch for: Choose one of the options shown in the current interface, then return to the server list and run Connectivity Test. When comparing servers, keep the test method, network and destination the same. A test result is a snapshot under current conditions, not a guarantee of sustained bandwidth. After a successful test, try the destination you actually need to reach.
Today Widget: System shortcut
What it is and where to find it: Today Widget provides shortcuts through a system widget. On devices that offer this option, look for it in Settings. It provides a shortcut; it doesn't recreate servers or rules.
How to configure it and what to watch for: First connect successfully in the app, then add an available widget using the system's widget controls. If its status doesn't update, open the app and check the actual connection instead of tapping repeatedly. Widget availability and refresh timing vary by system; follow what your device shows.
iCloud: Sync scope and local copies
What it is and where to find it: On Apple devices that offer iCloud options, check sync settings in Settings and confirm the system allows the app to use iCloud. This depends on your system account and permissions; iCloud isn't a universal sync option across all platforms.
How to configure it and what to watch for: Keep a local copy of your configuration before enabling sync, then check the scope described in the interface. Don't assume servers, configurations, system connection permissions and live connection status all move together. After switching devices, check the server list, enabled configuration and connection permissions separately. Before editing on both devices, confirm sync has finished to avoid overwriting newer content with an old copy.
Troubleshooting
Diagnostics and troubleshooting steps
What it is and where to find it: Diagnostics helps investigate network and connection issues. Look in Settings for the diagnostic options available on your platform. Connectivity Test in the server list checks connectivity. Diagnostic records help identify a problem; they won't fix incorrect protocol settings or outdated service details automatically.
How to troubleshoot: You don't need to change a lot of settings up front. Choose one server and one destination, then follow the steps below in order. Record the result after each step before moving on. This helps avoid confusing several simultaneous changes with a single cause.
- Check the basic network. See whether the current network requires authentication and confirm the system time is correct. If needed, compare using another network you already have access to.
- Test the server. Keep
Test Methodthe same and runConnectivity Test. If every server fails, first check the network and whether your subscription is active. If only some fail, check those entries first. - Check the protocol settings. Verify the address, port, authentication details, transport and TLS settings one by one. Don't rely on the server name alone.
- Check for routing effects. Note the current mode, briefly compare
ConfigandProxy, then restore your original setting. If the results differ, check the rules and policy references. - Inspect the specific request. Check available destination, resolution, policy and error details in diagnostics or the request log. If only some page resources fail, investigate the affected domains individually.
- Undo the latest change. Restore the previous DNS settings, rules or configuration, then test the same destination again. Don't reset everything as a substitute for finding the cause.
What to watch for: Logs may contain server addresses, destinations and authentication details. Remove sensitive information before sharing them. A low latency reading reflects one test under specific conditions; it doesn't guarantee download speed or the experience in every app. For a detailed connection-failure checklist, see How to Troubleshoot Server Timeouts.