Official Guide · Features and Settings
Shadowrocket Features and Settings
Choose a Global Routing mode first, then check your server and Config. Adjust On Demand, DNS, and test methods for your use case, and verify the results with Data and Diagnostics.
- Global Routing：Config / Proxy / Direct
- Rules are matched in order
- Change one setting at a time
Global Routing: Config, Proxy, and Direct
Global Routing determines how the current connection is routed. Open Global Routing from Home to choose Config, Proxy, or Direct. These are routing modes, not server protocols or connection-quality settings. After switching servers, check this selection separately.
For everyday routing by domain or IP, first confirm the selected profile in Config, then use Config mode. To check whether a rule is causing a problem, briefly switch to Proxy or Direct and test the same destination again. Restore the original mode afterward so a temporary troubleshooting setting does not become your everyday setup.
| Mode | How it works | When to use it | What to check |
|---|---|---|---|
| Config | Routes connections according to the rules and policies in the active Config. | For everyday rule-based routing or to verify that a rule works. | Active Config, rule order, and the policy each rule points to. |
| Proxy | Sends connections handled by the client through the currently selected proxy. | To check temporarily whether the current server can reach a destination. | Server availability, protocol settings, and the destination's response. |
| Direct | Sends connections handled by the client directly to their destinations. | To check direct access from your local network to a destination. | Whether the local network, DNS, and destination are working. |
Direct does not turn off the connection switch or remove the VPN configuration from the system. Proxy does not guarantee that every app request will succeed; the server's exit, destination service, and current network can all affect the result. When troubleshooting, note the connection switch state, Global Routing mode, and whether the destination is reachable separately—do not treat them as a single result.
Rule-Based Routing: Match Conditions, Order, and Policies
Rules specify which policy handles a connection. In Config, open the profile in use and check its rules and policy definitions. After adding or editing a rule, save the profile and confirm it is selected. Importing a profile into the list does not make it active. Global Routing must also be set to Config to check routing against the selected profile.
Match conditions and policies serve different purposes. Keywords such as DOMAIN and DOMAIN-SUFFIX describe the destination; DIRECT, REJECT, or a proxy policy name in the Config describes how to handle it. Policy names must match the definitions in the active Config—do not infer which server a policy uses from its name alone. Rules are generally evaluated from top to bottom, so place specific exceptions before broader conditions.
| Keyword | What it matches | What to keep in mind |
|---|---|---|
DOMAIN | An exact domain name. | Use when you want to handle a single, specific hostname. |
DOMAIN-SUFFIX | A domain suffix and its subdomains. | Covers more than a single DOMAIN rule. |
DOMAIN-KEYWORD | A keyword contained in a domain name. | Can match unintended destinations; check its scope first. |
IP-CIDR / IP-CIDR6 | IPv4 or IPv6 address ranges. | Check the address family, subnet, and resolution behavior. |
GEOIP | Destinations classified using an IP geolocation database. | Classification uses the destination IP's geolocation database record, not its domain suffix. |
USER-AGENT | User-Agent information that rules can match. | Not available for every connection, so it is not a reliable catch-all. |
FINAL | Connections not matched by an earlier rule. | Place it last and confirm the fallback policy works. |
The following is a rule syntax example, not a file to use as a full Config replacement. PROXY represents a proxy policy; check the active Config for the policy definition before using it. example.com is a sample domain.
DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
FINAL,PROXYDIRECT means connect directly; REJECT means reject matching connections. Before using REJECT, check what the destination is used for to avoid breaking sign-ins, content loading, or background requests. If a destination works in Proxy but fails in Config, first check which rule matched and which policy it selects instead of adding more broad rules.
A Config may also include DNS, policy groups, and other settings. When editing rules, change only the relevant parts and keep a copy of the original file. Existing sessions may continue using their previous route; start a new request to verify changes and reconnect if needed. For rule fundamentals, see the glossary.
Multiple Protocols: Use Your Existing Server Settings
Shadowrocket supports multiple connection protocols, including Shadowsocks, VMess, VLESS, Trojan, Hysteria2, WireGuard, HTTP, and SOCKS5. A protocol defines how the client and server exchange data; it is not a speed setting you can swap at will. Use the actual settings for your existing server: choose the matching type in Add Server on Home, or import an existing link that contains those settings.
Check the address and port first, then verify authentication, transport, and TLS-related fields. Required fields vary by protocol: some use a password, others a UUID, while WireGuard uses keys, addresses, and peer settings. Do not reuse values from one protocol in another, or disable certificate validation just to get a connection through temporarily.
Connections such as VMess and VLESS may also depend on additional transport settings. Using the same address does not mean the path, Host, or Server Name can be omitted. If an imported connection times out, compare each field with the original details and check for missing parameters. The server must support the same combination; changing the protocol name in the client alone cannot convert the server.
Managing Subscriptions and Servers: Import, Select, and Update
Use Home to view servers and subscription groups and select the server to use. If you have individual server details, choose the type in Add Server and enter them. To import an existing QR code, use Scan QR Code and check the parsed details. If you already have a subscription link, select Subscribe in Add Server, enter the link and a label as prompted, then save and update the list.
A subscription provides batches of server entries; it is not a Config rules file. Updating a subscription typically refreshes the server list. It does not necessarily change the active Config, DNS, or Global Routing as expected. After importing, check that the group appears and its fields are complete, select the server you want to use, and then test the connection.
Use recognizable labels for manual entries and subscription groups. Manual edits to subscription-generated entries may be overwritten during a later refresh, so check who manages an entry before making lasting changes. If an update fails, first check whether your current network can reach the subscription URL and whether the link is still valid, then ask your service provider to verify it. Avoid repeatedly deleting groups, as you may lose older details needed for comparison.
Subscription URLs, QR codes, and server credentials can all grant access. Do not include full links in public screenshots, logs, or support requests. Keep any original details you may need before deleting a group. After replacing multiple servers, test them again using the same Test Method so you are not comparing results measured in different ways.
On Demand: Connect Automatically Based on Network Conditions
On Demand lets the system handle VPN connection requests according to conditions you set, reducing the need to switch manually each time. It does not check server health or fix invalid credentials. Find On Demand in the app's Settings and configure the network conditions available in the current interface. Get manual connections working first, then enable On Demand.
Before configuring it, decide which networks should trigger a connection and under what conditions it should stay inactive. Start by testing one condition. For Wi-Fi conditions, check the network name and matching scope carefully. After saving, switch between test networks, make a new request, and check whether the system VPN status and app display match your expectations. A toggle's color alone does not confirm that the conditions are working correctly.
If the connection keeps dropping and reconnecting, first check whether On Demand is still enabled. If you need to disable the connection temporarily, check the On Demand rules too. When switching between Wi-Fi and cellular, behavior may also depend on the current network, system permissions, and existing VPN configuration. Change one condition at a time and keep reproducible test notes.
Data: Review Traffic and Activity
Data shows traffic statistics recorded by the client. Use it to observe changes in uploads, downloads, and related statistics while connected. In Data, first identify the displayed scope, time period, and units, then perform a specific action—for example, open the same webpage—and compare the before-and-after values. Available breakdowns depend on the current interface.
An increase in traffic means data passed through the relevant statistics scope; it does not mean the destination page fully loaded or prove that a rule matched correctly. Background sync, media preloading, and app retries can also generate traffic. If the count keeps rising while an app is not open, check background activity before concluding that the server is at fault.
Client statistics and your service provider's billing may use different measurement scopes, reset times, and units, so the numbers may not match exactly. To keep troubleshooting evidence, note the time period and connection state before using the reset option in the interface. Data is not a complete record of all device network traffic and should not be used on its own to assess server speed.
Settings: DNS, Testing, Quick Access, and Sync
Settings brings together commonly used options. Check what each one does before changing it. Some behavior may also be controlled by the active Config, so record relevant settings in both Settings and Config while troubleshooting. Avoid changing DNS, the test method, and the server all at once; otherwise, it is hard to tell what caused the result.
DNS: Check the Resolution Path and Configuration Source
DNS resolves domain names to addresses. A resolution failure can make it seem as if the server is connected while the destination remains unreachable. Check DNS-related options in Settings and the active Config, and identify which source is actually in use before changing anything. The DNS server itself must also be reachable over the current network path; do not replace it just because its name looks familiar.
When testing, distinguish a DNS resolution failure from a connection failure to the destination, and check whether IPv4 and IPv6 results differ. If the configuration uses encrypted DNS transport, also verify the domain, certificate validation, and connection path. Keep the original settings and retry the same request after each change. Clearing all DNS settings is not a universal fix.
Test Method and Connectivity Test: Compare Results Consistently
Test Method determines how connection tests are performed. Select a method available in Settings, then return to Home and run Connectivity Test. Different methods measure different stages, so their results are not directly comparable. A failed test does not necessarily mean the server is completely unavailable; check actual access and logs too.
To compare servers, keep the network, test method, and test destination the same, and repeat tests at similar times. Lower latency does not guarantee faster sustained transfers, and a passing test does not mean every destination will work. If a test times out, follow the server timeout troubleshooting steps.
Today Widget: Set Up Quick Status and Actions
Today Widget provides quick access to related status or actions. First check the available Today Widget settings in Settings, then add the items currently offered for your device in the system's widget interface. Widget formats and available actions depend on system and app support; refer to the names and options shown on your device.
Quick access does not replace checking the full configuration. After using a widget, confirm the current server, Global Routing mode, and connection status in the app. To edit rules or investigate a failure, return to Home, Config, or Diagnostics rather than repeating the same quick action.
iCloud Sync: Keep a Local Copy First
iCloud sync shares app-supported data between eligible devices. Check the relevant option in Settings and make sure the system allows the app to use iCloud. Both devices need the appropriate iCloud account and permissions. Your App Store purchase account and iCloud sync account serve different purposes; do not confuse them.
Before enabling sync, save important Config files and necessary details, and review the sync scope shown in the current interface. Do not assume that every setting, statistic, or connection status will sync. Sync is not a historical backup; deletions and overwrites may propagate to other devices. After switching devices, confirm the data is complete before connecting, and avoid making extensive edits to the same Config on both devices at once.
Diagnostics: Troubleshoot with a Minimal Reproduction
Diagnostics collects information related to connection problems. Open the relevant option in Settings and check the items available in the interface. To reproduce a problem, note the network type, server, Global Routing mode, active Config, and time of the error, then repeat the failed action once. The current interface determines which logs are available.
When reviewing diagnostic information, first distinguish DNS errors, connection timeouts, authentication failures, and errors returned by the destination, then check the relevant settings. Before sharing diagnostics, remove subscription URLs, passwords, keys, and personally identifying information. Include only the details needed to resolve the problem. Turn off any extra logging you enabled temporarily once troubleshooting is complete.
Settings Checklist: From Connecting to Rule-Based Routing
Break setup into three stages: verify the server first, then rule-based routing, and finally automation and sync. Use the same test destination at each stage, and move on only after confirming the result. This helps avoid troubleshooting protocol, DNS, rules, and On Demand all at once.
- Check the basic network. First make sure the device itself has network access, and note whether it is on Wi-Fi or cellular. If the network requires sign-in, complete that step first.
- Check your existing server. Select the intended entry on Home and verify its protocol settings. Run Connectivity Test using the same Test Method, then confirm that you can reach the actual destination.
- Check the active Config. Select the intended profile in Config, set Global Routing to Config, and check the rule and policy that match the destination. Keep a copy of the profile that works.
- Add settings one at a time. Adjust DNS, On Demand, Today Widget, or iCloud sync as needed. Repeat the test after each change and note how the result differs from before.
- Verify with data. Use Data to observe changes in activity and Diagnostics to reproduce errors if needed. If a new setting causes a problem, restore the previous setting before deciding what to change next.
For first-time setup, follow the step-by-step guide. If you are connected but cannot reach a destination, use troubleshooting to investigate by symptom. Check the App Store purchase and compatibility guide for purchases, redownloads, and device compatibility; connection problems do not require buying the client again.