Official Guide · Features & Settings

Shadowrocket Proxy Modes

Choose a Global Routing mode first, then check Config and your server. Verify the connection toggle, the policy used for requests and actual access separately.

Choose a mode Rule matching Verify settings

The instructions below use the common iPhone / iPad interface as a reference. Menu locations and available settings may differ by platform; follow what you see in the app. Shadowrocket is available for iPhone / iPad, Mac (Apple silicon and Intel), Windows, Android and Linux. See downloads for all platforms.

Choose a mode

The three Global Routing modes

Config, Proxy and Direct are the corresponding interface options. The selected mode determines how requests are routed; it is separate from the connection toggle.

What it is: Global Routing is where you choose the overall routing mode. Find Global Routing on Home and check which option is selected. For initial setup, import your existing server details and confirm they work before choosing a mode for everyday use. Avoid changing your server, DNS and configuration file all at once just to try different options.

Interface option	How requests are handled	When to use it	What to check
Config	Routes requests according to the rules in the active configuration.	Everyday routing by domain, address or other criteria.	Check that the configuration is enabled and that rule order and policy references are correct.
Proxy	Routes traffic through the proxy path overall, subject to the app and platform’s capabilities.	A brief comparison test to see whether an issue is related to rule selection.	Check that the selected server connects and that the destination service is reachable.
Direct	Routes traffic directly overall.	Check the local network or run a temporary direct-connection comparison.	Check that the local network and destination service are working.

Choosing a mode and switching back

If you already have a verified rule configuration, start with Config. If a destination fails in Config but works through the same server in Proxy, review the rules and policies rather than immediately reimporting a subscription. If Direct also fails for a destination that should connect directly, check Wi-Fi, cellular data or the destination service first. Change one condition at a time and note the results. When testing is done, restore your preferred mode.

Keep in mind: Selecting Direct does not turn off the connection, and selecting Proxy does not guarantee that a destination service will be available. The system may still show a connection status. To check how a request was routed, review the request log rather than relying only on the system status icon. Also distinguish new requests from existing connections: after switching modes, try the destination again and check the result.

Match criteria and routing policies

Config and rule-based routing

Rule types define what matches; policies define what happens after a match. They are not interchangeable.

Understanding rule types

In Config, review the Rule section of the active configuration. DOMAIN matches an exact domain; DOMAIN-SUFFIX matches a domain suffix; DOMAIN-KEYWORD matches a keyword in a domain. IP-CIDR and IP-CIDR6 describe address ranges. GEOIP matches against geographic data associated with an IP address; results depend on the data and resolution process, so they do not guarantee where a website is based.

Whether USER-AGENT can match depends on whether the request contains the relevant information. Do not assume it is available for every connection. Before adding a rule, identify the domain or address the request actually uses; a displayed page name is not necessarily its request domain.

Understanding policies

DIRECT means connect directly, REJECT means block, and PROXY routes through the corresponding proxy policy. A configuration may also refer to custom policy names, which must match policies defined in that configuration. Adding a name at the end of a rule does not automatically create a usable server or policy.

When a rule matches incorrectly, first identify the rule that matched, then decide whether to change its match criteria or its policy. If REJECT matches the destination, switching servers usually will not change the result. If the rule references an unavailable policy, check that policy’s members and selection state.

Rule order and verification

The following is a rule syntax example, not a complete configuration and does not include server details. example.com illustrates suffix matching; use the destination you need to handle in your own configuration.

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

Rules are generally checked in order, and the first matching rule determines the policy for a request. Place specific rules before broader rules. Use FINAL as the fallback when nothing above matches. Before editing, keep a copy of a working configuration. In Config, confirm the new configuration is enabled, set Global Routing to Config, revisit the destination, then check the matched rule and policy in the request log.

Keep in mind: Updating a remote configuration may overwrite local changes. Maintain custom content you need to keep using the configuration management options available in the app. A successful save only confirms that the content was written; it does not mean the rule was selected or that a request to the destination used it.

