Shadowrocket Settings Guide

01 · Current Settings values and Global Routing

Tap Settings at the bottom of Shadowrocket, review the list sections and item names, then open the relevant details. The location and availability of settings depend on the current app interface. If an option is not shown, do not treat a similarly named item as a substitute. Home is where you select a server and connect; Config handles configuration files and their rules; Settings brings together app behavior and utility options. All three can affect a connection, but they control different layers, so check and record them separately when troubleshooting.

Establish a restorable baseline before making changes

First note whether you are on Wi-Fi or cellular, which server is selected in Home, the current Global Routing mode, and the name of the active file in Config. Then record the setting you plan to change, its original value, and the outcome you expect. For example, “the connection should not start automatically after I reconnect to this Wi-Fi network” is more useful than “make the network faster.” Record automatic, blank, or inherited values exactly as shown. A blank value does not necessarily mean the setting is off; it may defer to a configuration file or the system.

“Default” can refer to three different sources: the value initially provided by the app, a value specified in an imported configuration file, or a value you saved earlier that may have synced. The current interface alone cannot tell you which applies. For settings that cannot be verified consistently across devices, this guide recommends keeping the current working value; it does not claim that one port, test address, or toggle state suits every device. This helps preserve existing requirements and makes it easier to relate each change to its actual result.

The three Global Routing modes

Check Global Routing in Home. Config, Proxy, and Direct correspond to configuration-based routing, proxy routing, and direct routing. Config applies the strategies in the active configuration file. Proxy can help determine whether an issue is related to routing choices. Direct lets you check access without the selected proxy server. These are routing modes, not connection-quality ratings, and they cannot make incorrect server details work. After a comparison test, restore the mode you normally need so a temporary diagnostic setting is not left in place.

Change one thing at a time to explain each result

Change one variable at a time, then repeat the same request. If you change DNS, the server, and Global Routing together, you will not know which change helped, even if the page starts working. Test with a newly opened page or a new connection; content that is already loaded is not enough. Browser caches, existing connections, and background app state can hide changes. If a change applies only to new sessions, stop and restart the connection, then confirm that Home still shows the intended selection.

The system VPN configuration authorization required for a first connection is separate from the proxy rules in a Config file. System authorization allows the app to establish the relevant network connection; it does not confirm that server details are correct or that a subscription has been imported. If the toggle turns on but the page is still unavailable, follow the first connection checklist to verify your selection and test steps. For advanced toggles without a clear purpose, keep the current setting. A change is manageable only when you know the original value, why you changed it, and how to restore it.

02 · DNS: Resolution source, configuration scope, and troubleshooting

Check DNS-related items in Settings, then open the active configuration file in Config and look for DNS settings. Use the interface as shown; different entry points may control resolution behavior and configuration content separately. DNS resolves a domain name to an address. Only afterward does the connection proceed to its destination, follow a route, and complete the higher-level request. A successful lookup and a working webpage are two different results; one does not prove the other.

First identify where the setting comes from

A configuration file can specify DNS servers in its General section. The snippet below shows how to use the system DNS source; it is not a universal default or a recommendation to replace your existing file. First check whether the current file already contains the relevant entry. Adding the same parameter twice makes maintenance and troubleshooting harder. If the file is updated from a remote source, manual edits may be replaced by a later update. Save a separate copy before deciding which file to use day to day.

[General]
# Example for learning: use the system DNS source; this is not a default value
dns-server = system

[Rule]
# Send the example domain through PROXY
DOMAIN-SUFFIX,example.com,PROXY
# Send private address ranges through DIRECT
IP-CIDR,192.168.0.0/16,DIRECT
# Send other requests through PROXY
FINAL,PROXY

Do not assume that a setting being editable in the interface means it overrides everything in Config. If the interface explains inheritance or scope, follow that guidance. If the scope is unclear, test one variable at a time in a copy of the current configuration and inspect the request log. There is no single recommended DNS address: use a source that works for your network and configuration, and confirm it with repeat tests. If resolution already works, there is no need to change everything to chase an abstract metric.

