Official Manual · Settings Reference

Shadowrocket Settings Guide

Instructions are based on the iPhone / iPad interface. If you haven't imported your own subscription or server details yet, follow the Getting Started guide to make your first connection. To check when a setting takes effect, how to verify a change, or how to restore it, use this page's table of contents. Options on other platforms depend on their respective interfaces.

Settings baseline
Record current values and check their scope first
Change and verify
Change one setting at a time and retest the same request
Restore
Undo the latest change before broadening your investigation
01 Settings baseline

Settings and scope

Before making changes, check three things: whether a connection is established, how new requests should be routed, and whether a setting follows the current configuration or applies to the entire client. Start in Home to check the connection and Global Routing, then open Config to identify the active file, and finally check the relevant item in Settings. A file appearing in the list doesn't mean it's enabled, and editing a file doesn't guarantee that current requests use it. If you can sign in but something won't load, note the specific action that failed; don't treat an entire page as the result of a single request.

Record the default source and how to restore it

This guide distinguishes between factory defaults, values specified in a file, and values currently shown on the device. Values on first use may already be affected by an imported configuration, system permissions, or restored data. Clearing a field may mean it inherits a value from elsewhere, not that the feature is disabled. Where no verified universal default exists, the chapters below provide repeatable starting points for testing rather than presenting recommendations as defaults. Record the actual state before changing it—including a blank field, an automatic value, or an explicitly entered value—not just a number that seems to work.

Three Global Routing modes

ModeHow it worksUseful for testing
ConfigRoutes traffic according to rules in the active configuration.Checking whether a target matches the expected rule.
ProxyRoutes traffic within the client’s forwarding scope through a proxy.Checking whether a target is reachable through a proxy on the same network.
DirectSends traffic within the client’s forwarding scope directly to its destination.Checking whether the same target works over a direct connection.

Direct doesn't disconnect the client. For a comparison, keep the client connected and send a new request in each mode. Test with the client disconnected separately if you need to compare behavior with and without it. Some apps reuse existing connections or show cached content. After switching modes, use a new tab or reopen the relevant feature, then confirm that a new entry appears in Log. When you're done, switch back to your usual mode. Otherwise, even correctly written rules may not be applied because the test mode was left active.

Test rules and fallback behavior in a copy

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

Add test rules to a copy you can restore. Check for broader match conditions above the rule, and make sure it doesn't come after the fallback entry. If the panel shows the action as PROXY, also identify which server is actually in use. A rule match only selects an outbound route; it doesn't mean a connection to the server was established. If the target in Log differs from the domain in the address bar, first determine whether the failure affected the main request, a sign-in redirect, or a page resource. Don't add an exception for the wrong target. See the configuration file structure guide for an overview of each section.

When troubleshooting, note the time, network type, active file, and mode. After temporarily changing a value, retest immediately. If the result doesn't show a clear difference, restore the original value before trying the next setting. This helps distinguish a setting change from a change in network conditions—even if the issue disappears after switching networks. If you can't reproduce the result, record the conditions at the time; don't treat a one-off recovery as a lasting fix.

02 Domain resolution

DNS: Sources, fallback, and testing

DNS resolves domain names to addresses the client or next hop can use. An enabled connection or a successful Ping doesn't prove that a website's domain is resolving correctly. If resolution fails, first check whether it affects every target or only one domain, a type of local network name, or a service whose address recently changed. Note the domain and network where the issue occurred, then check whether the active Config specifies a resolution method. Seeing a setting in Settings alone isn't enough to determine which resolver each request uses.

Check the source first; don't infer behavior from a blank field

Check [General] and [Host] in the active file. The former may specify resolvers; the latter may map certain names to fixed addresses. A mapping isn't a backup resolver, and it won't automatically update when a destination's address changes. If a site moves and only a few names still connect to its old address, check mappings and caches first. Imported files may also introduce explicit values. If system DNS settings, values specified in a configuration file, and values shown in the app all coexist, don't infer the final priority from the order in which they were entered. Verify it using actual request records, returned addresses, and one-setting-at-a-time comparisons.

