SETTINGS REFERENCE · Official Handbook

Shadowrocket Settings GuideSettings Reference

Check where a setting applies before changing it. Find out what each option does, how to check its current value, what to use, and how to roll back changes.

Use this page as a reference, not as a first-connection walkthrough. If you haven’t imported your details or connected yet, start with the user guide, then return here to review your settings. The steps below assume you already have your own subscription or server details.

Use the value shown in your current app Change one setting category at a time Verify the App Store version

01 / SCOPE

Settings scope, current values, and a safe order for changes

Shadowrocket’s behavior depends on several layers: the system network determines whether a server is reachable, the server entry defines connection parameters, Config supplies rules and related settings, Global Routing selects the current routing mode, and Settings provides app-level options. When a request fails, a switch’s position alone won’t identify the cause. First find which layer failed, then check the relevant settings.

Distinguish app settings, configuration files, and server parameters

Settings are not the same as the full contents of the active configuration file. Some behavior also depends on the Config in use, protocol capabilities, and system permissions. Options with similar names in different places do not necessarily override one another. Note the current Config name, server name, and selected Global Routing mode before reviewing an option. When comparing values, use the fields shown in your current app.

Server details usually include an address, port, authentication information, and protocol-specific fields. These define the connection endpoint and shouldn’t be changed to alter routing. Rules in Config determine which policy handles a request. Changing a server port to the local Proxy port, or treating a subscription URL as a configuration file URL, confuses different kinds of data. Even if the app lets you save the change, that doesn’t mean the connection will work.

Names and ordering on the Settings screen may vary with the current app interface. This guide keeps English names such as DNS, On Demand, Ping, and Log, but doesn’t present unverified initial states as universal defaults. A device that has been used before may retain changed or synced values, so its current values aren’t necessarily the same as the defaults on first install. For troubleshooting, record what you actually see rather than relying on memory to restore supposed defaults.

Choosing recommended values when defaults are unknown

The general recommendation is to keep settings that are known to work and change only what’s needed to address a specific issue. For server protocol parameters, use values that match your existing details exactly. For optional features such as On Demand, sync, and local listeners, confirm their purpose and scope before enabling them. These recommendations aren’t a set of numbers for everyone to copy; each choice should have a clear reason and be repeatable in testing.

Settings source	How to check current values	Recommended approach
Settings	Use the values shown in your current app	Record first; change one setting at a time
Config	Check which file is selected	Keep a copy you can restore
Add Server	Depends on the entry and protocol	Match your existing server details
System permissions	Check in system settings	Confirm the permission actually granted in the system prompt

Before making changes, write a brief note with the network type, whether you can connect, the affected destination, and your current settings. Don’t include plaintext passwords or a full subscription URL. If the issue occurs only on a particular Wi-Fi network, test on another available network first. If only one destination fails, check the matching rule. This helps distinguish a general problem from a local one and avoids using a setting that affects all requests to fix a single issue.

Make changes in a way you can roll back

Change one type of variable at a time and retest the same destination. For example, when testing DNS, leave the server, routing mode, and rules unchanged. When testing server parameters, don’t update Config at the same time. After each change, confirm it was saved; disconnect and reconnect if needed to establish a fresh connection state. If things get worse, restore the value you just recorded instead of stacking more unverified changes.

Back up the content you may actually need to restore. Saving Config alone doesn’t save server authentication details, and keeping server entries doesn’t preserve all your rules. Before exporting or copying anything, check what the current app’s action includes and save it somewhere you control. Backups may contain sensitive information, so don’t share them publicly when asking for help. Sync is not a substitute for a separate, verified backup.

Roll back from the most recent change outward: undo the latest change, check which configuration is selected, then review the server and local network. Don’t start by deleting all your data. If you need to reorganize everything, first make sure your backup opens and contains the key details, and check the App Store status for the account used to purchase the app. This guide is meant to make every change deliberate, not to make every option look tidy in one particular way.