Separate resolution issues from connection issues

For diagnosis, choose a domain you can normally access. Record whether it resolves, then check whether the connection times out. If no domains resolve, check the current network, whether the DNS source is reachable, and whether the configuration entry is correct. If only one domain has a problem, consider its DNS records, cache, or domain-specific rules. If resolution succeeds but the connection fails, continue by checking the selected server, destination service, and route. Do not keep changing DNS to fix a problem that is not at the resolution layer.

Some rules rely on domain information; others match the destination address. A resolved domain may return multiple addresses, and a page load may involve several domains, so different strategies within one page load do not necessarily mean a setting has failed. Compare the domain, destination address, and matched rule for the same new request rather than looking only at the page name. For IPv6, first check whether the current network and destination support it, then inspect the relevant DNS results and address rules. Disabling an address type should not be the default first step.

Caching, network changes, and recommended practice

After changing the DNS source, an old cache entry or an existing connection may still be used. End the old request, reconnect if needed, and then open a new page. If the interface provides a cache-clearing tool, use it as directed. Do not delete the entire configuration to fix one domain. Switching between Wi-Fi and cellular can change the DNS source provided by the system and its reachability, so results on one network do not necessarily apply to the other. Always include the network environment in your test notes.

If your DNS method requires an additional connection step, consider how the DNS service itself is reached. If you need to resolve a domain before you can access the service that provides resolution, the initial lookup can become more complicated. When a timeout occurs, check that dependency rather than looking only at the destination site. Start with a simple, verified working configuration and add options only when needed. To restore, reinstate the original DNS entries, reconnect, and check for duplicate configuration elsewhere before deciding whether the issue is back to its original state.

03 · On Demand: Conditions and manual connections

Open On Demand in Settings. Check the master toggle first, then review the network conditions and actions for the current configuration. On Demand manages connection behavior based on conditions; it does not speed up a server or fill in missing server details. Before setting it up, confirm that the same server works when connected manually. Otherwise, an automatic-connection issue and a server problem can overlap, making the cause difficult to identify.

Define the condition before choosing an action

Common conditions relate to the network, such as Wi-Fi, a specific SSID, or cellular. Use only the options shown in the current interface, and check the match and action for each one. Do not assume that “include a network” means “exclude every other network.” An SSID is a Wi-Fi network name, not a server name. Check capitalization, spaces, and the full name shown on the device. If different networks have the same name, the name alone cannot distinguish every situation, so continue to check the connection manually.

Start with one condition that is easy to verify. For example, check whether the expected action occurs when switching from cellular to a frequently used Wi-Fi network, then add another condition after that works. Multiple overlapping conditions make unexpected connections harder to trace. Do not assume that every list item runs cumulatively in the order you expect. Read the current interface guidance, establish the priority, and test by switching networks. Do not guess at behavior the interface does not explain.

Why does the connection return after I stop it?

If the connection returns after you stop it manually, check for an applicable On Demand condition before repeatedly removing the system VPN configuration. The system can respond to a new network request based on enabled On Demand conditions, so stopping a connection once is not the same as disabling automatic triggers. To troubleshoot with manual control temporarily, disable On Demand first, then stop the connection and check whether a new request still triggers it. Restore the original conditions when you are done.

Network switching does not happen instantly. The device may lose the old connection, obtain an address and DNS information, and then establish a new connection. Brief unavailability during this transition does not by itself mean the conditions are wrong. Wait until Wi-Fi or cellular is stable, then make a new request and check that Home still shows the intended server. On Demand controls when a connection is triggered; it should not be mistaken for a mechanism that automatically selects a different server every time the network changes.

Lock screen, background activity, and recovery checks

