Shadowrocket Settings Guide

Settings / Scope

Settings scope, defaults and change history

First, distinguish app settings from request handling

Settings is not the only place that determines network behavior. The server selected in Home determines the connection target available for forwarding. Global Routing determines whether requests follow Config rules or use Proxy or Direct. Config stores rules and related parameters, while Settings includes app-level options for connections, testing, display and maintenance. Before troubleshooting, identify which layer the issue belongs to. Changing test settings usually won’t help when a website takes an unexpected route, and a delayed Widget update alone doesn’t show that a rule has failed.

For each setting, record four things: where it is, its current value, the behavior you want to change and how you’ll verify the result. For example, when adjusting DNS, the goal should be reliable resolution for a specific domain—not a lower test number. For On Demand, the goal should be a connection that starts as expected under specified network conditions—not keeping the app visible in the background. Define a repeatable action so you can tell whether the setting worked and rule out unrelated changes.

What “default” means

“Default” can mean at least three things: the app’s initial value on first launch, a value specified in an imported Config, or a value supplied by the current system network. They may differ. After restoring data, syncing through iCloud or switching Configs, the displayed values shouldn’t necessarily be described as factory defaults. This guide doesn’t guess at default values that can’t be confirmed on the device. Recommendations focus on keeping verified settings and minimizing variables, not on entering the same parameters on every device.

Use a change process you can roll back

Before making changes, save a copy of the Config that currently works, and note the selected server, Global Routing mode, network type and connection switch state. Keep a private record of names and changes; don’t post a full subscription URL or password publicly. Change one item, save it, reconnect as required by the interface, then verify the result using the same real-world action. If you change the server, DNS and rules all at once, you won’t know which change fixed the issue—even if things start working again.

“Saved” and “applied to new connections” are different states. Some settings take effect when the tunnel is re-established or a new request is made; existing connections may continue using their previous route. To verify a change, stop the original test request, disconnect and reconnect if needed, then try again. Don’t repeatedly change settings during a download, call or other ongoing transfer. The interruption itself can become part of the issue, making it hard to match Log entries to a specific change.

A good baseline doesn’t mean resetting everything. Keep settings you can already account for. Unless there’s a clear reason to change them, leave test methods, ports, sync scope and automatic connection conditions as they are; use the relevant section of this guide when an issue comes up. To check the app’s source, see how to verify the official app and confirm the developer is Shadow Launch Technology Limited and the app ID is 932747118. Handle purchase and installation questions through the App Store rather than trying to work around them by changing network settings.

DNS / Domain Resolution

DNS settings and resolution paths

DNS translates names to addresses

DNS translates domain names into network addresses; it isn’t the proxy connection itself. A request may resolve an address first and then be routed by a rule, or the proxy may handle the destination name. The exact path depends on the Config and protocol. So a successful server test doesn’t mean DNS is at fault if a website won’t load, and successful resolution doesn’t prove the destination is reachable. Check name resolution, the server connection, rule selection and the destination response separately rather than treating one result as proof of the whole path.

In Config, confirm which file is active and check whether it explicitly sets DNS. Then compare it with the relevant options actually available in Settings on your device. Don’t assume an empty field means no DNS behavior; it may use settings from another source. If the file contains dns-server, review that setting and its related notes instead of changing a displayed value on another page. If you’re unsure which settings take precedence, copy the file and verify the result in the copy.

Default sources and recommended values

If you don’t have a specific DNS requirement, keep the existing working setup. The system DNS source can be a useful comparison, but it isn’t right for every network and doesn’t mean every request bypasses the proxy. The snippet below shows the system syntax only to illustrate where the parameter goes; it contains no server details and isn’t a complete replacement for your own Config. Before changing anything, save the current value and make sure no other setting in the active file affects the resolution path.

[General]
dns-server = system

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT

Don’t stack multiple DNS addresses with unclear purposes just to add “backup” options. Different sources may return different results and introduce differences in timeouts and caching. Before choosing another resolution method, confirm that the app interface or Config syntax supports its format and that it’s reachable on your network. For encrypted DNS, distinguish transport encryption, access to the resolver and access to the destination. Satisfying just one of these conditions doesn’t guarantee the request will work.