Managing connection details

Managing subscriptions and servers

Subscribe manages the source used to update a group of servers; Add Server is for individual connection details. Config manages rules and related settings.

Importing and adding servers manually

What it is and where to find it: On Home, review your existing servers and groups, then use the add option to open Add Server. If you have a subscription link, use the Subscribe option supported by the app. For a single server, enter the details for its protocol. You can import a QR code with Scan QR Code, but first make sure it came from your provider.

How to set it up: Get subscription links from your provider. Preserve the full path, query parameters and capitalization, and check for spaces or line breaks before and after pasting. To add a server manually, select its protocol, then enter the server address, port and required authentication, transport and TLS settings. Shadowsocks, VMess, VLESS, Trojan, Hysteria2 and WireGuard use different fields; do not apply one protocol’s setup steps to another.

After importing, confirm that a server appears on Home. Select it, run Connectivity Test and try accessing a destination. A successful subscription import means the list was retrieved, not that every server in it works. Likewise, a Connectivity Test result does not guarantee access to every website; verify each separately.

Updating, renaming and removing entries

When subscription content changes, update that subscription and check whether the server count, groups or current selection have changed. If the update fails, first confirm that your local network can reach the subscription address. Then check whether the link has expired and whether its response is in a format the app can read. An error page, login page or ordinary webpage cannot be imported as a server subscription.

Keep in mind: Before bulk cleanup, distinguish subscription-generated entries from servers you added manually. Updating a subscription may rebuild the entries it manages, so avoid relying on temporary edits to automatically generated entries. Subscription URLs often contain access credentials. Redact the full URL and authentication fields in screenshots, logs and support requests; do not paste them into public comments or unnecessary diagnostic tools.

See the subscription import and first connection guide →

Connection triggers

On Demand connections

On Demand controls when a connection starts; Global Routing and rules control how requests are routed once it is active.

What it is and where to find it: On Demand starts a connection when specified conditions are met. In Settings, look for On Demand or the corresponding automatic connection options, then check the current conditions and toggle state. Available conditions vary by platform; do not assume that options shown on another device are available on yours.

How to set it up: First disable automatic triggers so they do not interfere. Connect manually and confirm that the server, DNS and rules work, then set your On Demand conditions. If the interface offers conditions for Wi-Fi, cellular data or specific networks, check when the connection should start and when it should not. After saving, switch networks in a controlled setting and confirm the connection behaves as expected. Then test the policy used for a request to your destination.

Keep in mind: On Demand does not fix server problems. If a manual connection already fails, enabling it will only run into the same issue again. If the connection starts automatically after you turn it off, check the On Demand conditions and relevant system connection settings before deleting a configuration. For troubleshooting, note the original conditions and pause automatic triggers; restore them when you are done so expected automatic connections are not mistaken for a fault.

Monitoring usage

Data usage statistics

Statistics help you monitor traffic recorded by the app; they are not a substitute for provider usage figures or your carrier bill.

What it is and where to find it: Open Data to view the traffic statistics available in the app. First check the scope and time period shown on the screen, then compare uploads, downloads or other categories. If a platform places this information elsewhere, follow the labels and guidance in the interface.

How to use it: To check whether an action generated traffic, note the current value, perform one specific action, then return to Data and check for a change. Before tracking usage over time, check whether counts persist across connections and whether a reset option is available and what it affects. Do not subtract figures with different scopes and treat the result as an exact usage figure for a particular app.

Keep in mind: Protocol overhead, retransmissions, reporting methods and billing periods can all cause discrepancies. An increase in Data only shows that the app recorded traffic; by itself, it does not prove that a particular web request went through a specific server. To check routing, review the request and policy. If you suspect unexpected background usage, compare it with the system’s per-app network usage and battery records.

Common settings, explained

Common Settings

Keep a working baseline. Adjust each setting separately and verify the result using the same destination.

DNS