02 / ROUTING

Global Routing: Config, Proxy, and Direct

Global Routing determines the overall handling mode for current requests. Config, Proxy, and Direct correspond to the options shown in the app. For everyday rule-based routing, use a verified Config. Proxy and Direct can help with short comparison tests, but they don’t replace correcting server parameters or prove that all app traffic has the same network conditions.

Choose a routing mode before interpreting rule results

Config means requests are handled according to the rules in the current configuration file. The file must be valid, selected, and able to resolve the policies referenced by its rules. Importing a file into the list doesn’t mean it’s active. If a rule appears to have no effect, first confirm that Global Routing is set to Config, then check which file is selected, and only then inspect the spelling and order of a particular rule.

Proxy routes requests in the proxy direction, while Direct routes them directly. “Overall” describes the routing mode; it doesn’t guarantee identical handling for every type of system traffic. System connections, special network restrictions, and protocol behavior can still affect the results. After testing, restore the original Config mode. Otherwise, you may mistake a routing-mode difference for a rule failure when reviewing logs later.

App label	Meaning	Recommended use
Config	Config	Everyday routing using verified rules
Proxy	Proxy	Briefly test whether proxy routing works
Direct	Direct	Briefly test whether a direct local connection works

Use the mode currently selected in the app; this guide doesn’t assume which mode is selected by default on a new device. If a destination works after switching modes, that only shows that the routing direction affected the result. Continue checking DNS, rule matching, and the server connection. Don’t leave all requests in a different mode without a clear reason, as this may also change access to local resources, DNS resolution paths, and connection egress.

Understand rule matching in order

Common rules are evaluated from top to bottom, and an earlier match can prevent later rules from being used. DOMAIN matches an exact domain, DOMAIN-SUFFIX matches a domain suffix, and DOMAIN-KEYWORD matches a keyword in the domain. IP-CIDR and IP-CIDR6 match address ranges. Choose the narrowest suitable rule type. Avoid broad keywords just to match one destination, as unrelated requests may then be handled by the same policy.

GEOIP uses IP address location data; it doesn’t identify the user’s location or guarantee coverage of every resource on a website. A page may request multiple domains and addresses in different regions, so a direct route for the main page doesn’t mean all its subresources are also direct. FINAL is the fallback when no earlier rule matches. When checking the outcome, include the fallback policy in your review rather than looking only at the first few visible rules.

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

The snippet above illustrates rule order and policy syntax; it isn’t a complete configuration for every situation. example.com is a demonstration domain, and PROXY and DIRECT remain unchanged as rule keywords. Review the relevant section in a copy of your existing Config. Don’t add duplicate sections or import the snippet as server details. After saving, confirm the selected file and use Log to check whether the destination matches the expected rule.

Trace a rule issue from a specific request

Start with a destination where the problem can be reproduced. Note the action and time, then check the request’s domain, address, and policy. If Log shows that an unexpected upstream rule matched, adjust that rule’s scope or order. If the request consistently falls through to FINAL, check that the destination matches the domain in the rule. Redirects, image resources, and API domains often explain why a page address is correct but a rule doesn’t match.

REJECT blocks matching requests; it doesn’t identify all content on a page. A broad domain suffix routed to REJECT may also block sign-in, images, or APIs. Record the original rule before changing it, then test the main functions rather than checking only that the page opens. For matching scope, false positives, and rollback steps, see How to write REJECT rules and understand their limits.

A good rollback approach is to keep the original file, test one rule in a copy, then decide whether to merge it based on Log. More rules don’t automatically mean more accurate routing; duplicates with no clear purpose add maintenance work. After testing, confirm that Global Routing, the active Config, and the selected server are still the intended combination. Record that combination as a baseline for future troubleshooting.

03 / NAME RESOLUTION

DNS: resolution paths, caching, and address differences