Find the cause of DNS failures from the symptoms

If only one domain fails, check its spelling, whether the destination is still available and whether the failure is repeatable on the same network. If several unrelated domains fail, check Log for resolution errors. Trying an IP address is only a limited diagnostic clue: many services rely on domain names, certificates and request headers, so failure by address doesn’t prove the network is down. Use normal domain-based access for comparisons, and don’t mistake a certificate error for a DNS failure.

If the issue occurs only after switching Wi-Fi networks, note whether you need to sign in to the network, whether the system has a working connection and whether the client re-established its tunnel. Some networks can’t resolve names or reach external destinations until sign-in is complete; changing DNS may hide the actual access issue. Restore basic system connectivity first, then test Shadowrocket. If one network works and another keeps failing, that distinction is more useful than repeatedly replacing Config settings.

Caching can delay the visible effect of a change. The app, system, browser and remote services may all retain results, so don’t draw conclusions after refreshing a page once. Reconnect the client, close the old test page, make a new request and observe the same domain several times, noting when each test occurs. Use the cleanup options available on your device. You don’t need to delete all Configs, reinstall the app or clear unrelated data to test one domain.

After troubleshooting, note the DNS source you kept, the networks it applies to and the domains you used to verify it in your own Config notes. Don’t sync a temporary test value to all your devices before confirming it works. For the differences between DOMAIN, IP-CIDR and name resolution, see the glossary. If the switch is on but access still fails, use the server, mode, DNS and rules troubleshooting checklist to review the full path.

Global Routing / Config

Global Routing, rules and Config overrides

The mode determines how rules are used

Global Routing is the first place to check when tracing where traffic goes. Config mode processes requests using the active Config file. Proxy mode handles traffic within the client’s scope in proxy mode, while Direct mode handles it in direct mode. These describe how the client processes traffic; they don’t prove how every kind of system traffic on the device is handled. Before testing a rule, confirm that Config is selected. Even a correct rule file may not determine the current behavior otherwise.

For everyday routing by domain or address, use a verified Config. Proxy and Direct can help narrow down an issue, but a temporary comparison shouldn’t automatically become your long-term setup. Note the original mode before switching, and restore it after testing. If access works in Direct mode, that only confirms the direct route worked for that test. If it works in Proxy mode, that doesn’t prove every Config policy is correct. Verify the mode, rules and server separately; none is a substitute for the others.

Rule order and final matching

Rules are usually checked in order, with specific rules before broader ones. The final rule handles requests that haven’t matched earlier rules. DOMAIN matches a full domain name; DOMAIN-SUFFIX covers the specified domain suffix; IP-CIDR and IP-CIDR6 apply to address ranges. GEOIP matches based on IP geolocation, which depends on the database and address assignment. GEOIP doesn’t identify where a website’s content comes from, and a domain may resolve to different addresses over time.

[Rule]
DOMAIN,example.com,DIRECT
DOMAIN-SUFFIX,example.org,PROXY
IP-CIDR,192.0.2.0/24,DIRECT
IP-CIDR6,2001:db8::/32,DIRECT
GEOIP,CN,DIRECT
FINAL,PROXY

The example domains and documentation-only address ranges are for illustrating syntax; they aren’t real servers or general routing recommendations. PROXY requires an existing working proxy connection, DIRECT means a direct connection, and FINAL sets the handling for other requests. Changing the final rule to DIRECT changes the route for requests that didn’t match earlier rules. When reviewing a Config, check not only the line containing the target domain but also earlier rules and the final rule to see which branch actually handles the request.

The selected file matters more than its name

Importing a Config file doesn’t automatically activate it, and editing a file doesn’t mean the current connection is reading that copy. Before each test, return to Config to confirm the selected file and check that your changes were saved. If filenames are similar, add private notes about their purpose, such as daily baseline or temporary test, rather than relying on their position in the list. When a file has multiple sections, edit only the relevant one and keep the existing server and other required parameters intact to avoid losing context when copying a snippet.