Lock-screen and background behavior depends on system scheduling and network conditions. Do not use whether the app remains visible in the foreground as the sole indicator of a connection. If the issue occurs only after the device has been locked for a long time, record the network, connection state, and first new request after unlocking, then compare those details with a normal network-switch test. Avoid rapidly toggling settings to observe background behavior; this adds state changes and makes the trigger sequence harder to understand. Allow time for the network to stabilize and the request to finish.

This guide does not treat the On Demand toggle you see now as a universal initial value for a fresh installation, since the device may retain an existing configuration. If you do not need automatic connections, manual control is the recommended approach. If you do, use the fewest conditions needed for clearly defined situations, and record how to disable them. If an unexpected action occurs, first turn off the master toggle and confirm that manual connections work, then restore conditions one at a time. A clear rollback path is more reliable than adding many exceptions and looking for conflicts later.

04 · Ping and Connectivity Test: Test targets and what results mean

Check the Ping-related settings in Settings to confirm the available test method and target, then return to Home to review the results for the server list. Use the options shown in the current app; a single number does not reveal which test was used. Ping is often used as shorthand for a latency test, but different methods may measure different stages: some check address reachability, some test a port connection, and others include a request to a specified target. Do not compare results as if they measured the same thing.

What the numbers tell you

A test describes only part of the performance at that moment, on the current network, using the current method. The target, DNS, protocol handshake, and server response can all affect the result. A lower number does not guarantee faster page loads, and a higher number does not necessarily mean the connection is unusable. If a probe gets no response but the page opens normally, consider whether that test method is appropriate for the target. Conversely, a successful port connection does not prove that authentication, the higher-level protocol, or the final request will work.

Before changing test parameters, record the original method and target so you do not compare old and new results as if they came from the same test. If you enter a test target yourself, choose an address that remains accessible and suits the test method. Do not use a subscription URL as the target or enter a link containing access credentials. A test address is for a probe, not for importing a server. Keep the current timeout unless there is a clear reason to change it: a very short timeout may treat normal variation as failure, while a long one extends the wait when there is no response.

Cross-check list tests against real requests

In Home, check the selection mark beside the intended server, connect, and run Connectivity Test. After the test, make a new request to a page you actually need. This distinguishes three things: a response from the server-list probe, completion of the app's test, and availability of the destination service. If you check only the list result without selecting a server, the next request may use a different one. A system VPN indicator alone also cannot confirm that the higher-level request completed.

To compare two existing servers, keep the network, test method, and target the same, and test as close together in time as possible. Do not switch to cellular and change the test address at the same time, then attribute the result to the server. If results fluctuate significantly, repeat a small number of tests and check whether they complete consistently rather than keeping only the best result. See the guide to evaluating latency, region, and protocol type for more on the difference between a number and real-world performance.

Set a recommended test baseline

This guide does not prescribe one test target or timeout for every device, and it does not call the current saved value the app default. Choose a method that answers a real question. To assess the final webpage request, include an actual visit in your verification rather than stopping at an earlier connection stage. Keeping a consistent test baseline helps identify network changes; frequently changing targets makes historical results harder to compare.

If Connectivity Test results conflict with what happens on a webpage, check whether they use the same route, access the same domains, and whether the test target responds. A target that is down for maintenance or temporarily unavailable does not mean all access has failed. To restore the baseline, put back the original method and target, select the server again, and repeat the same request. Recording the time, network, method, target, and result is more useful than saving a latency number alone.

05 · Logs and Data: Use request records to troubleshoot settings

Check log-related settings in Settings, then open logs or request records using the entry point shown in the current interface. The data shown under Data also depends on the current interface. Logs help explain how requests were handled; Data helps you observe connection and traffic activity. Neither should be confused with a bill or a provider's usage statistics. Before troubleshooting, note when the issue occurred and which request was involved, then open the relevant records instead of searching through a large history by guesswork.

Start with one identifiable new request

Start recording, use only the page or feature you want to troubleshoot, and note the approximate time. Opening many apps at once generates background requests that can quickly fill the records and make an error for another domain look like the problem. A page may involve several domains; the main page can load while resource requests fail, leaving content incomplete. Review the related requests from the same action rather than changing every setting as soon as you find one failed entry.

