Shadowrocket Settings Guide Find the right value for your connection

First, identify which layer controls the setting

Shadowrocket’s connection behavior isn’t determined by Settings alone. The selected server in Home determines the connection’s exit point; Global Routing determines whether a destination is handled by rules; the active file in Config supplies rules and some network parameters; and Settings contains options such as tests, connection helpers, and app preferences. System VPN permission, network conditions, and background scheduling also play a part. Keep these layers separate when troubleshooting. For example, changing DNS repeatedly won’t fix invalid server credentials, and Direct mode can’t tell you whether a PROXY rule is correct.

A “default value” is the initial value in a specific environment; the “current value” is what the interface shows now; the “active value” is what the connection actually uses. They may differ. An imported Config can change the effective DNS path, while edits to a file that isn’t selected won’t affect the current connection. Before following a recommendation here, check that the option exists on your platform, then verify the in-app description, selected Config, and active connection. Don’t rely on an old screenshot alone.

Keep a record you can restore

Before making changes, record the network type, server name, Global Routing mode, Config filename, and fields you plan to edit. Keep a copy of existing configurations. Give subscription-generated files and manually maintained files separate names; include their purpose, not account details or full addresses. If an export contains server passwords, subscription parameters, or identity information, store it somewhere you control. Redact these fields in screenshots, especially credentials that appear in an address bar as ordinary query parameters.

Change one thing at a time, with an observable goal. For example, “the same domain resolves after changing DNS” is easier to verify than “improve the network.” “It no longer connects automatically when I return to Wi-Fi” is more precise than “disable background activity.” Choose one destination that worked before as a control and one that has an issue. If both fail, check the network and connection first. If only the problem destination fails, check its rules, resolution, and service before resetting all settings.

Recommended starting point and rollback conditions

Keep settings that already work as your baseline. Don’t enable an option just because its name sounds more advanced. If you haven’t established a stable connection, start with the requirements of your existing configuration and avoid extra automation and manual overrides. Save changes, then disconnect and reconnect as the setting requires; reopening the Settings page doesn’t rebuild a network session. Retest on the same network, with the same server and destination, so you can tell whether the setting or the environment caused the change.

When a new problem appears, first revert the setting you just changed instead of adding more workarounds. If the issue remains, check for an old connection, system DNS or app caches, and network changes, then establish a fresh connection. Rollback should have clear limits: don’t clear every server, delete subscriptions, or reinstall the client just to reproduce a test result. To return to the import and first-connection workflow, follow the tutorial steps and keep systematic troubleshooting separate from getting started.

System DNS, custom DNS, and DNS over HTTPS

DNS translates domain names into addresses needed for a connection. It doesn’t replace a proxy server or fix incorrect protocol parameters. System DNS usually follows the current network’s resolver settings, making it a useful baseline for observing the network’s behavior. Custom DNS specifies a resolver, but reachability still depends on the network and configuration. DNS over HTTPS carries queries over HTTPS and also requires resolving the endpoint, establishing a connection, and validating its certificate. Before switching, confirm the issue is in name resolution rather than changing every DNS option because a webpage failed to load.

Check the current client and selected Config together to establish the default behavior. Don’t assume an empty field means “no DNS”; it may inherit system settings, use a value from the Config, or trigger built-in client behavior. Check the field’s description. If the Config already specifies DNS parameters, keep a copy before deciding whether to edit the file or the app. Use one clear source of control for each setting to avoid mismatched file and interface values—and confusion about whether a change was saved.

Recommended values depend on the network

For routine troubleshooting, keep a DNS setup that already works. If you need a custom resolver, enter an address you’ve confirmed is usable and that matches the field’s format. Traditional resolver addresses and HTTPS endpoints aren’t interchangeable: don’t paste a full URL into a field that accepts only an IP address. If the field accepts multiple values, use the separator shown in the app rather than guessing between commas, spaces, or new lines. Add one resolver at a time, verify that names resolve and destinations are reachable, then consider adding a fallback.

Internal domains are a common edge case. A printer, company service, or router hostname may only be known to the resolver on the current network. Switching everything to an external resolver can make public websites work while breaking internal names; that doesn’t mean the proxy server is faulty. Conversely, a resolver that works at home may be unreachable on hotel or office Wi-Fi. Recheck the resolution path when you change networks. If needed, preserve handling for internal names, rather than treating a setting that works on one network as a universal recommendation.

Successful resolution doesn’t guarantee access