Your existing subscription and Config file are not interchangeable. A subscription update may change the server list, but whether rules change depends on the imported content and the update process. If a server disappears from the subscription, you may need to confirm the selected server again; that doesn’t mean DNS needs to be re-entered. Compare the available servers, selected item and active Config before and after an update. This makes it easier to identify the cause than rebuilding all your data. Keep links containing credentials on your own devices; don’t share them in public troubleshooting materials.

If the same domain sometimes takes different routes, check for related domains, different address families, reused connections or redirects to other resources. A page and its images, videos or API requests may use different domains. Find the request that actually failed in Log, then adjust the relevant scope; a rule for the page’s main domain may not cover every resource. Take particular care with DOMAIN-SUFFIX rules: their broad scope can affect many unrelated requests when you’re trying to fix just one destination.

On Demand / Connection Triggers

On Demand and connection status

Automatic triggers don’t guarantee a working connection

On Demand uses saved conditions to trigger a VPN connection. Its behavior also depends on system network state and which actions the device allows. It doesn’t check server health or fix incorrect credentials, unreachable addresses or DNS failures. If a manual connection isn’t stable yet, don’t add automatic triggers. Verify the server and rules first, then enable them. Otherwise, automatic connection attempts can overlap with manual troubleshooting, making it harder to tell when a connection started and why it failed.

When adding a VPN configuration for the first time, the system displays an authorization prompt. Follow it only when you’re initiating a connection in Shadowrocket, and complete the authorization as prompted by the device. Prompt text and authentication methods depend on what the device shows. Existing VPN configurations may also be affected by device management policies or other connection states. If authorization fails or the status immediately reverts, check the system prompt first; don’t repeatedly delete app data. Editing rule text can’t resolve a system-level restriction on creating the tunnel.

Conditions, initial state and recommended choices

Open On Demand on your device and note whether it’s enabled and which network conditions are already set. Available conditions and how they’re displayed can vary; this guide doesn’t assume all devices offer the same options or that a restored setup starts disabled. Begin with one condition you can verify clearly instead of adding several overlapping ones at once. If you want different behavior on different Wi-Fi networks, check the network names carefully and remember that networks with the same name may not be the same environment.

To verify automatic connection, stop any ongoing transfer, note the starting network and switch state, then switch networks once. Wait for the system to finish connecting before making a real request. Change one condition per test and record what happens on Wi-Fi, cellular and before and after locking the device. Don’t treat a brief interruption during a network switch as a persistent issue or rely only on the status icon; switching networks, rebuilding the tunnel and opening a new connection can take different amounts of time.

What to do if the connection returns after you turn it off

If the connection reappears soon after you turn it off manually, check whether On Demand is still enabled and whether the current environment meets its trigger conditions. To stop the connection temporarily, address the automatic trigger setting first, then disconnect and observe again. Repeatedly tapping the Home switch without checking conditions can create a cycle of disconnection and reconnection. If the problem continues with automatic triggers disabled, note the system VPN status and time of the action, then check other system settings that might affect connections.

Wi-Fi sign-in pages are another common edge case. Some networks require you to complete sign-in through a system prompt before normal access is available. If an automatic trigger starts connecting before the network is ready, it may wait or fail to access destinations. First confirm how the network requires you to connect, complete system sign-in and verify basic connectivity, then check On Demand. Don’t keep switching servers on a network you haven’t successfully joined; that can make an access issue look like a client configuration problem.

When a device is locked, the app not being in the foreground doesn’t mean the VPN has stopped. Likewise, connection text left in a Widget doesn’t prove that a request is succeeding. The system schedules the relevant network components, so you can’t infer background behavior from the foreground screen alone. After returning to the device, make a new request and check the actual status and Log. Repeatedly opening or closing the app or toggling the switch changes the conditions you’re trying to observe and makes automatic connection behavior harder to assess.

You should be able to explain each condition you keep in one sentence: under which network conditions should the connection start, and when? If you need exceptions, verify and record them one at a time; there’s no benefit to maximizing the number of conditions. Retest after moving to a new device or restoring data, since old conditions may still exist even though the new device’s network environment is different. For initial authorization and connection steps, revisit the tutorial. This page explains the settings and limitations that apply afterward.