For everyday use, start with the existing DNS settings. When accessing local devices on a home or office network, keep the network's resolver initially; public DNS services usually don't know local hostnames. If you want to use a resolver you've verified, make sure it's reachable on the current network and enter it in the format the client supports. With encrypted DNS, the service address, encryption method, and certificate hostname must match. Some service addresses also need to be resolved first. Switching to encrypted DNS doesn't automatically fix access problems. Don't verify a regular setup by ignoring certificate errors.

Test two targets and change one condition at a time

  1. Keep the current network, server, and Global Routing mode unchanged. Choose one ordinary target that works as a control and one that fails, then send a new request to each. Record whether an address is returned, whether a connection error follows, and which target each resolution or connection error refers to.
  2. Change DNS settings only in a copy of the configuration. Don't also remove [Host] entries or edit routing rules. Retest both targets in the original order. If they take different routes, explain the routing difference before assessing the DNS results. If only local network targets are affected, restore the original DNS settings and test again on the network where the issue can be reproduced.
  3. If the old address still appears to be in use, check whether the app reused an existing connection. Start a new test session and, if needed, wait for the DNS cache to expire before comparing again. Restore the active file and original values after testing so the test settings aren't mistaken for your everyday baseline.

Tell successful fallback apart from a later failure

Configuring multiple resolvers doesn't guarantee they'll be used only in the order entered. Settings may allow retries, fallback, or parallel queries, and a successful resolution may have come from a different service. To check one resolver, test it on its own in a copy you can restore; don't use a successful page load as your only evidence. If a domain resolves after you change resolvers but still won't connect, investigate the rule action, address family, connection, or certificate. Continuing to swap DNS servers may obscure more useful clues.

If a site's home page loads but sign-in or images fail, check the domains used after redirects and by page resources. They may resolve differently or take different routes. Replacing a domain with an IP address often changes certificate verification and server identification, so it doesn't prove the issue is DNS-only. For intermittent problems, note whether failures follow network changes and whether they can be reproduced under the same conditions. This is more useful than a few unrelated screenshots of successful loads; compare it with the On Demand trigger records as well.

03 Automatic connection

On Demand: Triggers and how to stop them

On Demand controls when the system attempts to establish a connection based on conditions. It doesn't decide whether a request uses PROXY or DIRECT, and it doesn't verify that a server is available. First connect manually from Home and confirm that you can access the intended service. Then test On Demand. If manual connection already fails, automatic triggers will just repeat the same failing path, making it easy to mistake a server issue for a trigger problem.

Record the switch state separately from the trigger conditions

As a starting point for testing, turn off On Demand and connect manually; don't assume it's off by default on every device. System restores, device management profiles, and existing settings can make one device's state differ from another's. Before enabling it, record the switch state, network conditions, and exceptions shown in the interface. Confirm that the system allows Shadowrocket to use the relevant VPN configuration. On managed devices, some settings may be restricted; follow your organization's requirements rather than removing other configurations to reproduce a particular screen.

Describe the scenario in terms you can verify—for example, “Connect manually on the specified Wi-Fi; don't connect automatically. After leaving that network, check whether the configured condition triggers a connection attempt.” Start with one network scenario you actually need and keep the rules to a minimum. If the interface offers conditions for network type or Wi-Fi name, select the relevant options. The system detects the current network connection, not the router's appearance or your physical location. Similar names, the same name used in multiple places, or a device switching to another network can all make the actual match differ from what you expect.

Test when conditions match, when they don't, and how to restore

  1. Enable the required condition on a network where manual connection has been verified. Move to an environment that meets the condition, send a new request, and compare the connection state before and after. Record when the state changed and which network was actually in use. Don't treat an in-progress network switch as the final result.
  2. Then test a network that doesn't meet the condition. Check whether a new automatic attempt occurs, and distinguish an existing connection that remains active from a new connection initiated by the system. A condition not being triggered doesn't necessarily mean an existing connection will be disconnected.
  3. After testing, turn off On Demand, disconnect manually from Home, and then repeat the same request. If a connection starts again after disconnecting, check that the trigger settings are actually off and whether the system's active connection is for Shadowrocket. Change only settings involved in this test.