To verify, first check whether the same domain resolves to an address, then whether the request matches the expected policy, and finally whether the destination service responds. Domain rules can match by name before connecting, while IP-based rules may depend on resolved addresses; these results aren’t interchangeable. Resolving to an IPv6 address doesn’t mean the network or server path can complete an IPv6 connection. For intermittent failures, record the address type, policy used, and actual error separately. One successful retry doesn’t prove DNS is fixed.

After a change, the system, browser, or app may temporarily retain old results in a cache. Rebuild the connection and make a new request; if needed, close and reopen the destination app to avoid reusing an old session. Don’t rapidly cycle through resolvers to compare them—caching, handshakes, and network fluctuations will get mixed together. For a fuller comparison of resolution paths, see the DNS settings technical note. To roll back, restore the original resolver and configuration source, then test an internal hostname to make sure restoring public access hasn’t affected local services.

It controls when to connect, not which rules to use

On Demand triggers connection behavior based on system network conditions. It addresses a different question from Global Routing: On Demand determines when to establish a connection; Global Routing determines which policy applies to a destination after the connection is established. Enabling On Demand won’t fill in missing server details or add missing rules to a Config. First establish a stable connection manually, then add automation. If manual connection already fails, automatic triggers will repeat the same failure and make it harder to diagnose.

Check the device’s actual display for the default switch state and any existing system configuration. “Always on” isn’t a universal recommendation. If you need manual control, keep manual connection enabled while you establish a baseline. If you genuinely need network-based connection conditions, configure them one at a time using options available in your current interface. Don’t copy steps from another device if your platform doesn’t offer the same conditions, or assume system-level automatic connection permissions are identical to an in-app switch.

Each condition should be testable on its own

Before configuring this, write down a specific goal, such as “connect manually on a specific network and trigger a connection on other networks.” If the interface supports matching Wi-Fi names, check the complete name and consider similar names, networks with the same name, and hidden networks. Matching a network name is a connection condition, not an authentication method. If you add multiple conditions, read the current interface’s guidance on priority and matching order rather than assuming the visual list order determines how the system applies them.

Test one network, one condition, and one transition at a time. Confirm behavior on the current Wi-Fi, switch to cellular, then return to the original Wi-Fi. Record the system VPN status and in-app connection status at each step. Keep the same server and Config throughout; don’t update a subscription or change servers mid-test. A system status icon only indicates tunnel-related status—it doesn’t prove a particular destination is reachable. After a trigger, make a specific request to confirm the connection and expected policy.

Captive portals, sleep, and manual disconnects

Hotel, station, and guest Wi-Fi networks may require you to sign in through a captive portal first. The network name can match a condition even though internet access isn’t ready, causing an automatic connection to time out. Complete the network’s sign-in first, then test the configured condition. Don’t assume a captive portal that won’t open means the server is down. If you temporarily turn off On Demand to sign in, record its original state and restore it afterward. When a network becomes restricted, distinguish “the system didn’t trigger” from “the connection triggered but failed.”

A locked device, an app in the background, or system power-saving behavior can change the timing you observe. Don’t conclude the configuration is wrong because nothing changed a few seconds after leaving the app, and don’t expect a guaranteed background trigger time. Whether a manual disconnect is followed by another connection depends on system conditions and configuration. If it reconnects immediately, check On Demand before repeatedly removing the VPN configuration. To stay disconnected temporarily, turn off automatic triggers first and confirm the system status so a condition-matched reconnection isn’t mistaken for a faulty switch.

To roll back, first disable the condition you just added and return to a manual connection flow you can explain. Then recheck the original server and Config. Don’t delete all system network settings; that could remove configurations used for other purposes. If manual connection works but switching on a specific network doesn’t, keep records of both states and retest under the same conditions. One condition you can reproduce reliably is better for long-term use than a set of overlapping conditions that merely looks complete.

Three modes: Config, Proxy, and Direct

Global Routing’s Config, Proxy, and Direct options correspond to three modes: follow the configuration, use a proxy, and connect directly. Config applies the selected configuration to destinations. Proxy is useful for temporarily checking how a destination behaves through the proxy path. Direct lets you observe access without the proxy path. These interface modes are different from uppercase policy keywords in rules; seeing PROXY or DIRECT in both places doesn’t make them interchangeable. Check DNS and system networking separately—a mode switch doesn’t explain the full network path.

When using existing rules, first check that Global Routing is in Config mode and the intended file is selected rather than rushing to add rules. Check Home for the current default mode and your own configuration for its default contents. If a destination works after switching to Proxy, that shows only that the two paths behave differently; it doesn’t prove a domain rule is wrong. Resolution, rule scope, or how the destination service handles the exit may also be involved. Restore the original mode after testing rather than leaving a temporary troubleshooting mode active.