When reviewing a record, check the domain, destination address, matched rule and strategy, and whether an error occurred during connection. Treat only fields shown in the current record as evidence; a field being absent does not prove the system skipped that step. If a request matches REJECT, first check whether that is what the rule is meant to do. If it matches DIRECT when you expected PROXY, check the rule order and whether the correct Config file is active instead of immediately changing the server password or test timeout.

Log level and retention

The log level controls how much detail is recorded; check the app's guidance for what each level includes. For everyday use, keep the current level if it provides enough information for basic checks. Temporarily increase detail when you can reproduce an issue, then restore the previous level when troubleshooting is finished. More records do not make a connection more reliable and can make issues harder to find. Detailed logging is for collecting evidence, not for improving performance; it cannot replace correcting a rule or server setting.

[General]
# Example for learning: log level; this is not the app default
loglevel = notify

[Rule]
# Put specific domain rules before broader rules
DOMAIN-SUFFIX,ad.example.com,REJECT
DOMAIN-SUFFIX,example.com,PROXY
# Route other requests through PROXY
FINAL,PROXY

In the example above, the more specific domain rule comes first so a broader match does not take precedence. Rules are evaluated from top to bottom, and the matching rule's strategy is applied. When troubleshooting, focus on “Which line actually matched?” rather than only “Is this line in the file?” See the guide to REJECT rules for scope and handling unintended blocks. Example domains illustrate syntax only; they do not refer to an available service.

Data values and handling sensitive information

When reviewing Data, first confirm the reporting scope and when its counters start. Reconnecting, reopening the app, or clearing statistics may change the scope, so do not subtract values from different periods and attribute the result to one app. A small amount of traffic shows only that data was exchanged; it does not prove the destination page loaded fully. No noticeable change could also be due to cached requests. Treat Data as supporting evidence and check it alongside logs and real requests.

Logs may contain domains, addresses, request paths, subscription details, and other browsing information. If you need to save troubleshooting material, keep the original locally and make a reviewed copy with access credentials and unrelated details removed. Do not share a full subscription URL. Before clearing logs, note any relevant timestamps and matched rules. If an issue cannot be reproduced, do not leave detailed logging enabled indefinitely; restore normal settings and collect the minimum necessary evidence the next time it occurs.

06 · Widgets: Quick actions, status, and system refresh

Check Widget-related settings in Settings, then open the system's widget gallery to see which Shadowrocket widgets are available on your device. Available sizes, displayed content, and interactions depend on what the app and system provide. Do not assume a layout shown on another device is available on yours. A widget provides a status display or shortcut; it is not a separate server configuration and does not replace checking the current selection and connection in Home.

Check the in-app state before adding a widget

First select the server you plan to use in Home, confirm Global Routing, and verify the connection with a real request. Then add the widget. If its display does not match your expectations, you can focus on the display or shortcut rather than questioning the server configuration at the same time. If a widget lets you choose what to show, check whether it points to the current selection, a specific item, or another group. If no such option is available, do not assume it automatically picks a server based on latency.

After adding the widget, check that its text matches the app's state, then test only the actions it explicitly supports. Some shortcuts may open the app before the app carries out the action; whether another interaction can be completed directly depends on the system and widget. Check the final state, not just the tap response. To confirm that the intended server is selected, return to Home, check the selection mark, and make a new request. Opening the app does not by itself mean the connection has switched.

Why the display may not update immediately

The system manages widget refreshes and background execution, so a widget should not be treated as a live, second-by-second monitor. After a network change, connection stop, or server switch, it may still show the previous state. Open Shadowrocket to check first, then wait for the widget to refresh instead of tapping it repeatedly based on an old display. Repeatedly starting and stopping the connection can keep changing the actual state, making discrepancies between the widget and app more likely.