DNS resolves domain names to addresses. A connection may fail before resolution, during resolution, or after an address has been returned; changing DNS affects only some of these stages. Start with settings that are already known to work, and check DNS-related entries in Config. Use the defaults and available options shown in your current app. No public resolver is the right choice for every network.

Tell a DNS failure from a connection failure

If a request gets no usable address, check whether the resolver is reachable, the domain is valid, and the current network requires access authentication first. If an address is available but the connection times out, the cause may be routing, server status, or the destination service. A browser message such as “Can’t open the page” doesn’t distinguish these cases. Use Log entries around the same time to identify whether resolution or connection failed.

The path used to resolve a domain and the path used for the subsequent connection are related but separate. A request routed through PROXY doesn’t mean every resolution step necessarily uses the same transport direction. Likewise, DIRECT alone doesn’t reveal which resolver was used. Behavior depends on the current configuration and app options. Record “where the name is resolved” and “where the connection goes” separately instead of treating both as one vague switch.

DNS behavior may depend on both app options and configuration file contents. Open the active Config and check its DNS-related entries, then review the available DNS options and descriptions in Settings. Don’t enter different values in multiple places and guess which one takes precedence. If the sources conflict, simplify one item at a time in a copy of the configuration, reconnect, and test until you can identify what changed the result.

Choose a resolution method and check the cache

Standard DNS and encrypted DNS use different transport conditions. Encryption can change how DNS requests are protected in transit, but doesn’t automatically make resolution faster, more accurate, or reachable on your current network. If the app lets you enter a resolver, check the required format, protocol support, and actual reachability. Keep the method that works unless you have a specific need and can verify a replacement.

Caching can make a change appear to have no effect. Caches may exist in the app, system, browser, or destination service workflow, so a single refresh may not trigger every lookup again. For testing, close old pages or end existing connections, use the cache controls available in the app, and reconnect if needed. Don’t delete the entire configuration just to clear a cache, or attribute a one-off recovery to a setting you haven’t verified.

IPv4 and IPv6 can also affect what you observe. A domain may have records for both, while the local network may support connections to them differently. If only certain destinations have problems, check the address type actually used and the stage where the request failed. First confirm that the network and server support the path in use. Disabling an address family may temporarily work around an issue, but doesn’t explain or resolve its underlying cause.

Local network names and access authentication

When accessing home devices, office resources, or names that exist only on a particular network, the local DNS environment may be essential. Sending every domain through the same external resolution path can prevent these names from resolving as expected. First confirm that the device is on the right local network, then compare the results with Direct and Config. Check whether the resource requires a particular domain, address range, or permission.

Complete the access process for a Wi-Fi network with a sign-in page before testing proxy connections. If the system doesn’t yet have normal network access, changing DNS or repeatedly switching servers usually adds variables. Check whether the system shows an authentication page and test the network with a known working basic request. After signing in, restore your original configuration and reconnect so the pre-authentication and post-authentication logs aren’t mixed together.

Don’t replace the domain with its IP address just to prove DNS is working. Websites using encrypted connections often depend on the domain for certificate checks and service selection, so visiting an IP directly may produce a different error. Instead, check whether resolution returned a result, then test the connection using the original domain. Note any redirects during testing, since subsequent domains may use different DNS or rules.

Finish DNS troubleshooting with a stable setup you can explain: keep effective settings, undo changes without supporting evidence, and retest the original destination along with local resources that worked before. If only one destination still fails, check its rules and service. If all domains fail while an existing connection temporarily works, focus on the resolution path. This avoids repeating trial-and-error changes to the same option.

04 / CONNECTION LIFECYCLE

On Demand: triggers and connection lifecycle

On Demand triggers a connection when configured conditions are met; it doesn’t change server quality or rule priority. First establish a stable manual connection, then configure On Demand for your actual use case. Check the available conditions, actions, and current state in the app. Before enabling it, know when you want a connection to start, when it should stay disconnected, and what should happen after a network change.

Establish a reliable manual connection first

