[Features]Official Guide · Features

Features and Common Settings

First distinguish traffic routing, server parameters, and system triggers; then adjust DNS and diagnostic options. Each setting has a different role. When a connection fails, change one variable at a time.

Global Routing Rules and Servers Settings and Diagnostics

This guide uses the iPhone / iPad interface labels. Menu layouts may differ on other platforms; refer to the labels shown in your version of the client.

[Routing]

The Three Global Routing Modes

What it does: Global Routing determines whether requests follow the rules in your configuration or use a single proxy or direct route. The three options correspond to Config, Proxy, and Direct in the interface. This setting is separate from server selection: choosing a server does not mean every request will use it.

Where to find it and how to use it: Open Global Routing from Home, then choose a mode for your needs. For everyday rule-based routing, select Config and confirm that the right configuration is enabled on the Config page. To check whether a saved server is reachable, temporarily switch to Proxy, then restore your original mode when testing is complete.

Mode How it works When to use it What to check
Config Applies the policies defined by the active configuration's rules. When you need to route traffic by domain, IP address, or region. Check the active configuration, rule order, and final policy.
Proxy Requests handled by the client generally use the current proxy. Temporarily check whether a routing rule is causing the issue. Check the selected server, protocol settings, and network reachability.
Direct Requests handled by the client generally use a direct connection. Compare access over your local network. Direct does not mean the system VPN connection is turned off.

Keep in mind: System traffic exclusions, LAN bypass settings, and platform-specific limitations can affect the actual route. Do not assume Proxy sends every packet from your device through a remote server. If the same destination works in Proxy but fails in Config, check which rule matches before rebuilding the server entry.

[Rule]

Rule Types and Policies

What they do: Rules combine a matching condition with a policy. Domain suffixes, domain keywords, IP ranges, and region databases each serve a different purpose. Rules are generally checked in configuration order, and the first match determines how traffic is handled. PROXY, DIRECT, and REJECT are policy keywords, not server protocols.

Where to find them and how to use them: Open Config, confirm the active configuration, then review or edit its [Rule] section. Put specific, narrow exceptions before broader rules, and check FINAL at the end of the configuration. The examples below illustrate rule syntax only; example domains do not represent real services, and no connectable servers are provided.

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
DOMAIN-KEYWORD,example,PROXY
IP-CIDR,192.168.0.0/16,DIRECT
GEOIP,CN,DIRECT
FINAL,PROXY
KeywordMatchesWhat to watch for
DOMAINThe exact domain specified.Does not automatically include other subdomains.
DOMAIN-SUFFIXThe specified domain and its subdomains.Useful for routing an entire domain family the same way.
DOMAIN-KEYWORDA keyword found in a domain name.Can match broadly, including targets with similar names.
IP-CIDR / IP-CIDR6An IPv4 / IPv6 address range.Check the range and the actual destination address of the request.
GEOIPThe region associated with an IP address.Results depend on the database and the destination address.
FINALRequests not matched by an earlier rule.Usually placed at the end of the rules to avoid overriding those that follow.

Keep in mind: DIRECT connects directly, PROXY applies the relevant proxy policy, and REJECT denies matching requests. Rules cannot supply missing server credentials. After adding a rule, make a new request to the destination and check the logs; existing long-lived connections may continue using their previous route. For a full explanation of the settings, see the Settings Reference.

[Server]

Managing Subscriptions and Servers

What they are: A server entry stores its address, port, protocol, and authentication settings. A subscription uses a link you already have to retrieve and update multiple entries. Server subscriptions and rule configurations are different things: updating a server list does not necessarily change the routing rules in Config.

Where to find them and how to use them: From Home, use Add Server to add a server you already have. If you have a subscription link, choose the appropriate Subscribe option and paste the full address provided by your service provider. If you have a QR code, use Scan QR Code. After importing, confirm the entry appears, select a server, run Connectivity Test, then turn on the connection and test access.

Check Fields by Protocol

When adding a server manually, select the right protocol first, then enter its address and port. For Shadowsocks, check the encryption method and password; for VMess and VLESS, check the identity parameters and transport settings; for Trojan, check the password, TLS, and SNI. For HTTP, SOCKS5, WireGuard, and Hysteria2, use the complete parameters provided for that server. Do not assume similar-looking fields are interchangeable across protocols.

Keep in mind: A subscription update may replace entries or remove those deleted by its provider, so manual changes may not persist. Keep important settings somewhere safe. Before sharing logs or screenshots, hide subscription links, credentials, and QR codes. A successful reachability test does not guarantee that every destination will work; also check TLS, DNS, and the active rules. For your first import, follow the Quick Start.

[On Demand]

Connect Automatically Based on Conditions

What it does: On Demand uses the system's on-demand mechanism to start a connection when specified conditions are met. It controls when a connection starts; Global Routing and rules control how requests are handled after connection. Treat these as separate settings.

Where to find it and how to use it: Find the On Demand options in Settings and review the available network conditions and triggers. First confirm that a manual connection works, then set conditions for Wi-Fi or cellular as needed. If a condition uses a Wi-Fi network name, check the exact name to avoid confusing a guest network or another network with the one you intended.

Keep in mind: After changing the settings, test what happens when you join a network, leave it, and reconnect after disconnecting. If the connection starts again immediately after you turn it off manually, first check whether an On Demand condition is still met; do not repeatedly remove the system configuration. On-demand connections cannot fix incorrect server settings or guarantee that existing connections survive a network change. For troubleshooting, temporarily disable the conditions and connect manually, then restore them when testing is done.