If the app and real requests work but the widget remains out of date, troubleshoot the display: confirm it is a Shadowrocket widget, check its configuration, then try reopening the app or adding the widget again. Do not start by deleting servers or Config files. If the app itself cannot connect, return to the Home, On Demand, and network checks. Re-adding a widget will not fix server authentication or DNS errors.

How widgets interact with On Demand

A manual widget action and an On Demand condition may occur one after the other. For example, the system may reconnect under an applicable condition after you stop the connection using a shortcut. Check On Demand rather than assuming the widget has failed. When testing shortcuts, temporarily disable On Demand, verify the manual behavior, then restore the conditions and test them together. Separating “Did the shortcut run?” from “Did another condition change the result?” helps identify the actual cause.

Consider privacy when displaying information on the lock screen. If a widget shows a server name or connection status, check whether the name contains anything you do not want visible. Server labels can help you identify entries, but should not include passwords, full subscription URLs, or other access credentials. A label is only a local organizational aid; changing it does not change the server address or protocol settings. After editing a label, check the selected entry in Home to avoid confusion between entries with the same name.

This guide does not prescribe a fixed widget size or layout, and a missing widget does not mean the app failed to install. Add only the display or shortcut you need, and keep a way to verify the state in the app. System requirements and compatibility are as listed on the App Store page and shown on your device. To reset widget settings, remove the widget while leaving the app configuration unchanged. Once everyday connections are confirmed, add widgets back one at a time. Isolating the change is safer than resetting the entire app and helps preserve a working setup.

07 · iCloud and Config: Sync scope, backups, and file updates

Check iCloud-related items in Settings and read the current interface's explanation of what syncs. Then check the files on this device in Config. Sync availability also depends on the system iCloud state, app permissions, and network conditions. Do not assume that enabling a toggle immediately sends all data to another device, or that Home, Config, statistics, and system authorization are all included in the same sync scope. Follow the items explicitly listed in the interface.

Save an identifiable copy before syncing

Before enabling or changing sync, organize the current file names, note which file is active, and use the app's available save or export option to keep a restorable copy. Names can describe a purpose, such as “daily rules” or “troubleshooting copy,” but should not promise an unverified result. Copying a file without checking that it is complete is not a sufficient backup. Reopen the copy and make sure it contains the sections you need, such as General and Rule.

Sync and backup have different goals. Sync makes corresponding changes available to participating devices, so an accidental edit may spread too. A backup lets you restore an earlier state. Before editing the same file on two devices, decide which copy is the baseline. If a conflict appears or duplicate files share a name, save both copies and compare their rules before choosing what to replace. Identical names do not guarantee identical contents, and the file opened most recently on a device may not be the one you want to keep.

Config updates and local edits

In Config, confirm which file is active, whether it comes from a remote source, and whether an update option is available. A remote configuration update is not the same as updating a Subscribe item in Home: the former concerns rules and configuration content, while the latter concerns server details you imported. Both can affect a connection, but check them separately. Get subscription links from your service provider. After importing one, do not treat it as an ordinary shareable URL or put it in a public note for convenience.

Before editing a remote configuration locally, consider whether a later update might overwrite your changes. Put custom rules you need to keep in a separate, manageable copy, and document its source and how you merge changes. If the app provides another maintenance method, follow its instructions rather than assuming all local content will be preserved. After an update, check key rules and the final strategy, then make a real request; do not rely only on the update completing successfully.

Checklist for moving to a new device or troubleshooting sync

If expected content is missing on another device, first check the system account and iCloud availability, then review Shadowrocket permissions and the in-app toggle. Wait for a stable network and check again. Do not repeatedly toggle sync and immediately delete local files; that risks losing the only complete copy. If only some content differs between devices, first check whether that content is within the stated sync scope before concluding that sync failed. Content outside that scope must be handled using the options provided by the app.