For now, don’t rely on automatic triggers. In Home, confirm the selected server, Global Routing mode, and active Config, then connect manually. If the system asks to add a VPN configuration, verify the source and follow the system prompt. Granting permission only allows the system to establish the connection; it doesn’t confirm that the server details are correct or that a destination is reachable. Test access and review Log as well.

If a manual connection isn’t stable, On Demand will only repeat an unstable process automatically. Fix authentication, DNS, or routing issues before setting triggers. Otherwise, repeated connect-and-disconnect behavior may look like an On Demand problem. Check in this order: network access, server details, a reliable manual connection, correct rule results, and finally whether the automation conditions behave as expected.

Don’t judge connection quality from the system status bar icon alone. An icon or app switch can indicate connection status, but not whether every request succeeds. Check separately that the connection is established, a specific destination is reachable, Log shows new requests, and the expected policy is in use. Keeping these results separate helps distinguish “the connection wasn’t triggered” from “the connection is up but access fails.”

Conditions and manual disconnects

If the current interface lets you set actions based on network type or conditions, read each condition carefully and configure only networks you actually use. Similar Wi-Fi names don’t necessarily mean the networks are equally trustworthy; don’t judge security by name alone. Start with a small number of clear, easy-to-test conditions rather than adding many that overlap. Check how conditions interact in the current app and verify the behavior in practice.

If the connection comes back after you manually disconnect, check whether an active trigger remains in On Demand. Turning off the connection once doesn’t necessarily disable automation. If you need to stay disconnected, first address the relevant On Demand conditions, then confirm the connection state. When restoring your usual setup after testing, review both the conditions and the connection switch so you don’t leave one changed by accident.

A network change may interrupt an existing connection and require a new one. A task already in progress may not continue on the new network, so one brief failure doesn’t prove the rules are broken. Wait until the network has normal access, start a new request, and check the timeline in Log. If every network switch leads to ongoing failures, reconnect manually first and compare that with automatic recovery to narrow down the cause.

Lock screen, background activity, and system limits

The connection doesn’t necessarily stop when the app is no longer in the foreground, and an open app doesn’t mean the system network state remains unchanged. Locking the screen, network changes, and system resource management can all affect what you observe. Test a repeatable scenario, such as reopening the same destination after locking the screen, and note whether you need to reconnect. Don’t assume one background behavior will be the same on every device.

Assess battery use alongside session length, data transferred, signal quality, and how often the connection is re-established. Ongoing transfers, weak signal, and frequent reconnects can all affect power use; On Demand being on or off alone doesn’t explain it. For comparison, keep the network, server, and task as consistent as possible and observe a longer period. Battery changes after rapidly switching several settings usually aren’t enough to identify the cause.

If the connection conflicts with another system network configuration, first check which connections and management restrictions are actually active in system settings. Managed devices may have organization-defined restrictions; deleting configurations at random isn’t a safe fix. Test only within your control and keep a record of the original settings. Confirm the purpose of unfamiliar system configurations before changing them, so you don’t interrupt network access you need.

After configuring On Demand, verify at least three states: it connects during normal startup, behaves as expected after a network change, and stays in the intended state when disconnected. If any result is unexpected, simplify the conditions instead of adding compensating rules. For use at a fixed time, connecting manually is also a clear option. Automation should reduce repetitive steps, not create states that are hard to explain.

05 / DIAGNOSTICS

Ping, Connectivity Test, and Log

Ping and Connectivity Test check reachability under particular test conditions; Log records what happens during operation. A test result doesn’t guarantee ongoing availability or directly measure real-world throughput. Use tests as clues: identify the test target and method, then compare with actual access and Log. Check the test method, target, and default options in your current app.

Understand what’s being tested, not just the number

A test may check whether a server port is reachable, or whether a full request to a destination works through a proxy. Those results aren’t directly comparable. The first can succeed while authentication or the destination connection later fails; the second can fail because its test destination is temporarily unavailable. Before testing, check the current method and its description. Don’t assume every number labeled as latency measures the same network round trip.