Ping / Connectivity Test

Ping, test methods and interpreting results

A test can only support conclusions about the part it measures

Ping and Connectivity Test can provide clues about a connection, but test methods cover different parts of the path. Some check whether a server address is reachable, some attempt a transport connection and others send a test request through the proxy. Check which method and target are selected on your device before interpreting the result. A response time in a list doesn’t verify a destination website, the full rule path or every protocol feature. No result may also mean the remote network doesn’t respond to that test method.

A basic network probe, a port connection and a request through a proxy are different actions. A server may not respond to one type of probe and still accept proxy connections. It may also accept a port connection quickly but fail during authentication or forwarding. So “the number is low, but the page won’t load” isn’t a contradiction. When interpreting results, check whether the actual proxy protocol was used, whether authentication completed and whether the test target was the service that failed. Don’t extend a partial success into a claim that the whole connection works.

Default method and recommended parameters

Use the Ping method, timeout and target currently shown on your device; don’t assume every device has the same settings after a restore or change in usage. Keep a known test method and use the same target for before-and-after comparisons. A timeout that’s too short may mark normal fluctuations as failures; one that’s too long only makes you wait longer and won’t make a failed connection work. Unless there’s evidence that the timeout is inappropriate, there’s no need to change it—or to change every test setting at once.

Choose a test target that’s stable, clear and suitable for the issue you’re checking. If the app supports a custom target, confirm the required format and don’t include credentials or use a page that requires sign-in. Redirects, rate limits, maintenance or certificate issues at the target can also affect results. Keep the old target for comparison if you change it, and note that this changes the test conditions; don’t treat the old and new values as a direct server performance ranking.

Create a repeatable test set

Prepare a simple set of checks: on a fixed network, test the current server, use the same Global Routing and Config to access the destination, then check Log for the failed request. Repeat a few times and note whether the failure is consistent, occasional or tied to a specific action. Avoid running many tests at once, especially on a weak network or where the server has limited connection capacity. Tests consume connection resources too, and high concurrency can create behavior unlike an ordinary single request.

If the server test succeeds but a webpage fails, continue by checking the destination’s DNS resolution, rule match, authentication and remote response. If the test fails but the page works, first check whether the test method applies rather than deleting a working server. If only one server keeps failing, verify its address, port, protocol parameters and active status against the service details you already have. Confirm those details with their original source; repeatedly increasing the timeout won’t reveal the correct values.

For TLS connections, distinguish the server address from the name used to validate the certificate. They may differ in a valid configuration; follow the details provided for your existing server. Don’t routinely lower certificate validation requirements when verification fails. Check the device’s time, the entered name, certificate chain and server status first. A successful port connection only confirms a response during the transport stage, not that the TLS negotiation and request completed.

After testing, restore any temporary test targets or methods and record the parameters you kept. If the issue occurs only on one network, keep at least two results under the same conditions before moving on to Log. For protocol field names, see Features and Settings and the glossary. Those pages explain the concepts; this section covers what the test evidence can support.

Log / Data

Log, request records and troubleshooting evidence

Use Log to trace a single request

Log helps connect symptoms to the stage where they occur; you don’t need to interpret every line. Before troubleshooting, note the time, network, server, Global Routing mode and Config, then perform one specific action that fails. Review only the relevant entries from around that time, looking for links between the domain, connection target, rule and error. A webpage may generate many resource requests, and the first failure isn’t always the one that prevents the page from working.

First check whether the request reached the client, then whether it resolved, which policy was selected, whether a connection was established and whether the remote side responded. If you can’t find the target in Log, don’t conclude that the rules are working. The request may not have been sent again, may have been cached by the app, may have taken a different system path or may not be included in the current logging mode. Make a clear new request and check the Log scope again. Narrowing the issue down by stage is more reliable than searching for one fixed error message.

Logging scope and default state

