Settings · Official Manual

Shadowrocket Features and Common Settings

Choose a Global Routing mode first, then check the rules and server details before adjusting Settings. This guide explains what common features do, where to find them, how to configure them, and what to watch for on iPhone and iPad.

Shadowrocket is a paid client for Apple platforms and is available exclusively from the App Store. The one-time app purchase does not include a service plan. The instructions below assume you already have your own subscription or server details; no nodes or subscriptions are provided, sold, or recommended here. Check the App Store listing for system requirements.

Choose Global Routing first
Then check Config
Finally, test a real request

Global Routing

Three modes: Config, Proxy, and Direct

Global Routing determines how requests are routed; it does not fill in missing server details. Open Global Routing from Home to review the Config, Proxy, and Direct modes. Choose Config to route traffic by domain or address, Proxy to temporarily check the proxy path, or Direct to observe a direct connection. Note the original selection before making changes, and restore your usual mode when troubleshooting is done.

Mode	How it works	When to use it	Check first
Config	Applies policies based on the rules in the current configuration.	Everyday rule-based routing, proxying specific sites, and direct connections to the local network.	Whether the configuration is selected, rule order, and the fallback policy at the end.
Proxy	Routes requests handled by the client through the proxy.	Temporarily check whether an issue is related to rule selection.	Whether the selected server is valid and a proxy connection can be established.
Direct	Routes requests handled by the client directly.	Compare results on the local network and check whether the proxy path is causing the issue.	Whether the current network can connect directly to the destination.

Choosing Config as the mode is not enough: open the Config screen and confirm which configuration file is active. A successful import, a file being present, and a configuration being selected are three different states. If rule changes have no effect, check the active configuration first, then Global Routing. Avoid changing DNS, test methods, and server settings all at once.

New to Shadowrocket? Follow the setup guide to connect and verify your settings →

Config · Rule

Rules and routing: match first, then apply a policy

Rules define which requests match; policies define what happens after a match. View, import, or edit configurations in Config. To route traffic using a configuration, return to Home and set Global Routing to Config. Rules are generally evaluated from top to bottom, and the first match determines the result. Put more specific rules before broader rules that could take precedence.

Common rule types include DOMAIN for an exact domain match, DOMAIN-SUFFIX for a domain and its subdomains, DOMAIN-KEYWORD for matching a keyword in the domain, and IP-CIDR and IP-CIDR6 for IPv4 and IPv6 ranges. GEOIP checks the geographic location associated with an IP address; it does not indicate a site's language or the user's location. Whether an address rule matches also depends on the request details and how the address is resolved.

PROXY routes a request through the proxy, DIRECT connects directly, and REJECT blocks the request. These are policies, not match types. FINAL handles requests that did not match earlier rules and belongs at the end of the list. If it appears earlier, later rules may never get a chance to match.

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT
FINAL,DIRECT

This example means “send example.com and its subdomains through PROXY, send the specified local network range through DIRECT, and send everything else through DIRECT.” It is not a complete set of connection details. Keep a copy of the original configuration before editing. Afterward, make a request to a specific destination and check the connection log for the matching rule and policy. A webpage loading by itself does not reveal which route it took.

Learn more about rule keywords and match order →

Subscribe · Add Server

Managing existing subscriptions and servers

A subscription keeps a set of server details up to date; an individual server entry stores the settings for one connection. If you already have a subscription, use the Subscribe option in the Home screen’s add menu, enter the link, and save it. To add an existing individual server, choose Add Server and enter its address, port, authentication details, and other options for the relevant protocol. Available import methods depend on the options shown in the app. Do not enter different types of information into the same field.

Shadowsocks, VMess, VLESS, Trojan, and other protocols use different fields. A server address is not a subscription link, and a subscription name is not authentication information. When entering server details manually, check the protocol, port, password or identity, and any additional parameters such as TLS against the information you already have. A name is for identification; it does not correct connection settings.

After saving a subscription, update it and check that the expected server list appears. Select a server and run Connectivity Test. Updating checks whether the server details have refreshed; a connection test checks whether a destination is reachable under the current conditions. These are separate checks. If an update fails, first confirm that the link is complete, the service details are still valid, and the current network can access the subscription address.

If you edit a server created from a subscription, a later update may overwrite your changes. Keep custom details that need to persist separate from content that updates automatically. Before deleting a subscription, check what will be affected, including whether linked servers will also be removed. Subscription links may contain personal credentials. Redact them from screenshots, logs, or configurations before sharing, and never post a complete link publicly.

See how to import, select a server, and run the first connection test →

On Demand

On Demand: match connection behavior to network conditions

On Demand triggers or changes VPN connection behavior based on conditions; it does not replace domain-based routing rules. Find On Demand in Settings. Review the conditions and actions shown on your screen before enabling it. Available options may vary with the system and app state, so follow the instructions on your device.

First, confirm that the server and Config work with a manual connection. Then add one clear condition, save it, and connect to the relevant network to check the system VPN status and the result of a real request. For example, use On Demand to describe a network condition when you want connection behavior to change on certain networks. To send a specific website through DIRECT, change the rules in Config instead of trying to use a connection condition as a substitute for a site rule.

After enabling On Demand, manually disconnecting may seem to conflict with a condition that triggers a connection again. If the connection returns after you turn it off, check the On Demand conditions first rather than repeatedly deleting servers or resetting all settings. For troubleshooting, temporarily disable On Demand and test on a single network. Once the basic connection works, restore conditions one at a time.

