Shadowrocket Guide · Features & Settings

Shadowrocket Features & Settings

Start with the routing mode, then check your servers, configuration, and DNS settings. This guide focuses on iPhone and iPad and covers common features by explaining what they do, where to find them, how to configure them, and what to watch for. Available options and interface locations may vary. Check the App Store listing for system requirements.

Most routine use does not require changing several options at once. First use your existing server details to establish a connection, then choose the Global Routing mode that fits your needs. Change one setting at a time and note its original value so you can distinguish server, rule, DNS, and local network issues if something stops working.

View the first connection guide How to verify and get the official app →

Global Routing: Config, Proxy, and Direct

Global Routing determines how connections are routed. Find it in Home, then choose Config, Proxy, or Direct. These modes correspond to configuration-based routing, proxy routing, and direct connections. They are not three servers and do not replace a server's address, authentication, or protocol settings.

Mode What it does When to use it What to check
Config mode Uses the rules in the currently active configuration to determine how traffic is handled. When you need traffic routed according to domains, addresses, or other matching criteria. Check that the intended configuration is selected and that the policies referenced by its rules are valid.
Proxy mode Routes traffic through the proxy; the exact behavior may still depend on related settings. As a temporary check to see whether an issue is related to routing rules in the configuration. Check whether the selected server connects and the proxy route is available.
Direct mode Connects directly without forwarding traffic through the selected proxy server. To compare access over your local network. Check whether your local network and DNS are working and whether the destination is directly reachable.

Choosing a Mode and Verifying It

If you need rule-based routing, first confirm the active file in Config, then set Global Routing to Config. If a destination is unreachable, temporarily switch to Proxy and compare the result for the same destination. If Proxy works but Config does not, check rule matching and policy targets before changing all your server settings.

Direct is useful for comparing local network access, but it is not the same as turning off the system VPN. To check whether the connection is off, look at the connection switch in Home and the system status. Restore your original mode after testing so a temporary troubleshooting setting does not become your everyday setup.

Rules & Routing: Match First, Then Apply a Policy

A rule consists of fields such as match type, match value, and policy. It describes how to handle a type of connection; it is not a set of server connection details. Open the active configuration in Config and check its [Rule] section. Keep a recoverable copy before editing, and confirm the edited configuration is active when you are done.

Rule Types and What They Match

DOMAIN matches an exact domain; DOMAIN-SUFFIX matches a domain suffix; and DOMAIN-KEYWORD checks for a keyword in the domain. These match different scopes. For a domain-related issue, first decide whether you need an exact match or one that includes subdomains, then choose the appropriate rule. Do not enter a full URL path as though it were a domain.

IP-CIDR and IP-CIDR6 specify IPv4 and IPv6 address ranges, respectively. GEOIP matches against an address database, so results depend on the database and the resolved address. USER-AGENT matches a corresponding field when it is visible in a request; it should not be assumed to cover every app connection. Whether a rule can evaluate a request depends on the information available at the time.

Policies and Rule Order

DIRECT means connect directly, PROXY applies a proxy policy, and REJECT blocks matching connections. A configuration may also refer to custom policy names, which must match definitions that actually exist in the file. Rules are generally evaluated in order, so put more specific rules before broader ones. FINAL handles connections that did not match any preceding rule.

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

This section explains syntax and ordering; it is not a complete configuration. The example domain is for documentation purposes. After adding a rule, test it with a new connection to the relevant domain. Existing long-lived connections may not switch routes immediately after a change. To reconnect, end the test request and start a new one.

See rule keywords and policy terminology →

Config: Configuration Files and What Takes Effect

Config is where you manage configuration files. A configuration may include general settings, DNS, rules, and policy definitions, so it can affect more than a single routing rule. Having a server in the list does not mean a configuration is enabled. Likewise, saving edits to a configuration does not mean the current routing mode will use that file.