The information and detail available in Log depend on the options and current state on your device. Some details appear only when the relevant logging is enabled; enabling it won’t fill in earlier requests. For everyday use, keep enough logging to observe basic behavior and increase detail only briefly while reproducing an issue. More logs may use additional storage and processing resources and can include more browsing details. Restore the original setting after troubleshooting and remove records you no longer need as appropriate.

Log errors often describe a stage in the process, not the ultimate cause. For example, a timeout might be due to an unreachable address, a server that didn’t respond, a slow destination or a network switch. One word isn’t enough to assign the cause. Connect the entries before and after the error to the action and its time. If a change moves the error from resolution to connection, note that the request progressed further—but the connection isn’t fully restored yet.

What Data and connection status can tell you

Traffic or related statistics in Data can help confirm that data activity occurred during a period, but they don’t prove that a destination service responded successfully. Totals may include other background requests or data from earlier connections. Check the time range shown on the page before comparing short periods. If the range is unclear, don’t use a cumulative change to infer whether a particular rule matched. For precise diagnosis, rely on the relevant request record and a repeatable access test.

If the issue is intermittent, keep the Config unchanged until the reproduction conditions are clear. Note whether it relates to a network switch, device lock, subscription update or ongoing transfer, then run a limited number of tests under the same conditions. Changing a different setting after each failure makes results hard to compare. Keep a stable baseline and a copy with one change so you can refer back to the original state and check whether restoring it resolves the issue.

Protect subscription URLs, server credentials, personal domains and device details when preparing records. Share only the time range needed, keeping error types, rule keywords and processing stages while removing authentication data and personally identifying details. Don’t post a full Config together with Log, and don’t assume that hiding a password removes all sensitive information. Query parameters in subscription URLs, connection addresses and some names may identify personal services; check each item carefully.

Once the issue is resolved, test again under the original conditions and turn off any temporary detailed logging. Deleting all historical logs isn’t a routine fix; it only changes visible records and storage use, not server parameters or rules. For the full sequence, see the troubleshooting guide for connected but no internet. Identify the stage from the symptoms first, then decide what to change.

Widget / iCloud

Widgets, iCloud sync and device restoration

A Widget is a shortcut, not a full diagnostic view

A Widget lets you check status or use shortcuts from system-provided locations. The available options depend on the Widget provided on your device. The system schedules refreshes, so what it displays may not reflect a recent network change immediately. If the Widget and Home don’t match, open the app to check the current server, connection status and actual requests, then wait for the Widget to refresh. Don’t rewrite the Config to fix a display delay or rely on the Widget’s text alone to decide whether a connection is active or working.

Add the component through the system’s Widget editing flow, select Shadowrocket and check the options offered by the current Widget. If you can choose related content, make sure it points to an item that still exists and is relevant. After restoring data, renaming or deleting items, review the selection again. Start with a simple display whose purpose is clear rather than placing several similar shortcuts that could trigger repeated connection actions before you confirm the state.

Sync data and purchase eligibility are separate

iCloud sync handles data supported by the app. It isn’t the same as an App Store purchase record, and it doesn’t transfer an active VPN session between devices. Buying the app, syncing settings and authorizing a connection are three separate processes. Being able to get the app from your purchase history on a new device doesn’t prove that all settings have synced. If a Config appears, still check local network authorization, the selected server and the rules before testing a connection.

Check the sync state and supported data on the device in Settings. Before enabling sync, confirm that you’re signed in to iCloud and that the relevant access is allowed, then save a working local copy of your Config. Don’t make major changes to the same content on two devices and only then wait for sync. Sync isn’t a backup with unlimited version history; don’t assume you can recover every old value. Keep a separate recoverable copy of important Config changes in secure storage, and protect any credentials it contains.

Handling sync delays and conflicts

If a change doesn’t appear on another device, first check that both devices have network access, iCloud permissions are set correctly and sync is enabled in the app. Allow a reasonable amount of time, then check the content. Don’t repeatedly import, overwrite or delete items to “force” a sync. If the two devices already differ, save a copy from each before deciding which one to keep as the baseline. Whether the app merges, replaces or preserves conflicting content depends on what you actually see; this guide doesn’t assume a fixed conflict-handling method.