Automatic connection attempted, but the service still doesn't work

If the interface shows a connection attempt, first check whether the server was reachable when the request occurred; don't expand the trigger conditions yet. Public Wi-Fi may require you to complete a sign-in or access confirmation in a browser. After mobile service returns, a signal indicator doesn't always mean the destination is reachable. You can temporarily turn off On Demand, follow the network's normal sign-in process, and confirm a manual connection. Then retest the same trigger condition. If manual connection still fails, investigate the network, DNS, and existing server settings first.

If an issue occurs only after the screen locks, when returning to the foreground, or during a network switch, test each action separately. Don't assume that events occurring one after another are causally related. Record whether a new request occurred, whether the old connection had ended, and whether the state shown when the app returned to the foreground matched the system. If results differ between devices under the same conditions, compare system network settings and management restrictions rather than copying the entire configuration. To restore automatic connections for regular use, verify one entry condition and one exit condition on a frequently used network before adding exceptions one at a time. Test only one new change at a time.

04 Connectivity tests

Ping: Methods, timeouts, and results

Ping or Connectivity Test results describe a single probe under the selected conditions. They don't prove that every app can access the destination over the same route, and they aren't a measure of everyday download speed. Check which test method the device actually offers before interpreting the result. Different probes may test a server address response, a port connection, or an app-level request to a specified target. Even when all results are shown in milliseconds, their start and end points may differ, so the values aren't directly comparable as a ranking.

Distinguish the test method, target, and timeout

ResultWhat it tells youWhat it doesn't tell you
Port connection succeedsA transport connection to the target was established in this test.The proxy protocol settings are correct or the service is accessible.
Test request receives a responseThe target responded under these test conditions.Other domains, protocols, or longer connections will also work.
Test timed outNo expected response arrived before the wait period ended.The server is disabled or the problem must be on the server side.

Use the method, test address, and timeout actually shown on the device. Some interfaces only provide a way to start a test and don't expose its parameters; don't guess the underlying method. If you can edit the test address, choose a stable target you can access that doesn't require sign-in. Addresses that require authentication, redirect to an access confirmation page, or depend on session information aren't suitable long-term benchmarks. Keep the original timeout unless you have a specific reason to change it. If the network is genuinely variable and the interface allows it, temporarily extend the timeout once to see whether the original result depended on the wait period. A longer wait doesn't mean a faster connection.

Create comparable test records

  1. Use the same device and keep the current network, test method, and target fixed. Test one existing server at a time. Record success, timeout, or a specific error—not just the lowest value from a successful test. Note the original result before changing a setting so you can check whether any difference remains after restoring it.
  2. Repeat the test several times under the same conditions. Distinguish persistent failures, occasional failures, and variation in successful response times. Testing many servers can change both device network load and server response. To investigate one issue, stop batch testing and retest only the entries in question.
  3. Return to Home, make a real request, and check the corresponding Global Routing mode and Log entry. If the probe succeeds but the service doesn't work, investigate routing rules, DNS resolution, protocol negotiation, and the service response separately. A successful probe doesn't rule out a service failure.

When to stop adjusting Ping

If a port connects quickly but the service remains inaccessible, first check the address, port, protocol, and corresponding verification parameters in the existing server details. An open port doesn't prove that it provides the service required by the selected protocol. A direct test and a request through a proxy may also follow different routes. If the problem disappears when switching from Wi-Fi to mobile data, record that as a network comparison—not as proof that a latency setting fixed it. Retest on the original network under the same conditions to see whether the difference is consistent.