Rules run top to bottom: specific matches first, fallback last

Rules are generally matched in order. Put specific exceptions before broader conditions and the final policy at the end. DOMAIN matches an exact domain, DOMAIN-SUFFIX matches a domain suffix and related subdomains, and DOMAIN-KEYWORD matches a keyword in the name. Keyword rules have a broad scope and can catch names you didn’t intend to handle, so validate them against actual request logs. IP-CIDR, IP-CIDR6, and GEOIP match address ranges or locations; don’t swap them with domain rules just because their names look similar.

This Shadowrocket .conf snippet illustrates rule order. It isn’t a complete connection configuration and contains no server details. The example domains are for demonstrating syntax, not for testing. The first rule sends a matching domain suffix through PROXY, the second sends a specified private IP range through DIRECT, the third uses GEOIP to select DIRECT, and FINAL sends remaining requests through PROXY. Choose a final policy that fits your own configuration goals; don’t mechanically replace your existing file with this snippet.

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

Prevent configuration updates from overwriting manual edits

Subscribe manages updates to your existing subscription; it doesn’t mean rules in Config files will automatically merge as expected. Check subscription-generated server details, remote configuration content, and local edits separately. If an update regenerates a file, direct edits to it may be overwritten. Keep the original file and a local test copy, then verify changes in the copy first. For rules that need ongoing maintenance, use a management method supported by the current client and decide what to check after each update. Don’t assume manual edits will be preserved in every file.

If a rule appears not to work, check four things: Is the edited Config selected? Is Global Routing set to Config? Does the request use the expected domain or address? Has an earlier rule already matched? Apps may reuse old connections or request other domains, so the browser address bar alone doesn’t show what actually matched. Save and reconnect, then find that request in Log and compare it with the rules. If it’s still unclear, test with one temporary rule of limited scope, then remove it so troubleshooting doesn’t permanently change traffic routing.

A test result isn’t a single measure of connection quality

Ping can refer to different probe processes depending on the test method. Before interpreting a result, check the selected method and target in Settings. A single time shown in a list isn’t the full load time of a real webpage. Round-trip time to a server, establishing a transport connection, completing proxy authentication, and reaching a test destination are separate stages. A successful probe only shows that the stages it covers responded. A timeout with another probe doesn’t necessarily mean the server is unusable; interpret results based on the method and a real request.

Check the current client for the actual default test method, target, and timeout. There is no single default value that applies across platforms. Keep test settings that already work so results remain comparable. If you need to change one, record the original value and why you’re changing it. If the interface lets you set a target, use one you know is reachable, responds consistently, and suits the test method. Don’t assume any homepage is an equivalent probe; a target may refuse a particular type of request and produce an apparent failure.

Timeouts, concurrency, and comparable results

A timeout that’s too short can mark a normal but slow handshake as a failure; one that’s too long can make a test run take much longer. Start with the client’s current value and adjust gradually based on repeated results on the same network instead of chasing the lowest number. A mobile network change, a recently awakened device, or a hostname that hasn’t resolved yet can add setup time to the first test; record it separately from later results. If a setting has units, check whether it uses milliseconds or seconds before changing it. Don’t copy numbers between fields without checking.

If your platform supports concurrent tests, testing too many servers at once can use network and device resources or trigger remote limits. When troubleshooting one server, test it individually first, then compare it with a small number of known-working servers. A change in ranking isn’t itself evidence of a problem; brief fluctuations can reorder results. Don’t keep changing test targets just to tidy the list. Doing so removes the shared baseline, making it impossible to tell whether the network improved or the new probe endpoint simply responds faster.

Connect test results with real access

A useful check involves three separate observations: whether the server probe succeeds, whether the connection is established, and whether the destination request completes. Run Connectivity Test for a server you already have, select it and connect, then request a fixed destination and check Log. Use the same network for all three steps and don’t update the subscription mid-test. If the probe fails but the connection and destination work, note the test settings; don’t break a working connection just to change the status shown in a list.

If a webpage loads but large file transfers are slow, probe time doesn’t measure sustained transfer performance. Throughput also depends on the destination service, network congestion, protocol parameters, and remote processing. A low time in one test doesn’t prove a long connection will be stable. For comparisons, use the same destination on your own setup and a similar time window, and record upload, download, and interruption behavior. For background on Hysteria2 transport, see the Hysteria2 technical note. Protocol explanations don’t guarantee how a particular route will perform.