Different devices may need different network policies. An iPhone’s cellular use differs from the Wi-Fi environments commonly used with an iPad; On Demand conditions, test target reachability and local port use may also vary. After syncing, review settings that depend on the environment instead of assuming the same filename means no checks are needed. First establish a basic working connection with the same Config, then restore automatic triggers and Widget shortcuts one at a time. This helps avoid mistaking a successful sync for proof that every setting applies.

When moving to a new device or reinstalling, get the app through the App Store purchase history for the original purchasing account. Refer to the App Store listing for re-download details and general purchase eligibility. Then check that supported data has been restored, verify that your server and subscription details are still valid, and complete local connection authorization as prompted by the system. For details, see how to restore a purchase and restoring Shadowrocket on a new iPhone. There’s no need to handle purchase and sync issues as one step.

On iPad, the layout may shift in landscape or split-screen mode. Find controls by their interface names—Home, Config and Settings—not by fixed screen coordinates. See iPad purchase and interface details for more. After restoring, recheck the Widget selection and On Demand conditions to make sure the shortcuts match the data you kept.

Proxy / Ports and rollback

Proxy ports, parameter boundaries and rollback checks

Local listening ports and remote server ports

First identify which end a “port” belongs to. The server port in Add Server comes from the service details you already have and is used to connect remotely. If Settings provides a local Proxy listening option, it serves proxy requests from the device or permitted sources. These ports have different purposes: don’t change the local port to fix a remote connection failure, and don’t enter a local port in the server details. Before changing anything, check the address, port and protocol together and confirm which layer you’re adjusting.

Local HTTP or SOCKS5 access and the remote server protocol are different concepts. The connecting app or device must use the method actually provided locally; the remote side continues to use the saved server parameters. A port listening by itself doesn’t verify DNS, rules or remote forwarding. If no app or device needs to connect explicitly to the local Proxy, keep the current state; there’s no need to configure an extra listener for an ordinary VPN connection.

Default ports and access scope

Check the actual port number, listening scope and authentication options in Settings on your device; this guide doesn’t prescribe one fixed value for every installation. Before making a change, note the original value and confirm which clients already use that port. After changing it, update those clients too; changing only one end can lead to a refused connection or an endless wait. If there’s a conflict, identify its source first. Don’t try a string of numbers without recording the final value you keep.

Allowing access only from the device and allowing sources on the local network have different risks. Before widening the listening scope, check whether the network is trusted, whether authentication is available and correctly used, and which sources can reach the port. Don’t leave a broader access scope enabled just to make a one-time test easier. Whether a local network request can reach the port also depends on network isolation and system state. Enabling an option in the app doesn’t mean every device can connect—or that you should expand access further.

Settings can’t compensate for missing protocol parameters

Each protocol—including Shadowsocks, VMess, VLESS, Trojan, WireGuard and Hysteria2—has its own fields. Use the details provided for your existing service. Changing Ping, Widget or Log settings can’t supply missing fields when the address, port, authentication, transport or encryption parameters don’t match. After importing, check the protocol type and required parameters, especially for manually entered details. Don’t assume the current protocol uses the same field structure as a different working connection.

If your server uses a domain name, it may continue pointing to a working service as its address changes. Replacing it with an address from a single DNS lookup could break name verification or future updates. Keep any specified TLS names and transport paths from your existing server details; don’t remove them just because a port test received a response. Correct one confirmed entry at a time, then make a real connection test and note which stage failed before and after.

Return to the last verified working state

If the issue remains after troubleshooting, undo changes in reverse order using your notes: restore temporary port and test settings, restore DNS, reselect the original Config and server, then check On Demand. Don’t clear all data at once; you’d lose both your working baseline and useful evidence. Reconnect and test the same destination after restoring. If the original setup also fails, check the network and the status of your existing service instead of assuming every change came from client settings.

To review purchase and system requirements, see App Store access information. Shadowrocket is a paid commercial client; a one-time purchase of the client is not a service plan. Confirm your existing service’s validity separately from the app purchase. The goal of Settings isn’t to change every option, but to give each retained value a clear purpose, make every automatic behavior explainable and keep a path back to the last verified working state.