A lower test time doesn’t mean faster downloads. Real-world speed also depends on local signal, available bandwidth, server load, transport protocol, and destination service limits. For a useful comparison, use the same network and test method at similar times, and check whether results are consistent across a few tests. Don’t choose based on one unusually fast result or delete an entry after a single timeout. First check whether the same result can be reproduced.

Before testing, confirm the correct server entry is selected, especially when notes are similar or entries are duplicated. A subscription update may change the list, so an old note isn’t a substitute for checking current parameters. If the list test succeeds but a live connection fails, record when and what you tested. Check whether both used the same entry, routing mode, and network instead of assuming the test is inaccurate.

Use Log to trace a failed request

The most useful unit in Log is one repeatable action, not the entire screen. Note the time, make one specific request, then find the domain, address, rule, and error around that time. The fields available depend on what the current app shows. If the log is long, narrow down the test rather than opening several pages at once, since background requests and subresources make it harder to identify the relevant event.

First identify the stage where the request failed: did the domain resolve, did a policy match, did the server connection establish, did authentication succeed, and did the destination respond? Keep error text exactly as shown; don’t assume every timeout has the same cause. A timeout can occur at different layers, while a refused connection and an authentication failure call for different checks. Interpret the error using nearby events and the specific destination instead of reading only the last line.

What you observe	What it doesn’t prove	What to check next
Low test time	Real transfers will be faster	Keep conditions consistent and test a real task
No DNS result	The server is necessarily unavailable	Check DNS and the local network first
The expected rule matched	The connection will necessarily succeed	Check connection and authentication next
Only one destination fails	The entire configuration is broken	Check the destination domain, rules, and response

An address or domain in Log doesn’t mean the corresponding content was transferred successfully. It may record only a DNS lookup, connection attempt, or rule match. Likewise, not seeing the expected entry doesn’t necessarily mean the app didn’t handle the request; filters, logging scope, or a request that was never sent may be involved. First check the log view’s filters, then make a new, specific request to see whether entries are updating.

Keep only the diagnostic details you need

Before asking for help, remove passwords, authentication tokens, full subscription URLs, and records that reveal personal usage habits. Server addresses, notes, and visited domains can also be sensitive, so keep only what’s relevant. You can describe the issue, for example: “Manual connection fails on the same network with an authentication error,” and share a few redacted lines. There’s no need to publish the entire configuration or log, and never send the full subscription URL.

Detailed logging may use more storage and add noise. Enable it only when needed, using the controls available in the current app, and restore the previous state after troubleshooting. Use the log level and initial state shown in the app; don’t leave every detail on just to collect as much as possible. Before clearing logs, keep the excerpts needed to resolve the issue. Then test again so old errors aren’t mistaken for new ones.

When connections are slow, check the local network, protocol parameters, connection status, and server load one layer at a time. Change one condition per test and record how a real task behaves. For a more complete comparison, see A step-by-step guide to troubleshooting slow connections. Test results only describe conditions at the time; they don’t predict future reliability and shouldn’t be used to evaluate or recommend connection services.

After troubleshooting, record the conditions that resolved the issue: what changed, its original value, the destination used for testing, and whether you retested on another network. Undo changes that didn’t help and restore any temporarily changed Global Routing mode. This gives you a known baseline for the next similar issue, instead of another round of undocumented tweaks. The purpose of Log is to reduce variables, not increase the number of steps.

06 / CONFIGURATION DATA

Data boundaries: Subscribe, Add Server, and Config

Subscribe manages subscription details you already have, Add Server adds server entries, and Config manages configuration files. These are related but not interchangeable. First identify what kind of information you have, then choose the appropriate entry point. Don’t use the same import method just because two items both look like links. Check the available fields and import options in the app; server parameters should match the details you already have.

Check subscription updates separately from the active configuration