After testing, restore the original target, timeout, and concurrency settings—or record why you’re keeping the change. When asking for help, share the test method, network type, whether the issue is reproducible, and whether real access works; these details are more useful than a number alone. Don’t include full subscription URLs or server credentials. If the issue only occurs on one network, keep a comparison from the same device on another network. Investigate the network conditions before concluding that all server details are invalid.

Narrow the time window before reading errors

Log breaks a connection process into observable events; collecting more text isn’t always better. Before troubleshooting, note the time, limit activity in other apps, and reproduce one specific failure once. Then check the matching records. Without a time window, background requests, system connectivity checks, and destination app retries can get mixed together. An error in the log isn’t necessarily the cause of the current issue. First check that the destination, server, time, and action correspond to your test.

Check the current Settings and platform for supported logging switches, levels, and retention behavior; don’t assume every platform offers the same options. Keep the client’s existing settings for everyday use. If you need more detail, temporarily increase the logging scope, reproduce the issue, then restore it. Long-term logging can use more storage and processing resources and accumulate sensitive context. If changing logging settings requires reconnecting, save relevant records first, then reconnect and verify so you don’t lose events that could explain the problem.

Separate resolution, connection, authentication, and destination response

Read logs in stages: start with name resolution, then check whether the remote connection was established and protocol authentication completed, and finally inspect the destination request and response. If a name won’t resolve, check DNS. Repeated connection timeouts point to the network or server’s reachability. Authentication errors call for checking your existing server details. If the destination returned content or a status, investigate its behavior. Don’t treat every timeout as the same problem: the same word can appear at different stages and require different fixes.

To diagnose rules, consider the request destination, matching rule, and policy together. A browser loading one page may also request images, scripts, and other domains, so searching only for the address-bar name isn’t enough. A request marked REJECT doesn’t necessarily break the whole page; check whether it’s an essential resource first. If a field isn’t shown in the current logs, don’t invent a value. Narrow the test to one destination, make the same request again, and check the most likely rule in Config.

Read Data values within their measurement scope

Interpret Data values alongside the current view, measurement start point, and reset actions. Server-based and app-based views answer different questions; a number in one isn’t necessarily equivalent to the same number in another. Small amounts of upload or download traffic may come from handshakes, retries, or background requests and don’t prove a webpage finished loading. An increase in total traffic doesn’t prove a destination used a particular rule. Keep the server and app fixed and observe the change during a controlled action rather than using a historical total to explain a new failure.

Before resetting statistics, confirm which scope the current button affects and save a comparison of the values. Don’t clear everything after every failure or you’ll lose the timeline. If an app or statistic isn’t listed, check platform support, whether traffic went through the current connection, and the current view; don’t invent app-level evidence. For details, see the Data traffic statistics guide. Use it alongside logs, not as a replacement for request records.

Minimize sensitive information before sharing

Logs may contain full domain names, request paths, subscription parameters, server addresses, device information, and identity fields. Share only a short excerpt relevant to the issue, and redact credentials and personally identifying details. Don’t publish a full address as ordinary text, even if it belongs to your own subscription. Stage names, error text, and relative timing are often enough. After troubleshooting, restore the original logging scope and remove exported files if needed so diagnostic material doesn’t become a long-term copy of your credentials.

Widget is a shortcut, not a network test result

Widget provides a system-level place to view or control client-related status. Its appearance, available actions, and refresh behavior depend on the device’s system and client support. It isn’t a separate connection configuration and doesn’t replace server selection in Home. If Widget says connected, confirm access with a destination request. If its status hasn’t refreshed, don’t immediately conclude that the connection has dropped. The system may limit refresh frequency, so the displayed status can lag behind network changes.

Adding Widget is a system interface choice, not a universal client default. First verify the connection in the app, then add the shortcut you need. If the system offers different sizes or actions, choose what’s useful rather than adding them all. After connecting or disconnecting, check Home and system VPN status. If On Demand conditions are still met, a manual disconnect may be followed by reconnection. Check the automatic connection conditions instead of repeatedly removing Widget.

Be clear about what you want to sync

iCloud sync can keep supported data associated across devices, but don’t assume every Setting, system permission, Widget layout, or runtime state will transfer. Check the sync interface and actual results to see what the current client supports. System VPN permission is device-specific; a server that works on one device doesn’t mean another device has the same permissions. During migration, check “the data is present” and “a connection can be established” separately.