What it is and where to find it: DNS resolves domain names to addresses. Related options may be in Settings or in the active Config. First check which configuration is in use and whether it defines DNS, so you do not change a global option while overlooking DNS settings in the configuration.

How to set it up and what to watch for: Start with the DNS setup that currently works. Switch to custom DNS or DNS over HTTPS only when you have a specific need. After making a change, request the same domain again and compare the resolution result, access and logs. The DNS over HTTPS endpoint must also be reachable; it will not fix incorrect rules, authentication details or an unavailable server. For more, see the DNS settings guide.

Test Method

What it is and where to find it: Test Method in Settings lets you choose how to test a connection. Each method checks a different part of the process. Interpret results in the context of the selected method rather than comparing a single number in isolation.

How to set it up and what to watch for: When comparing servers, keep the Test Method, test destination and local network consistent, then run Connectivity Test. A reachable port does not mean a complete proxy request will succeed, and access to the test destination does not guarantee access to others. If the test differs from your actual experience, check the method and destination first, then review the actual request log. Avoid changing every setting based on the test alone.

Today Widget

What it is and where to find it: Today Widget is a platform-provided shortcut for viewing or controlling the app. Look for the relevant option in Settings, then check the system’s widget management interface to see whether it can be added. Availability and appearance may vary by system version.

How to set it up and what to watch for: First select a server and verify the connection in the app, then configure the options actually available in the widget. Test a shortcut after adding it, then return to the app to check the current status. Widgets may refresh periodically, so a delayed update alone does not prove the connection failed. If the widget is missing, check whether your system and app version offer it.

iCloud sync

What it is and where to find it: iCloud settings relate to the app’s supported sync or backup features. Check the details in Settings, as well as your system’s iCloud permissions, account and available storage. Sync only covers the items explicitly listed by the app; do not assume all data will transfer.

How to set it up and what to watch for: Before enabling sync for the first time, keep a usable local copy of your configuration. Upload or sync from one device first, then check the content on another. If there is a conflict, identify which copy you want to keep before proceeding to avoid overwriting it repeatedly. Sync is not a guaranteed, ongoing backup, and deletions may propagate. Treat server credentials and subscription links as sensitive information.

Diagnostics

What it is and where to find it: Diagnostics provides supporting information for investigating connection and request issues. Open the relevant option in Settings, then check what the tool actually tests and what it reports. Do not treat one diagnostic result as a conclusion about your entire network.

How to use it: Note the destination, current Global Routing mode, selected server and network type, then reproduce the issue once. Check whether the problem is DNS resolution, a connection timeout, authentication or an unexpected policy selection, and adjust only the relevant part. If the same issue occurs on different networks, record each case separately rather than combining them into one diagnosis.

Keep in mind: Before exporting or sharing, check logs for server addresses, subscription links, authentication fields and personal browsing records. Share only what is necessary. For further troubleshooting, follow the troubleshooting guide for your symptoms; you do not need to publish your full configuration.

Verify your settings

Verify your configuration step by step

Check server availability, the selected mode and rule matches separately to avoid repeated changes.

Check your inputs. On Home, confirm that the server or subscription was imported and that protocol fields are complete. Do not rely on the entry name alone to verify the import.
Check the connection. Run Connectivity Test using the same Test Method, then try an actual request. If the test fails, first investigate the server, local network or authentication details.
Check the mode. In Global Routing, confirm whether Config, Proxy or Direct is the mode you intend to test. Restore your usual selection when testing is complete.
Check the configuration. When using Config, confirm the correct configuration is enabled and check rule order, policy references and the fallback behavior.
Check automatic behavior. Finally, restore On Demand and other automatic triggers, switch networks and test again to confirm automatic connections and routing behave as expected.

If a change causes a problem, restore the last working setting and test again, changing one variable at a time. To start with importing, read the first-time setup guide. If the connection works but specific destinations fail, start with the symptom-based troubleshooting guide. For app downloads and installation, use the downloads for all platforms page; changing rules will not resolve installation issues.