If the service works but only the probe fails, first check whether the test address suits the current network and method. Some networks allow real traffic but don't respond to a different kind of probe. Conversely, a simple test may succeed while a long connection still drops. For intermittent issues, recording the network, action, and time needed to reproduce the failure is more useful than continually increasing the timeout. To compare two setting changes, compare results only when the method and target are the same and network conditions are similar. Otherwise, record them separately rather than comparing the numbers directly.

05 Request diagnostics

Log: Find the failure point by time

Use Log to see what a specific action accessed, which route it took, and where it stopped. Before you start, narrow the issue down to one repeatable action, such as opening a particular page or using the same feature in an app. Note the approximate time, stop refreshing anything unrelated to the test, and send one request. A single action may contact sign-in, resource, and service endpoints. Treating the last error in Log as the cause of the main request can lead you to mistake an incidental background request for the problem.

Start with the current log level

Start with the log level currently shown. Increase detail temporarily only if the existing records can't distinguish DNS resolution, rule matching, and connection stages, and the interface offers a more detailed option. Note the original level before testing, then restore it afterward to avoid accumulating unrelated records. To compare before and after, note the test times to define the observation window; you don't need to clear the entire history first. Clear old records only when you're sure they're no longer needed and the interface provides that option.

Follow each stage; success at one stage doesn't mean the whole request succeeded

  1. First, locate the target. Narrow the search by time and domain, then check whether the target in Log matches the failing feature. If only a resource request failed while the main request succeeded, investigate that resource. If the expected entry is missing, confirm that the app sent a new request instead of loading cached content.
  2. Next, check the route. If you see DIRECT or PROXY, interpret the result in the context of the current Global Routing mode and active file. If a rule selected the route, check whether an earlier rule matched the target first or whether it fell through to FINAL. Don't infer the actual route from the last line of the file.
  3. Finally, identify where processing stopped. DNS errors, connection refusals, timeouts, protocol verification failures, and service response errors each point to different areas to investigate. Resolution for some routes may happen on the other end, so local records may not show the full process. Note missing information as unobserved; don't invent evidence.

For example, text on a page loads but images consistently fail. Compare the domains they use, the routes selected, and where each request stopped. If an image request matched a broader rule than expected, adjust only that match in a copy and compare the results. If it selected the expected route but the destination refused the connection, check the port and service. Return to DNS only if the failure is confirmed to have occurred during resolution; don't change the proxy, DNS, and rules all at once.

When records are missing or need to be shared

If you can't find a target record, first check that you're viewing the right time period and that the device clock and log timestamps align. Then check the Home connection state and the app involved to confirm that it actually sent a network request. Some records may not appear in the current view because of the log level, filters, or traffic handling scope. Try a known reproducible target to confirm that your observation method works, then compare it with the failing target. Not seeing an entry only means the current view doesn't show that information; it doesn't by itself prove that no request occurred.

If a colleague needs to review the issue, describe the reproduction steps—for example, “Use the same network, keep the same file and mode, then send one new request”—and include the expected and actual results. State exactly which setting you changed and whether restoring its previous value reproduces the issue. This helps distinguish an intermittent problem from a reproducible configuration difference. When finished, restore the log level, disconnect any connection established only for troubleshooting, and confirm that no extra settings were left enabled just to capture logs.

06 System access

Widget: Display and action limits

A Widget is a system entry point for viewing information or triggering an action, not a separate configuration. Available sizes, placement, and actions depend on the device, operating system, and features Shadowrocket provides on that device. To check the current connection and Global Routing mode, return to Home. System refresh timing may affect what the Widget displays; it isn't a live log or a frame-by-frame copy of the app's state.

Start testing without a Widget

Whether a Widget has been added depends on the system layout, which may also be restored when you set up a device. If you don't need a shortcut, keep the current layout; this doesn't affect connecting in the app. To add one, first confirm that Shadowrocket opens normally and you've completed any system confirmation needed for an initial connection. Then open the system's supported Widget gallery, search for Shadowrocket, and choose from the available sizes and positions. Don't assume your device offers the same options as another device in a screenshot. Adding or removing a Widget in the system doesn't change Config.

