Shadowrocket
Features & Settings
Set Global Routing first, then check rules, servers, and DNS. Change one setting at a time and verify the result with the same request.
Covers iPhone, iPad, Mac, Windows, Android, and Linux. The steps below use English interface labels on iPhone and iPad; menu locations and available settings may vary by platform.
- Global Routing → Rules → Policies
- Change one setting at a time
- Verify with logs and real requests
The three Global Routing modes
The mode determines whether requests are evaluated against the configuration’s rules; it does not select a server.
What it does: Global Routing sets the overall routing mode. Open Global Routing on Home to choose a configuration, proxy, or direct connection—the corresponding interface labels are Config, Proxy, and Direct. Config is usually the right choice for routing traffic by domain or address. Use Proxy or Direct temporarily to check whether rules are affecting a connection. Changing the mode is not the same as starting a connection; after choosing a mode, check the connection status on Home.
| Interface option | How requests are handled | When to use it | What to check |
|---|---|---|---|
| Config · Configuration | The policy is determined by the rules in the active configuration. | Everyday traffic routing, direct access to local networks, or assigning a policy to specific domains. | The active configuration, rule order, and FINAL rule. |
| Proxy · Proxy | Routes intercepted requests through a proxy instead of evaluating them against the usual routing rules one by one. | Temporarily check whether a rule is causing a different route. | The selected server and whether it is reachable. |
| Direct · Direct | Routes intercepted requests directly. | Check whether the local network can reach the destination on its own. | The current network, destination service, and DNS. |
How to set it up: In Config, confirm which configuration you want to use. Return to Home, set Global Routing to Config, select an existing server, and start the connection. Send a new request to the same destination and check the log for the matched rule and policy. Keep network conditions the same during testing; switching Wi-Fi and routing modes at the same time makes it hard to tell which change affected the result.
Keep in mind: Proxy is not a fix for every connection problem, and Direct does not disable the system VPN connection. The mode only describes how traffic is routed; system traffic interception, configuration exceptions, and platform networking can all affect the outcome. Restore your usual mode after troubleshooting so temporary settings are not left in place.
Rule types and policies
Rules determine what matches; policies determine what happens after a match.
Edit the active configuration in Config
What it does: Rules route requests according to conditions such as domain or address. In Config, open the active configuration using its edit option and check the [Rule] section. Rules are evaluated from top to bottom, and the policy on the first matching line is applied. More specific exceptions should generally appear before broader rules.
How to configure it: 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 match IPv4 and IPv6 ranges, respectively; GEOIP matches based on the address’s geographic data. USER-AGENT depends on request information being available, which cannot be assumed for every connection.
Keep in mind: PROXY uses a proxy policy, DIRECT connects directly, and REJECT blocks the request. The interface option Proxy differs in capitalization from the rule policy PROXY; keep keywords exactly as written when editing a configuration. FINAL is the fallback when no earlier rule matches and belongs at the end. If placed too early, it makes subsequent rules ineffective.
This example demonstrates syntax only; it is not a complete configuration for every network. Save a copy of the original configuration before editing. After making changes, send a new request and check the match log. Existing connections may continue using their previous route, so refreshing a long-running connection alone does not prove that a new rule failed to take effect. For the full section structure and matching details, see the configuration reference.
Manage subscriptions and servers
Server details, subscription sources, and configuration files are separate items and should be managed separately.
Home, Add Server, and Subscribe
What they do: A server entry stores its address, port, protocol, and authentication details. Subscribe retrieves a server list from a subscription URL you already have. Config stores settings such as routing rules. Importing a subscription does not automatically provide rules suited to your needs, and switching configurations does not replace your server list.
Where to go and what to do: On Home, tap Add Server and enter the details provided by your service. Shadowsocks, VMess, VLESS, Trojan, Hysteria2, and WireGuard require different fields; do not reuse settings from another protocol just because the names look similar. If you have a QR code, use Scan QR Code. If you have a subscription URL, choose Subscribe, check the URL, save it, and update the list. Then select an entry.
- Before importing, identify whether you have a single server, a subscription URL, or a configuration file, and choose the corresponding import option.
- After saving, check that the number and names of entries match your expectations, then run Connectivity Test.
- Select an entry, connect, and make a normal request. Once it works, you can organize older entries.
Keep in mind: Updating a subscription may overwrite entries generated from that source, so consider the effect of the next update before editing them manually. Subscription URLs may contain access credentials; do not include them in public screenshots, chat logs, or support requests. Connectivity Test results reflect only the selected test method and do not replace real-world access checks. A failed update does not mean every saved server has stopped working.
When migrating, distinguish between exporting a configuration and exporting server details. Do not publicly share content containing credentials as if it were a regular rules file. Check unfamiliar configurations for rules, DNS, and rewrite settings before enabling them; a file name alone does not tell you what it does.
On Demand connections
Verify manual connections first, then add automatic triggers.
What it does: On Demand asks the system to establish a connection when specified network conditions are met, reducing the need to connect manually each time. It controls when a connection starts, not whether a domain uses PROXY or DIRECT. Once connected, requests are handled according to Global Routing and the active configuration.
Where to go and what to do: In Settings, find On Demand and review the available Wi-Fi, cellular, and network exception conditions. First make sure a manual connection works, then enable only the condition you need. After saving, switch to the relevant network, check the system connection status, and test with the same request. For exceptions tied to a specific Wi-Fi network, verify the network name and check that the conditions do not conflict.
Keep in mind: With On Demand enabled, a qualifying system trigger may reconnect after you disconnect manually. This does not necessarily mean the connection switch is broken. To pause automatic connections, disable the relevant conditions before disconnecting. For Wi-Fi networks that require a web sign-in, complete the sign-in first. System permissions, sleep, and network switching can also affect when a trigger runs, so an immediate reconnect is not guaranteed.
Data usage statistics
Check the statistics’ scope before comparing values; client-side records are not a provider’s bill.
What it shows: Data displays traffic usage recorded by the client. Use it to track upload and download changes during a connection and help identify ongoing requests. The scope depends on the object and time range shown in the interface; do not assume a total on one screen represents all network usage on the device.
Where to go and how to use it: Open Data and check the displayed scope and available filters. To investigate unexpected usage, note the starting value, pause unrelated background activity, perform the target action once, then return to Data and compare. If a reset option is available, save any records you need before resetting so you can compare the before-and-after values.
Keep in mind: Protocol overhead, retries, reporting periods, and measurement methods can all cause client statistics to differ from system or provider records. Usage shown in a subscription usually comes from information included in the subscription response; it is not the same as Data’s local total. The absence of subscription usage figures does not mean the subscription has stopped working. An increase in traffic only indicates data transfer; check request results and logs to confirm whether the intended service worked.
Common Settings
Menu locations depend on the current platform; also check settings already defined in the configuration.
DNS: domain resolution and configuration sources
What it does and where to find it: DNS resolves domain names to addresses. It affects both the connection destination and rules that rely on addresses. Look for DNS options in Settings and check whether the active Config specifies DNS settings, so you do not change one place while overlooking the settings actually in use.
How to configure it and what to watch for: Keep a copy of the current working settings. Determine whether the problem occurs during domain resolution or later in the connection before changing the DNS method. After a change, test the same domain and check the logs; clear relevant caches using the available interface option if needed. Do not change DNS, servers, and rules all at once. Encrypted DNS also requires a reachable network path; entering a resolver address does not guarantee it can be reached.
Test Method: Connectivity Test options
What it does and where to find it: Test Method in Settings determines how Connectivity Test checks server entries. Different methods test different layers: some focus on basic connectivity, while others depend on a response from the test destination. Their results are not directly comparable as if they measured the same thing.
How to configure it and what to watch for: When comparing entries, keep Test Method, test destination, and local network the same. Run tests in succession before comparing results. A timeout may be caused by the server, test destination, or current network; a reachable result does not guarantee that every service will work. Use tests to narrow down the issue, then check access to the service you actually need. Do not treat a single latency value as a definitive result.
Today Widget: quick status and actions
What it does and where to find it: Today Widget lets you check status or use quick actions from a system-supported widget area. Check the related options in Settings, then add the widget using your system’s widget controls. Available information and actions depend on the system and the current app interface.
How to configure it and what to watch for: Set up and test the main app’s permissions and connection before configuring the widget. Widget updates may depend on system refresh timing, so a status that has not refreshed is not the final connection result. If the display looks wrong, check the current status on Home rather than tapping the widget repeatedly.
iCloud sync: manage settings across devices
What it does and where to find it: On Apple devices where the option is available, iCloud settings in Settings manage the content the app supports syncing. Sync depends on your system iCloud status, account, and app permissions; do not assume it includes every item, such as servers, configurations, or history.
How to configure it and what to watch for: First confirm that both devices use the intended iCloud account, then review the sync scope shown in the interface. Keep a local copy on each device before enabling sync for the first time. Make changes on one device, wait for them to sync, then check the other device to avoid overwrites or conflicts from simultaneous edits. Sync is not a separate backup and does not transfer App Store purchases. Handle configuration migration separately from reinstalling or downloading the app again.
Diagnostics: collect troubleshooting details
What it does and where to find it: Diagnostics provides information for troubleshooting connections; look for it in Settings. It helps identify whether a failure occurs during DNS resolution, connection setup, or a later request. It is not an automatic repair tool.
How to use it and what to watch for: Note the network type, Global Routing mode, and active configuration when the problem occurs, then run diagnostics or review the available logs. Reproduce the issue once to keep the logs easy to analyze; avoid running many tests at the same time. Before sharing, remove server addresses, subscription links, authentication details, and unnecessary browsing records. Share the error type and steps to reproduce the issue, not a complete log containing sensitive information.
Verification checklist after setup
Check connection status, traffic routing, and automatic triggers separately.
- Check the network. Confirm that your Wi-Fi or cellular connection works. Complete any required web sign-in first and note which network you are using for the test.
- Check server details. Verify the protocol, address, port, and authentication fields, then run Connectivity Test. Do not assume a failed test means the rules are at fault.
- Check Global Routing. Select Config when you need rule-based routing, and make sure the active configuration is the one you just edited—not a similarly named copy.
- Check a single request. Send a new request to the destination and check the matched rule and policy. If DNS resolution fails, check DNS first; if the wrong rule matches, check the order and conditions.
- Test automation last. Enable On Demand only after manual connections are stable. Then check network switching, Today Widget status, and changes in Data.
If a problem appears after a change, undo that one setting and test again under the original conditions. Reproducible before-and-after differences are more useful than changing several settings at once. For your first setup, see the getting started guide. For a line-by-line rule review, use the configuration reference. For installation and access details, see downloads for all platforms.
It works in Proxy but not in Config. What should I check first?
First confirm which configuration is active, then compare the matched rule and policy for the same destination in Config. Check whether an earlier REJECT, DIRECT, or broad match is taking precedence, and consider the DNS result. Do not replace the entire configuration before reviewing the match log.
The connection starts again after I disconnect. How can I pause it?
Check whether On Demand still has a trigger condition that matches the current network. Disable the relevant condition before disconnecting, then check the system status. If it keeps reconnecting, review other system automation settings related to the connection.