Before Selecting a Configuration

  1. Open Config and check the source and contents of the file you plan to use. Use only configurations whose purpose you understand and whose source you trust.
  2. Keep a copy of your current working configuration, then check the new file's policy names, rule order, and DNS settings.
  3. Select the configuration to activate, return to Home, and check that Global Routing is set to Config.
  4. Test with a new connection to a specific destination. If something goes wrong, restore your copy and compare the differences one at a time.

A remote configuration may overwrite local changes when it updates. Before making custom content permanent, understand how the file is updated and choose an appropriate way to maintain it. Do not copy every option from an unfamiliar configuration into your everyday setup. Check the purpose and scope of settings involving certificates, request handling, or DNS resolution separately.

Subscriptions and Server Management

The server list in Home lets you select a connection endpoint. Each server entry includes details such as protocol, address, port, and authentication. Subscribe updates a group of servers using an existing subscription URL. Imported content should come from your own service details, and its settings must match the server.

Add Server: Add and Verify a Server Manually

In Home, open Add Server, choose the correct protocol, then enter the address, port, and authentication details. Shadowsocks, VMess, VLESS, Trojan, HTTP, SOCKS5, WireGuard, and Hysteria2 use different settings; a server name alone does not tell you which protocol to choose. If your service details include fields such as TLS, transport, or server name, enter each one in the corresponding field. Avoid randomly toggling options in the hope of finding a combination that works.

After saving, return to the list, select the server, and run Connectivity Test before making a real connection request. A passing test only confirms a response under those test conditions; it does not guarantee that every destination, protocol, or sustained transfer will work. A failed test should also be considered in light of your local network and the test method.

Subscribe: Import, Update, and Delete

To import a subscription you already have, select Subscribe in Add Server, enter your subscription URL, and save. After updating, check that the group and server entries appear, then test one of them. If the subscription fails, verify the full URL, subscription status, and whether your current network can reach it. Avoid repeatedly importing the same content.

A subscription update may recreate server entries, so avoid keeping important manual changes only in subscription-managed entries. Deleting a server has a different effect from deleting an entire subscription. Before removing anything, verify which item is selected and note the group you are using. Subscription URLs often contain credentials, so redact the full URL and authentication details in screenshots, logs, and backups.

Troubleshoot subscription update failures →

On Demand: Trigger Connections Automatically

On Demand triggers connection behavior based on configured network conditions. It controls when a connection is established, not which policy a domain uses; that is handled by Global Routing and configuration rules. Look for On Demand in Settings. Available conditions and menu locations depend on the current interface.

Configure and Test

First turn off automatic triggers and manually verify that the current server and configuration connect successfully. Then open On Demand and set the conditions you need. If the interface offers options for network types or specific networks, enable only those you need. Save and test under the relevant network conditions. Check the connection state before and after the trigger, and keep the setting only if it behaves as expected.

Automatic connection does not guarantee recovery from server failures. Network changes, system scheduling, and server status can all affect connection setup. If the app reconnects automatically after you turn it off, check On Demand before assuming the connection switch is not working. For troubleshooting, disable automatic triggers temporarily, test manually, then restore your usual settings.

Data: Review Traffic Statistics

Data shows traffic recorded by the client. Check the displayed statistics and time ranges before comparing upload and download data. Cumulative totals and current rates are different metrics: the total over a period does not represent the current connection speed.

Using Statistics to Help Diagnose Issues

To monitor a single activity, note the current readings, perform one specific action such as opening a page, then return to Data to check for a change. Avoid running system updates, cloud sync, or other high-traffic tasks at the same time; otherwise, you cannot attribute the change to one action. Before using a reset function, save any readings you need and confirm what the reset covers.

Client statistics and service-side billing may use different time periods, traffic calculations, and methods for accounting for protocol overhead, so the numbers may not match. Use Data to observe trends and identify unusual activity, not as a replacement for service-side usage records or as the sole way to tell whether a subscription has expired. If the connection is on but the data is not changing, check actual requests and diagnostic information.

Settings: Common Options and What to Change

Settings includes options for DNS, testing, shortcuts, sync, and diagnostics. Some behavior may also be controlled by the active configuration file. Before making changes, distinguish app settings from configuration-file parameters, note the original values, and confirm which setting is active. This helps avoid making the same change in both places and losing track of what caused the result.