A subscription usually provides and updates a set of server entries, but that doesn’t mean it includes complete routing rules. After importing, check what was actually added: whether the entry count changed as expected, notes look right, and any parsing errors appeared. Then separately confirm which Config is in use and the selected Global Routing mode. A server in the list only means connection details are available; it doesn’t mean rules have been selected.

A subscription URL may contain information that identifies you, so protect it like a password. When copying it, avoid extra spaces, line breaks, or explanatory text. Don’t put the full URL in a note after pasting. If an update fails, check that the URL is still valid and test access on your current network. Don’t submit it to an unfamiliar website. If you’re unsure how updates work or what they contain, check the details provided with your existing service.

Before updating, note which entry is in use; afterward, check that it still points to the intended server. Entries may be added, removed, or renamed, which can affect the previous selection. Use notes that help identify entries without putting passwords in their names. For duplicates, check their source and actual parameters before removing anything; identical names don’t prove they use the same endpoint.

Don’t guess Add Server parameters

When adding a server manually, its address, port, and authentication details must match the information you already have. Shadowsocks, VMess, VLESS, Trojan, WireGuard, Hysteria2, and other protocols use different fields; don’t apply one protocol’s conventions to another. Check each required field for the selected protocol, keep field names in English, and compare them with your source details. If something is missing, get the correct information instead of trying random values.

Transport settings, fields related to encrypted connections, and certificate names can affect the handshake. A reachable server address doesn’t prove these fields are correct. Don’t disable certificate verification to bypass an error or assume every access failure is caused by a password. Record the original error, then check the domain, system time, authentication details, and protocol requirements. A failed security check needs investigation; changing a switch to “connected” isn’t the goal.

QR code imports still need to be checked. Scan QR Code can reduce typing, but it doesn’t replace verifying the parameters, and a trusted source doesn’t guarantee the details are still valid. After importing, check the protocol, address, port, and note, and confirm you selected the right entry before connecting. If the content isn’t a data type supported by the current entry point, stop scanning it repeatedly and identify whether it’s server details, a subscription URL, or another kind of configuration.

Edit, select, and restore Config

Keep a copy before editing Config, and make local changes in the copy. A configuration may contain general settings, rules, and other sections; don’t delete existing content just to add a few rules. After saving, check for any format warning and confirm that the file is selected for use. Its position in the list, last-edited time, or display name doesn’t prove it’s active. Check the selected state in the app.

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

The example only illustrates rule syntax; the private address range shown is only an example of matching by address. Your local network may use a different range, so copying it doesn’t guarantee access to every local resource. DOMAIN and DOMAIN-SUFFIX have different matching scopes, and FINAL is the fallback. Test one specific destination before broadening a rule, then check related functions as well to avoid blocking unrelated traffic.

Updates to remote configurations may change rules, so make clear which changes are local and which come from the remote source. Before updating, identify what must be kept; afterward, check that key rules are still present. Avoid mixing a frequently updated source with many undocumented local changes, or it will be hard to tell where a change came from. Record the purpose and test method for important edits, and keep a copy that restores the last working state.

When managing multiple subscriptions, use clear notes to identify their purpose and source, and review entries before cleaning them up. Check the current app’s confirmation prompt to understand what deleting a subscription will do to the entries it created; don’t confirm until you’re sure, and avoid repeated bulk actions. For a more detailed workflow, see How to group and sort multiple subscriptions and handle duplicate entries. This guide covers managing details you already have; it doesn’t provide, sell, or recommend nodes or subscriptions.

Finish this section by keeping the three data types in their proper places: Subscribe updates existing entries, Add Server parameters match your details, and Config is selected and produces the expected rule results. If one layer fails, address it there instead of repeatedly importing everything. To follow the workflow from the beginning, return to the quick start guide and work through import, selection, connection, and verification.

07 / CONTINUITY