Before enabling sync, keep a local copy of your configuration and check that the devices use the intended iCloud account, the system allows the app to use iCloud, and the network can complete the sync. The same account doesn’t mean sync has finished; system restrictions, storage, and background conditions can delay it. Check the actual switch state and data scope rather than enabling everything in a hurry to copy a few settings. If you only need one file, use an import/export method supported by the client and store sensitive contents securely.

Test sync boundaries with a single change

Start with an easy-to-recognize configuration name or ordinary preference that contains no credentials. Change it on one device and wait for it to appear on the other, confirming sync direction and scope before handling important data. Don’t edit the same file on two devices at once; it makes it hard to tell which copy you intended to keep. If conflicts or duplicates appear, stop editing and keep both versions. Compare them before choosing one rather than assuming the most recently displayed copy is complete and up to date.

If a server appears on another device but won’t connect, check that device’s network and permissions first, then verify that the server parameters are complete. Don’t immediately turn sync off and on again. Different results from the same data on two devices may be caused by system networking, DNS, or supported protocol capabilities. To restore data, use the local copy you saved and check whether restoration will sync to other devices. Understand the effects on deletion, replacement, and sync scope before proceeding; otherwise, local troubleshooting can unintentionally change data across devices.

Keep purchase restoration separate from configuration sync

For iPhone / iPad, follow the restore purchases instructions on the download page. Having a configuration in iCloud doesn’t restore a store purchase, and restoring the app doesn’t guarantee local data is complete. The iPhone / iPad version is a one-time $2.99 App Store purchase; the Mac, Windows, Android, and Linux versions are free. An app purchase and your existing server details are separate. Keep a configuration copy before switching devices, verify permissions afterward, then see restore purchases and reinstall instructions so store account and data processes don’t get mixed up.

Local access and remote server ports are different

First distinguish the purposes of Proxy ports. The port in Add Server belongs to your existing remote server details; a local proxy listening port is an entry point the client provides to other programs. Both are ports, but their values aren’t interchangeable. Enter the remote port from your existing server details and make the local port match the program that uses it. Check the current Settings to see whether your platform offers a local HTTP, SOCKS5, or other entry point and whether it requires a separate switch. Don’t assume every platform is the same.

There’s no universally recommended listening address or port across platforms; check the current value and app guidance first. If you use the local proxy only on the same device, prefer a scope that allows access only from that device. Don’t listen on the local network without a clear need. To allow other devices to connect, confirm the client supports it, the system network permits it, and access control and authentication are configured. Expanding the listening scope doesn’t just make connecting easier—it can expose the entry point to other devices on the same network. Decide who can connect and how to stop providing access.

Match the address, protocol, and port as a set

A program using a local entry point must have the correct protocol, address, and port. An HTTP entry point isn’t a SOCKS5 entry point just because the port number is the same; a remote server address can’t replace the local listening address. A device connecting to its own loopback address follows a different path from another device connecting to its LAN address. If the second device uses its own loopback address, it reaches itself—not the device running Shadowrocket. When troubleshooting, identify the requesting device first, then the device hosting the entry point.

A port conflict usually means the listener can’t start or another local program receives the request. Before changing the port, record the original and check that the new port isn’t in use. Update every program that uses the entry point, then test again. If you change only one end, the client may be working while the caller still requests the old entry point. After stopping the local proxy, restore the caller’s proxy settings too; otherwise it may keep trying a closed port, making the whole system network seem broken.

Choose checks based on the scope of the failure

If every app fails, check basic network access, system VPN status, the selected server, and authentication details first. If only programs using the local entry point fail, check the protocol, listening address, port, and access scope. If only one destination fails, check DNS, Global Routing, and the matching rule. This approach avoids unrelated changes. If another device on the LAN can’t reach the entry point, also check whether both devices are on the same network, guest isolation, and the system firewall. A successful remote server test doesn’t prove the LAN entry point should be reachable.

A full rollback isn’t the same as resetting everything. Undo the latest change first, restore the original Global Routing mode and Config, then check DNS and On Demand, and finally check whether the caller still has local proxy settings. After restoring each layer, make the same destination request. Stop once you find where the result changes. If the issue remains at baseline, keep a short relevant Log excerpt and the test conditions, then check whether your existing subscription was updated or server details changed. Don’t delete everything and hope for the best.

If you need to reinstall or switch platforms, use the all-platform downloads and read the installation approval guide. On Windows, verify the source and follow the SmartScreen prompt. On Mac, verify the source and follow the prompts under Privacy & Security. On Android, grant the required installation-source permission when prompted. After installing, restore basic connectivity using the quick-start guide, then restore these settings one at a time. For mode differences, see the proxy modes guide. Don’t keep temporary troubleshooting values as permanent settings.