Before choosing a layout, decide what you need: to check your usual connection status on the Home Screen, or to perform a shortcut action from a system-supported location. Different sizes may show different information; if you only need status, there's no need to take up more space for extra fields. If someone else uses the device, or the screen is visible in public, check what information will appear before placing it somewhere easy to see. Start with one Widget, compare it with the app once, and consider other locations only afterward; multiple Widgets may refresh at different times and give a misleading impression.

Compare once to separate display from action

  1. Open Home and note the connection state, current Global Routing mode, and selected server. Return to the system location where the Widget appears. Without tapping it, check whether its display matches the state you just saw. If it updates later than the app, treat that as a display delay—not a new connection failure.
  2. If the Widget offers an action, trigger it once. Return to Home to check that the expected action occurred, then verify it with a real request. If the system asks you to confirm, read the prompt before continuing; don't keep tapping to force a refresh.
  3. Compare once with a manual connection and once with On Demand enabled. If the client reconnects automatically after you disconnect manually, check the system behavior using Triggers and how to stop them. The sequence of text shown in the Widget alone can't tell you which entry point established the connection.

Widget missing, delayed, or unresponsive

If Shadowrocket doesn't appear in the system search, open the app to confirm its basic setup is complete, then check whether the system's add list currently offers a Widget for it. If the app works but the system status briefly differs after a connection change, wait for the system to refresh or check the app again. Don't reset your configuration or change servers to fix a display delay. If repeated comparisons show no updates, remove only that Widget, add it again from the system list, and see whether the issue was limited to the original instance.

If tapping the Widget only opens the app without changing the connection, first check whether that Widget is designed to perform the action directly and whether the system requires an unlock or confirmation. If you can connect manually from Home and real traffic works, investigate the Widget layer. Check DNS, server settings, or rules only if manual connection also fails. If you no longer need the Widget, remove it from the system layout and confirm in Home that your usual settings remain in place. Removing a Widget doesn't disconnect the client or turn off On Demand; check those separately.

07 Data sync

iCloud Sync: Scope, conflicts, and recovery

iCloud Sync transfers data that the client allows to be synced between devices that support the feature. Don't assume that every configuration, subscription status, system permission, or active connection will match. After an item appears on a new device, check the active Config, current Global Routing mode, and system connection permissions. If you only need to move a readable configuration file once, first check what the app can export; you don't need to enable ongoing sync just to transfer one file.

Check three things: system, client, and data scope

First, check that each device uses the same account for iCloud and that system settings allow the app to use iCloud. Then check the sync status and supported data scope shown in Shadowrocket. System permission to access iCloud doesn't mean the client has started syncing; a sync option in the client doesn't mean every data type is included. Use the actual status shown on both devices as your baseline. If you don't need sync on one device, leave it as is. For a first test, use the device with the most complete data as the baseline, and don't reorganize data on both devices at once.

iCloud Sync and restoring a purchased app from the App Store are separate actions. The former concerns app data and cloud state; the latter concerns the app purchase record in an account. Being able to reinstall the app doesn't mean local configuration files or imported content have been restored. Check system connection permissions on the new device when prompted; don't expect them to transfer directly from the old device. For app access and data migration, follow the download page's guide to restoring a purchase, then return here to verify sync.

Back up before enabling sync; test one item first

  1. Identify which device has the most complete data. Use the options the client actually provides to save copies of configurations you need to keep, and note anything outside the export scope. Being able to export a configuration doesn't mean all state can be exported. If a file contains your server or subscription details, store it somewhere you control; don't upload it to a public location just to compare devices.
  2. First, stop editing on the other device. Check the system and app options on both devices separately. Choose a recognizable test configuration copy with no credentials. If that type of data is included in sync, check whether this single item appears. Don't delete the old file to test whether sync has started before confirming the result.
  3. After the test copy arrives on the other device, compare its contents and enabled state, and check whether you need to enable it manually. Then test access to the same target. If only the names match but the contents differ, keep both copies for now; don't rush to replace a file or repeatedly toggle sync.