DNS: Check the Resolution Path First

DNS translates domain names into addresses used to connect. Check DNS options in Settings and see whether Config already contains DNS settings. If a domain is unreachable, compare behavior across destinations and local networks, then check the resolved address and connection path. Not every connection failure is caused by DNS.

If you need to make a change, adjust one DNS option at a time and retest the same destination, bearing in mind that cached results may affect the outcome. The selected DNS service must be reachable over the current route. Changing DNS will not fix an incorrect server password, an expired subscription, or a transport connection that cannot be established. Local network names and public domains may also require different DNS handling, so test each after making a change.

Test Method: Know What the Test Measures

Test Method determines how connectivity tests are performed; look for it in Settings. Different methods test different parts of the connection path, so their results should not be ranked as if they measured the same thing. Choose a method that fits your troubleshooting goal, then run Connectivity Test in Home. Compare results using the same method on the same network.

A shorter test time does not mean faster sustained transfers. If a test gets a response but the destination is still unreachable in practice, check the destination, rules, DNS, and transport settings. If only one test method fails, first confirm that its test conditions are met rather than deleting the server immediately.

Today Widget: Shortcuts and Status Checks

Today Widget provides related shortcuts or information. Check its available options in Settings, then add it in a location supported by the system. Available features and display options depend on the device's interface.

After setting it up, try a manual action, then return to Home to check the selected server and connection status. A shortcut only makes an action quicker; it does not replace server configuration. Do not rely solely on a display that may not have refreshed yet.

iCloud Sync: Keep a Copy Before Syncing

iCloud sync can sync app-supported content across eligible devices. Check the relevant options in Settings, along with your system's iCloud status and app permissions. Before enabling sync, keep any necessary copies on each device and decide which device's content to use as the starting point for organizing.

Do not assume sync includes all statistics, system permissions, or temporary connection states. Refer to the current interface for details on what is synced and how. Editing on two devices at once can make changes difficult to track. Organize content on one device first, confirm it appears as expected on the other, and then continue. Restoring the app after changing devices and syncing configuration are separate tasks.

Diagnostics: Collect Information to Troubleshoot Issues

Diagnostics helps investigate problems; look for it in Settings. Note the network type, routing mode, destination, and steps involved when the issue occurs, then use the diagnostic tools available in the interface. Reproduce one issue at a time so you can match the diagnostic record to what happened.

When organizing diagnostic records, keep the error category, sequence of events, and relevant setting names, but redact subscription URLs, authentication details, personal domains, and network identifiers. Diagnostic output helps explain the connection process; it does not mean you should change every setting shown. After testing, restore any logging options enabled only for troubleshooting.

Recommended Settings Check Order: From Connection to Automation

Checking the basic connection, routing, and automation separately is usually more effective than changing several settings at once. Use the following order when validating a new configuration or investigating an issue after making changes.

  1. Verify the server details. Check the selected entry in Home, its protocol, and its authentication settings. For subscription-imported entries, also confirm that the most recent update succeeded.
  2. Verify the routing mode. Note the current Global Routing value. To troubleshoot rules, compare modes using the same destination, then restore the original value after testing.
  3. Verify the active configuration. Open Config and check the file, policy names, and rule order. Do not just check whether the file you edited was saved.
  4. Check DNS and the actual request. Distinguish DNS resolution issues from connection setup and destination response issues. Do not use a single test duration to judge the entire connection path.
  5. Review Data and run diagnostics if needed. Use one clearly defined visit as a test case and interpret the results alongside Diagnostics records. A difference in statistics does not by itself indicate a billing problem.
  6. Enable automation and sync last. Once manual connections are stable, test On Demand, shortcuts, and iCloud sync one at a time. Keep a recoverable copy of your configuration.

If an issue occurs only on a particular local network, keep the same server and configuration and compare network conditions. If it occurs only in Config mode, check the rules first. Narrowing down one variable at a time helps avoid unrelated changes and makes it easier to document where the issue occurs.

View connection troubleshooting Q&A See interface and protocol terms →