Reacquiring the app and restoring in-app data are separate processes. Find a purchased app through the App Store; see the guide to restoring purchases for details. You still need to check servers, rules, and system connection authorization individually. If you have multiple subscription groups, see the guide to managing multiple subscriptions to organize duplicates. Keep the working configuration on the old device until you have verified the new one, and avoid editing on both devices until the baselines match. Then resume your usual sync.

08 · Proxy ports: Listening scope and restoring settings

Check Proxy-related items in Settings and distinguish local proxy listeners, connection sharing, and any other options actually provided. Names and support depend on the current interface. A local listening port is not the same as the remote server's Port in Add Server. The local port determines how a proxy entry on your device accepts connections; the remote port is where the app connects to a remote service. Setting them to the same number does not make a connection more correct and may break existing settings.

First decide whether you need a local listener

If you normally use Shadowrocket through the Home toggle and have no specific need for a local proxy, do not enable an extra listener just because you see a Proxy setting. Keep the current working state unless you know which proxy protocol the connecting device supports and which address and port it needs. HTTP and SOCKS5 use different connection methods. If the connecting device selects the wrong protocol, requests may fail even when the port is reachable; checking the port number alone is not enough.

A local loopback address usually means access is limited to the device itself. If the interface offers an option to make the listener available on the local network, its scope and risks are different. Before enabling it, check whether the network is trusted, which devices can connect, and whether the interface provides authentication or access restrictions. Do not assume that every device on the same Wi-Fi is trustworthy, and do not widen the listening scope on a public network just to make troubleshooting easier. If you have a clear need, use the narrowest scope that meets it and restore the original setting afterward.

Troubleshoot ports, addresses, and conflicts

A port must be a valid number and match the value entered by the connecting device. If the listener will not start, check the toggle, input format, and possible port conflicts, then review the app's message. Do not keep changing ports at random and rely on one accidental success. Change the connecting device's setting at the same time and record both values. This guide does not guess at a universal default port; check the current interface and its guidance, and keep the original value if you can verify it.

The address must also match how the listener will be used. Do not assume the same address works both for connections from the device itself and from another device. The address assigned to a device on Wi-Fi may change when the network changes, so an address saved yesterday may no longer be correct. If the issue occurs only after switching networks, first check the current address and network isolation settings rather than changing the remote server. Turning off the extra listener and checking whether the existing manual connection still works is a useful isolation test.

Return to rules and the full verification path

After a connection reaches the app, its strategy still depends on the current Global Routing mode and Config. The snippet below demonstrates rule order: handle specific domains and private addresses first, then regional rules, and use FINAL last. GEOIP matching depends on the address and relevant data; it does not refer to a webpage's language or a server's name. This snippet is for learning rule syntax only. Do not replace your entire file without checking it, especially for exceptions already present in your configuration.

[Rule]
# Use PROXY for the specified domain
DOMAIN-SUFFIX,example.com,PROXY
# Use DIRECT for private address ranges
IP-CIDR,192.168.0.0/16,DIRECT
# Use DIRECT when the corresponding address data matches
GEOIP,CN,DIRECT
# Use PROXY if none of the preceding rules match
FINAL,PROXY

After making changes, check the current network, Home selection, Global Routing, Config, On Demand, and the Proxy setting you just changed, in that order. Then make a new request and inspect its record. This sequence helps distinguish an unavailable entry point, an unexpected rule match, and a failed remote connection. If a local proxy request fails, do not reset DNS, sync, and every server at once. Limit the investigation to the area you just changed so you can keep a working baseline.

If the result is still unclear, restore the recorded original values, disable the listener or condition you added, and test the previous connection path again. A successful recovery suggests the issue is related to this change, but does not prove that one particular parameter is at fault; repeat the test with one variable at a time. A recommended setup is not a fixed table of numbers, but a reproducible state: necessary features enabled, scope understood, original values recoverable, and real requests verifiable. For first-connection steps, see the quick-start guide. For purchase and compatibility questions, return to the App Store purchase guide rather than trying to solve an unrelated issue through network settings.