Duplicate names, sync delays, and accidental deletion

Files with the same name aren't necessarily the same item, and list order doesn't tell you which one is newer. If there's a conflict, pause edits on both devices, save separate copies of the candidates you want to keep, then compare their actual contents—especially [General] and [Rule]. If sync doesn't appear to be working, first check system access, network availability, available cloud storage, and whether the test data is confirmed to be in scope. Don't start by repeatedly signing out, deleting the app, or clearing cloud data; these actions can make the original state harder to verify.

To return to the previous state, use the copy saved before the change. Don't alternate edits between devices that may still have pending changes. First establish a local baseline on one device and confirm that re-enabling the file restores normal operation. Then decide whether to resume syncing it. Finally, record which data types you've confirmed can sync and which need to be checked manually. Use this checklist when you next switch devices; don't assume that one item appearing last time means all data has been restored.

08 Local proxy access

Proxy Ports: Listening scope and minimal setup

A Proxy port in local proxy settings is the port other apps use to connect to a proxy entry point on the device. It isn't the remote port used by an imported server, or the Proxy mode in Global Routing. First check whether an app actually needs you to enter proxy settings manually. If you're just using Shadowrocket on the device, you don't need to open an extra listening endpoint for Home to connect. Changing the local port won't fix an existing connection to a remote server that's already failing.

Check the protocol, bind address, and port

First check whether the platform offers the relevant settings, then verify the local proxy protocol, listening scope, and port it shows. HTTP and SOCKS5 are different connection methods. If the app using the proxy specifies the wrong protocol, it may fail to make a valid request even if it can connect to the port. Use the default port shown in the interface; don't infer it from a remote server entry, and don't change it just to match the number on another device. If you need to change it, choose a port the client explicitly supports that isn't already in use, and update the apps that actually use this entry point.

For use on the same device, prefer a listening mode reachable only through the local loopback interface, and enter an address from the same address family in the client app. Enable local network access temporarily only if the interface explicitly allows access from other devices and you can control the test network and access scope. Don't broaden the listening scope on public or shared networks, set up public port forwarding on your router, or disable system protections for a test. If the interface doesn't offer the required binding controls, use an option with a known scope; don't guess an address.

Troubleshoot one failure point at a time

SymptomCheck first
This device can't connect to the proxy entry pointIs the listener running? Do the address families match? Is the port correct and unused?
Port is reachable, but requests failDoes the client app use the same protocol as the listener? Then check whether the target appears in Log.
Works on this device but fails from anotherListening scope, the network both devices are on, and local network isolation policies.

Run one reversible test from this device. In an app that explicitly supports manual proxy settings, note the original settings, enter the verified protocol, listening address, and port, then send one new request. If the connection can't be established, check whether the entry point is available; don't change the remote port. If the request reaches the entry point but still fails, check whether Log shows a target at the time of the test. Only after confirming that the request entered the client should you investigate the route, DNS, or remote protocol. Reaching the entry point and accessing the target are separate tests.

A loopback address used on this device can't be used by another device to reach the entry point; the other device will interpret it as its own local address. If authorized local network access is required, check the listening device's actual address on the current network and whether a guest network or organization policy isolates the two devices. An address that worked on a previous network may no longer be valid. Don't attribute a resulting failure to server settings. Follow the rules for managed networks; don't broaden access to bypass restrictions.

The interface guidance in this manual is based on iPhone / iPad. Options on Mac (Apple Silicon and Intel), Windows, Android, and Linux depend on the respective client. There are two ways to get the app: the iPhone / iPad version is available from the App Store for a one-time US$2.99 purchase; system requirements are as listed on the App Store page. The Mac / Windows / Android / Linux versions are free, with installers distributed from this site. A one-time client purchase is not a connectivity plan. This site doesn't provide, sell, or recommend proxy servers or subscriptions; use your own existing details to connect and test. See Download Shadowrocket for platform download options and system prompts.