On Demand still depends on system permissions, the current network, and valid server details; it cannot guarantee connectivity. Test both sides of a condition at least once: when it becomes active and when it no longer applies. Check that behavior is as expected when switching from Wi-Fi to cellular.

Data

Data usage: distinguish speed, transfer totals, and billed usage

Data shows traffic recorded by the client; it is not a substitute for service-side usage records. Open Data and check the reporting period, direction, and units before interpreting the numbers. They may represent uploads, downloads, total transferred data, or a transfer rate at a particular moment. A rate measures data transferred over time; a total is the sum over a reporting period. They are not directly comparable.

To check the stats, note the current numbers, make a recognizable request, then return to Data and see what changed. If the screen offers a reset option, save any records you need first. Resetting local stats does not reset service-side usage limits. Do not treat the app's transfer total as all network usage on the device; system and client stats may cover different traffic.

If local and service-side records differ, compare the reporting periods and units, check whether multiple devices are included, and account for protocol overhead. Use the current screen to determine whether direct and proxy traffic are counted separately and which breakdowns are shown. An increase in Data alone does not prove that a particular rule matched; check connection records and the request destination to verify the route.

For ongoing troubleshooting, record the time, network, server name, and Global Routing mode. This lets you relate changes in totals to specific actions instead of relying on a screenshot of a number without context.

DNS

DNS: check where settings take effect before changing resolution

DNS resolves domain names to addresses; successful resolution does not guarantee that the connection will succeed. Check the DNS-related options in Settings and whether the current Config file contains a [General] section and the dns-server parameter. Do not assume that all requests use the same resolution path based on a single value in one settings screen.

If your network is working and you have no specific reason to change DNS, leave the current resolution settings as they are. If a change is needed, back up the configuration and note the original value before entering a format accepted by the app. A configuration using dns-server = system refers to DNS settings provided by the system, but its behavior also depends on the active configuration and related DNS options. Compare differences between configurations item by item instead of replacing an entire section.

If an address is reachable but its domain will not load, check DNS resolution first. If the domain resolves but the connection times out, check the policy, server, and destination service. Do not attribute every failure to DNS. After making a change, reconnect and repeat the request. If needed, use the app's diagnostic options to check the result; a connection established before the change may lead to misleading conclusions.

Changing several DNS options at once makes issues harder to isolate. Change one variable at a time, then compare results for the same destination. If there is no improvement, restore the original value before checking the next option. Public networks may require a sign-in step first; rule that out before testing.

See the settings guide for DNS reference →

Settings

Test Method, Widget, and iCloud sync

Settings serve different purposes; do not treat every option as a way to improve connection speed. First decide whether you want to change the test method, what the system displays, or how data syncs. Then open the relevant setting. Options and availability depend on the current app interface; this guide does not prescribe one default for every device.

Test Method: keep test conditions consistent

Test Method determines how a connection test is run. Find Test Method in Settings, choose from the options shown, then return to Home and run Connectivity Test. If the screen also shows a test target or timeout, note those settings too. To compare a group of servers, keep the test method, target, network, and test time as consistent as possible.

A test result reflects one run using the selected method; it is not the same as sustained transfer speed. A failed test does not necessarily mean every real request will fail, and a successful test does not prove that every website is reachable. After selecting a server, test an actual destination and check which rule matched.

Today Widget: check settings in both the app and the system

Today Widget provides a quick view or action in system-supported locations. Check the related option in Settings, then use the system's widget editor to confirm that the widget has been added. Available widget formats, displayed information, and interactions depend on system support. Enabling an option in the app is not the same as adding a widget in the system.

If the widget does not appear, check the setting in the app first, then look in the system's widget list. If it shows information that does not reflect your latest action, open the app to confirm the current state. Before sharing a screen, check whether the widget displays personal information such as a server name. Do not rely on a single widget status to determine which route a request took.

iCloud: check what syncs before resolving conflicts

iCloud sync coordinates app data when supported; it does not restore every runtime state. First confirm in system settings that your Apple Account is signed in and iCloud is available. Then check the sync option and its description in Shadowrocket Settings. The data that syncs and when sync occurs depend on the current interface. Do not assume that every setting, statistic, or connection status will sync.

When enabling sync for the first time or resolving differences between devices, keep important configurations from each device and check the sync result. Avoid editing the same data on two devices at once and repeatedly toggling sync. Sync does not replace purchase records: to restore the app on a new device, find it in the App Store using the original purchasing account. See how to restore a previous purchase.

Diagnostics · Log

Diagnostics and logs: trace a single failed request

Diagnostics and logs provide clues; a single message in a record should not be treated as the definitive cause. Look for Diagnostics or a related Log option in Settings and check which checks and records are available on your screen. Enable the relevant options only when needed, reproduce the issue once, then restore the original settings.

Stay on the current network and note Global Routing, the active Config, and the selected server. Temporarily avoid automatic switching conditions.
Run Connectivity Test, then visit a specific destination. Note when the failure occurs and what happens.
Check records from the same time period. Review domain resolution, rule matching, policy selection, and connection setup in order.
Change only one setting supported by the evidence, then test the same destination again. Restore the original value if there is no improvement.

Logs may contain visited domains, server addresses, subscription details, or authentication information. Review and redact sensitive content before saving or sharing. Keep only the time, error description, and context needed to troubleshoot. Avoid recording all activity indefinitely or masking the original issue by repeatedly importing new configurations.

Use this page to understand features and their limits. For a step-by-step review of Settings, see the settings guide. For a specific symptom, visit Frequently Asked Questions or follow the troubleshooting steps for when the connection is on but nothing loads.