Widgets provide a system shortcut for viewing or triggering actions. iCloud features carry data across devices within the scope supported by the app. Neither replaces checking the actual state in the main app, and neither proves a connection succeeded. First verify everything in the main app, then add a shortcut or set up sync. Check available features, sync scope, and current defaults in the app and system; don’t assume every type of data syncs.

Check widget display separately from the actual connection

To add a widget, use the system’s widget management flow and check which Shadowrocket widgets and sizes are available on your device. Widget types and interactions depend on the system interface; don’t infer them from another device’s layout. After adding one, check the connection and selected entry in the main app, then compare the widget display. If it doesn’t update immediately, check the actual state in the app instead of tapping repeatedly and triggering multiple connection changes.

The system may control when a widget refreshes, so its display may not match the main app at every moment. If the widget looks wrong while the app connects normally, focus on its display and refresh behavior. Compare the widget before and after one clear connect or disconnect action, allowing time for the system to update it. Repeatedly changing servers or deleting configuration files usually won’t fix a widget refresh issue.

Server and configuration notes visible on the Lock Screen or Home Screen can reveal information about your usage. Name entries so they’re easy to identify without including full addresses, authentication details, or subscription URLs where they may be displayed. Consider who can see or use widgets on a shared device. Choose short, recognizable names without sensitive credentials, and check what the widget actually displays after adding it.

Understand what will sync before enabling iCloud

Before enabling sync, check your system account, iCloud availability, and the related options provided by the app. Confirm the sync scope for each type of data. “iCloud is on” doesn’t mean all servers, configurations, logs, connection states, and preferences have been saved. Test sync with a recognizable change that contains no sensitive information, then decide whether to rely on it for organizing devices. Use the current values shown in the app.

Sync carries data between devices; it isn’t a historical backup archive. An accidental deletion or incorrect change may affect other devices, so keep a separate copy of important content. Label the copy with its purpose and contents, and store it somewhere you control. Seeing a filename on a second device doesn’t prove that everything synced. Open it, verify key entries, and confirm it can be used for an actual connection.

Editing on multiple devices at once can make it hard to tell where a change came from. Choose one device to organize your data, then wait for the expected result to appear on the others before continuing. If duplicate files or differences appear, keep separate copies first and compare important fields before deleting anything. Check rule order, server parameters, and note-to-entry associations, not just filenames; matching names don’t mean matching contents.

Distinguish file imports from ongoing sync

Use the current app’s entry point and prompts to understand Import from Cloud JSON. Importing a file once doesn’t establish ongoing sync, and successfully reading a file doesn’t mean every field applies to your device. Check the file type and source before importing; afterward, inspect what was actually created or changed. Don’t assume the file extension tells you it contains server entries, and don’t overwrite a working configuration with data from an unknown source.

System network permission usually needs to be checked on each device. Permission granted on one device doesn’t mean another device is authorized. When connecting for the first time on a new device, follow the system prompts and recheck the local network, server, and rules. App purchase eligibility and compatibility are listed on the App Store page. Seeing synced data and meeting a device’s operating requirements are separate things to verify.

If synced data doesn’t appear, first check the system account and network status on both devices, then review the relevant in-app options. Only then decide whether to import again. Don’t turn off sync and clear cloud data before keeping a copy, or repeatedly toggle sync in the hope that it works. Change one part at a time and record what appears on the other device to distinguish a transfer delay, scope difference, or content conflict.

After setup, treat widgets and sync as shortcuts, not your only control point. When something goes wrong, return to the main app to check the connection, Global Routing mode, active Config, and selected server. Periodically confirm that backups open, visible notes don’t expose sensitive information, and outdated copies are organized. This keeps things convenient while making device state clear and verifiable.

08 / LOCAL LISTENING & REVIEW

Proxy ports, local listeners, and settings review

Proxy ports identify where a particular proxy service listens; they’re not remote server ports. Whether the app offers HTTP, SOCKS5, or other local listener options, and their defaults and operating conditions, depends on what the current app shows. If you have no specific need, keep the existing settings. Don’t guess a fixed port or change listener parameters in an attempt to improve speed.