[Data]

Traffic Statistics and What They Show

What it does: Data shows traffic information recorded by the client, including upload, download, and any available breakdowns. It reflects traffic the client can record; it is not an ISP bill or a direct measure of the remaining allowance on a subscription service.

Where to find it and how to use it: Open Data and check the scope, time range, and categories actually shown. Then observe a repeatable browsing activity. To compare behavior before and after a change, keep the network, destination, and usage conditions as consistent as possible. If you need to start a fresh record, first check what the reset action affects and save any information you need.

Keep in mind: Background tasks, system traffic, connection reuse, and the start and end times of a measurement can all affect the numbers. An increase in download traffic only shows that data was transferred within the measurement scope; it does not confirm that a request matched the intended rule. To check a specific traffic route, consider the request log, destination domain, selected mode, and policy—not just the total.

[Settings]

Common Settings Explained

Options in Settings affect behavior such as DNS resolution, testing, shortcuts, and data syncing. Menus may be grouped differently across platforms and client versions. If you are unsure what an option does, leave it as is rather than copying settings from a screenshot of another device. No fixed defaults are specified below; refer to the current interface, active configuration, and network conditions.

DNS: Check What Handles Name Resolution

Purpose and location: DNS resolves domain names to IP addresses. Resolution behavior may be affected by DNS options in Settings or by the [General] section of Config. When checking DNS, open the active configuration and compare it with the client's current DNS settings; do not check only one place.

Setup and notes: Start with the current DNS method as a baseline. Change it only when you can identify a resolution failure, an unexpected address, or a specific network compatibility issue. In a configuration, dns-server = system means to use the system DNS. After a change, make a new test request and account for caching and existing connections. Working DNS does not confirm that server authentication is valid, and encrypted DNS does not mean application traffic necessarily uses a proxy.

Test Method: Know What the Test Measures

Purpose and location: Find Test Method in Settings. It determines how availability tests are performed. Depending on the method, a test may check network-level reachability or go on to contact a test destination. Interpret the result in light of the selected method.

Setup and notes: Use the same test method when comparing servers, and check which test destinations the interface lets you set. If one method fails while actual access works, first check whether the test destination is unreachable or unresponsive. Treat Connectivity Test as a diagnostic aid: after a passing test, verify the actual request too. A single test result cannot establish long-term connection quality.

Today Widget: Quick Access at a Glance

Purpose and location: Today Widget settings configure quick-view or control options supported by the system. Check the available options in Settings, then add the widget wherever the system allows. Available features depend on the system and the current client version.

Setup and notes: After adding the widget, check what it displays and confirm that its controls match the app's current state. System refresh timing may delay updates. If you are unsure of the connection status, check Home rather than repeatedly toggling the widget based on an outdated status.

iCloud: Check What Actually Syncs

Purpose and location: Look for iCloud sync options in Settings and confirm that iCloud permissions in the system allow Shadowrocket to use iCloud. Sync can keep supported data consistent across devices signed in to the same account; it does not necessarily copy every aspect of the app's state.

Setup and notes: Before moving to a new device, confirm that syncing has finished on the original device and save important configuration files separately. On the new device, sign in to the same iCloud account and check servers, subscriptions, and the active configuration individually. System connection permissions must still be confirmed on the new device. Sync may be delayed and can propagate deletions, so do not treat it as a separate historical backup. For sensitive configurations, also review access to the device and account.

[Diagnostics]

Using Diagnostics and Logs

What they do: Diagnostics and related logging options collect clues about connection attempts to help distinguish DNS resolution, server connectivity, authentication, and rule-matching issues. Logs do not repair a connection, and there is no need to collect more than necessary when you cannot reproduce a specific problem.

Where to find them and how to use them: Look for Diagnostics or the available log options in Settings. Note the network type, selected server, and Global Routing mode, then enable the logs you need and retry a failed request once. Check whether the destination is correct and whether the log shows a resolution error, connection failure, or authentication issue. Use those clues to identify the failing step.

Keep in mind: Reproduce one issue at a time so that background requests do not obscure the evidence. Before sharing logs, remove subscription links, passwords, identity parameters, personal domains, and irrelevant browsing records. Restore an appropriate log level when finished. If the issue occurs only on one Wi-Fi network, retest on another network with the same configuration. If it occurs only in Config, check the rules before relaxing TLS checks.

[Verify]

Check Settings in Dependency Order

Features depend on one another: valid server details provide the connection, the right configuration determines routing, DNS determines how domain names resolve, and On Demand only triggers the connection. Changing several layers at once makes problems harder to reproduce and makes it harder to restore the original settings.

  1. Check the inputs first. Confirm that an existing subscription can update, or that a manually added server has the correct protocol, address, port, and complete authentication details. Do not try to compensate for missing parameters by changing rules.
  2. Then verify the basic connection. Select a server, run a test on the current network, and try an actual request. If needed, temporarily use Proxy to narrow down the cause, then restore the original mode.
  3. Next, check routing. Switch to Config, confirm the active configuration, rule order, and FINAL, then retry the same destination and check which rule matched.
  4. Add automation last. Once a manual connection is stable, enable On Demand, widgets, and syncing as needed. Verify each change independently and keep a way to roll it back.

If you still cannot identify the issue, troubleshoot by symptom in Frequently Asked Questions. For details on how settings affect one another, see the Settings Reference. Note the network, mode, and destination where the failure occurs; this is usually more useful than changing several settings at once.