Distinguish remote server ports from local listener ports

The port in Add Server usually connects to a remote server you already have details for, so it must match those details. A local Proxy port lets eligible requests connect to a proxy endpoint on the device. These are different ports in different places. Changing the local port won’t change the remote service’s listening port or fix a remote authentication error. Before troubleshooting, identify which port you’re editing and record its associated address.

A proxy endpoint requires an address, port, and protocol; knowing the port number alone isn’t enough to connect. Using HTTP with an endpoint that only supports SOCKS5, or combining a remote address with a local listener port, can cause failures. Configure only what the current app supports and your actual use requires. Don’t treat commonly seen numbers as defaults or use the size of a port number as a performance measure.

The listening address determines which sources may be able to reach the endpoint. An address limited to the device and one available to the local network have different scopes. If the current interface offers these options, read the description before choosing. A broader listening scope may let other devices on the same network attempt a connection, so confirm the access boundary and authentication capabilities. Without a clear need for access from other devices, keep the scope as narrow as possible and close any temporary access after testing.

Check operating conditions, conflicts, and reachability

Whether a local listener works may depend on the app’s connection state, enabled features, and system network conditions. First confirm that the app is running as expected, then check the address and protocol from the device that needs to use the proxy. A saved port doesn’t prove the listener is active at all times. Likewise, working on the same device doesn’t prove other devices can reach it; these tests use different paths.

If you see a port-in-use or binding error, save the exact message and check whether another service is using the same listening endpoint. A port being within the valid numeric range doesn’t mean it’s suitable for this purpose; system limits and existing services may prevent it from binding. Choose an available value for a clear reason, then confirm it saves and takes effect. Don’t hide the cause of a conflict by entering random numbers repeatedly.

Local network access also depends on whether devices are on a mutually reachable network, whether Wi-Fi isolates clients, and whether an address has changed. A guest network may allow internet access while blocking direct communication between devices. First test basic connectivity, then check the Proxy endpoint. Not every failure is caused by Shadowrocket. Be careful on shared networks and restore the original access scope after temporary testing.

Check	How to handle current values	Recommended approach
Remote server port	Use the details for your existing server	Match the remote service exactly
Local Proxy port	Use the values shown in your current app	Choose one that meets the need and isn’t already in use
Listening address	Use the values shown in your current app	Keep the access scope as narrow as necessary
Endpoint protocol	Check what the current app supports	Match the configuration on the client device

Review changes and know how to restore them

After changing a port, test each layer in order: whether the endpoint is reachable, the protocol matches, the request reaches the app, routing behaves as expected, and the destination responds. Success at one layer doesn’t guarantee success at the next. For example, if the request reaches the app but the destination times out, check the server connection and rules. If the endpoint can’t be reached at all, start with listener status and network scope rather than immediately replacing the remote server.

Use the same review checklist for any Settings change: record the original value, state the reason for the change, change one variable, test a fixed destination, check Log, verify features that previously worked, keep changes that help, and undo the rest. If there’s no clear improvement, restore the original value first. A small set of understandable settings is usually easier to maintain than a growing collection of switches that might be useful.

An app update doesn’t mean you need to redo every setting. Check that commonly used options and key workflows still behave as expected. Updates are managed through the App Store; check the store listing and current app interface for specific changes rather than relying on old screenshots. First test your usual connection, configuration selection, and any essential On Demand behavior. If something differs, keep your existing data and review the settings one at a time instead of clearing everything and starting over.

Finish by recording a reproducible setup: the network used, the Config, the server entry, the Global Routing mode, and any Settings you changed. You don’t need to include real credentials, but the record should let you recreate the same conditions. For unresolved issues, return to the relevant section. For first-time steps, see the user guide; for purchases and device requirements, see the App Store page. Each page has a distinct purpose.