Official ManualSettings Reference
Shadowrocket Settings Guide
Already imported your own subscription or server details and want to know what a setting affects? Use this page as a reference to learn when to keep the current value, when to change it, and how to verify the result. If you haven't made your first connection yet, follow the import, mode selection and connection steps in the Getting Started Guide, then return to the relevant section here.
Interface labels primarily refer to the iPhone / iPad app. Options and navigation may differ on Mac, Windows, Android and Linux; follow what you see in your current client. To identify which layer may be causing an issue, jump to the troubleshooting steps in Log.
Settings and Global Routing
Know where each setting takes effect
If you changed a setting but nothing changed in the connection, first check which of these four states you changed. Settings controls client settings and system integration. Home shows whether you're connected, the selected server and the current Global Routing mode. Files in Config can define rules, policies and DNS settings. The system VPN configuration handles permissions required to connect. Opening a file in the editor doesn't make it the active config; editing a server entry doesn't mean it's selected on Home.
When checking a “default” value, distinguish the initial state after installation from the value in effect after importing or restoring settings, and from the recommended starting point in this guide. Existing settings, synced data and the active config can all affect the result. If the client doesn't identify a default, don't infer it from a screenshot of another device, and there's no need to clear existing settings to test. Note the displayed value, current network, mode and config name first. This baseline gives you something to compare against after each change.
Choose a mode based on what you're testing
| Interface label | Mode | Best for testing |
|---|---|---|
Config | Config | How current rules match and which policy handles each request. |
Proxy | Proxy | Whether the current proxy route can complete a request without relying on rule selection. |
Direct | Direct | Whether the same destination is reachable on the current network without a proxy route. |
For everyday split routing, use Config and confirm which file is active. The other two modes are useful for comparison, but aren't interchangeable fixes. Direct doesn't mean the system VPN is off; disconnecting changes more conditions. Test only with a destination known to allow direct access, not a service that requires a specific route. Compare results on the same device, network and destination, then switch back to your original mode. Don't change networks or servers while switching modes. See Proxy Modes for details.
Understand config rule order
[Rule]
DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
FINAL,PROXY
This .conf snippet illustrates how to read rules; it isn't a complete file to replace your current config. The first rule matches example.com and its subdomains. The second checks a geographic IP database against the destination IP, not the website's language or domain suffix. The final line handles requests that didn't match earlier rules. In a real config, PROXY must map to an available proxy policy. If a broad rule comes before an exception, the exception may never match. Moving the fallback rule higher can also prevent later rules from taking effect.
To troubleshoot a single website, find the actual hostname in Log and compare it with your rules; don't rely only on the browser's address bar. A page may also request separate domains for login, media and static assets. The main document matching the expected policy doesn't mean its dependencies do too. If an external source maintains the config, first check whether a refresh will overwrite local edits. To test a change, keep the original file and edit one rule in a recoverable copy. Then make sure you've selected the copy, not the original.
Keep a record you can reproduce
Record the result before the change, the single change made, the result afterward and how to revert it. Test one change at a time so you can tell what fixed the issue.
For example, if a webpage loads but sign-in fails, keep the current server and network, reproduce the issue in Config, and note the approximate time and policy for the failed request. Then test your current network with a destination known to allow direct access. Edit the config only after confirming a rule mismatch. If the connection switch won't stay on, check connection permissions before changing FINAL. If Home shows you're connected but the issue appears only after switching networks, keep the config as is and check the On Demand conditions on this page.
When moving between platforms, look for the same feature rather than expecting it in the same place. Get the iPhone / iPad app from the App Store product page for a one-time payment of $2.99; check the App Store page for system requirements. The Mac (Apple silicon / Intel), Windows, Android and Linux versions are free; get installers from this site's downloads for all platforms. A one-time app purchase is not a service plan. This site doesn't provide, sell or recommend servers or subscriptions; the guidance below assumes you already have your own connection details.
DNS: Choose a resolver and troubleshoot failures
Identify which name needs resolving
A connection may involve at least two different names: the hostname of your existing server and the destination domain the website or app wants to reach. If the server hostname can't be resolved, the proxy route may never be established. If the destination name fails, your server test may succeed while a particular service remains unreachable. Whether the destination is resolved on your device or upstream depends on the selected route, protocol and config; a single DNS field doesn't tell the whole story. Identify which name and step failed before checking the server address, resolver or rules.
A good starting point is to keep the DNS setup that's already working. If you don't have a specific need, there's no reason to fill in a field just because it's there. If the active config already defines DNS settings, note those separately from the system's network settings. “Use the current network,” “set explicitly in the config” and “resolve upstream over the selected route” are different behaviors; a blank field doesn't necessarily mean a fixed address is in use. When comparing devices, confirm they're using the same config and comparable networks instead of comparing fields that merely look alike.
Keep public and internal names separate
A home router's local domain, an organization's internal domain and public domains may be answered by different resolvers. Replacing all existing DNS settings with a public resolver can make public websites work while printers or internal sites disappear. If your network needs internal access, test with a destination specified by its administrator and keep the original settings. Successful resolution doesn't guarantee a usable result: the same internal name may return different addresses on different networks, and an address returned by an external resolver may not be correct for the internal service.
If your existing config requires DoH or DoT, use the format it specifies and verify the endpoint, protocol and network reachability. If the encrypted DNS endpoint itself is a hostname, it may need to be resolved before a connection can be established. Switching to an encrypted endpoint won't automatically fix lookups if the initial resolution path is unavailable. Don't mask certificate errors by weakening validation. Check the system date and time, endpoint spelling and network first, then review the required settings. To revert, restore both the resolver type and address; don't restore just one.
Distinguish timeouts, empty answers and unreachable addresses
| Symptom | Check first | Don't assume |
|---|---|---|
| Query timed out | Whether the resolver is reachable from the current network and its hostname resolves. | The destination domain doesn't exist. |
| No record found | Hostname spelling, public or internal resolver, and requested record type. | The connection switch is broken. |
| An address is returned, but the connection still fails | Whether the address is reachable, which rule was selected and what connection error followed. | Changing resolvers will fix it. |
A and AAAA records return IPv4 and IPv6 addresses respectively. Finding one doesn't mean the other route works. If the issue occurs only on certain network types, note which address family the failed connection used. Don't disable an entire address family right away; first determine whether the record is missing, the returned address has no usable route, or the app is taking too long to switch between addresses. Keep the original hostname when testing. Replacing a website URL with an IP can change TLS verification and how the server identifies the request, so it isn't an equivalent test.
Change one thing at a time and account for caching
First record the original DNS setup. On the same network, make requests to one reliable public destination and one destination that actually fails. Change only the setting you're testing, then start a new connection and try again. If the client requires you to reapply the config, do so first; if the app is reusing an existing connection, close the relevant pages and reopen them. The system, client and app may all cache earlier results, so seeing an old address immediately after saving doesn't by itself prove the new setting failed. Comparing the time and visible resolution result of a new request is more reliable than rapidly switching settings back and forth.
Domain rules determine which policy handles a request; DNS determines which address a name resolves to. They can affect each other, but they don't establish the same thing.
If public domains work again but internal access gets worse, the new DNS setup isn't suitable as a global replacement. If several websites work but one app fails, check the actual names it requests in Log and consider whether it uses its own DNS behavior. When documenting the issue, record only the symptoms, network type, DNS setup and a redacted error; don't publish a list of internal domains. If testing produces no repeatable improvement, restore the original settings rather than turning a one-off success into a permanent configuration.
On Demand: Triggers, exceptions and battery life
It controls when a connection is attempted, not how requests are routed
On Demand determines whether the system tries to establish a connection when its conditions are met. Global Routing determines how requests are routed after the connection is handling traffic. They aren't interchangeable: changing DOMAIN-SUFFIX won't change the system's trigger conditions, and enabling On Demand won't fix a rule that sends traffic to the wrong policy. If a destination still fails after you connect manually from Home, get the manual connection working before testing automatic triggers; otherwise, issues at the two layers can mask each other.
For the first setup, keep manual connection available, note the current toggle state, and decide whether you need On Demand. Don't mistake this guide's suggestion to turn it off temporarily for the default on every device, especially if settings were migrated from another device or a VPN configuration is already on the system. After enabling it, check the state in both the app and system settings to make sure you're looking at the same connection. If the system asks to authorize a VPN configuration, confirm the prompt was triggered by the action you just took. See VPN configuration permissions for details.
Start with one condition and test both match and no-match cases
First write down a scenario where you want the connection to trigger, such as starting a request after switching from your usual Wi-Fi network to cellular. Also specify a scenario where you don't want it to trigger, such as remaining on a designated local network. Set a condition only if it's clearly available in the current interface; don't copy conditions from another device or platform. Once configured, observe the non-matching scenario first, then enter the matching one and open the same non-sensitive test destination. Finally, return to the starting network. Each time, note whether a connection was attempted, whether it actually connected, and what happened after leaving the condition.
An automatic connection attempt won't necessarily happen as soon as the screen wakes or the network changes. The system may wait for an actual request to apply the condition, and the network may still be authenticating or switching. If you can't check while the screen is locked, compare the Home status, network type and request log after waking; don't rely on the status bar alone to infer second-by-second timing. For a lock-screen test, first complete a comparison with the screen on and record a known-good result. That gives you a basis for deciding whether the locked screen is the relevant difference.
Handle hotspot sign-in, repeated reconnects and manual disconnects
Public Wi-Fi networks that require a sign-in page may restrict normal access until authentication is complete. If the connection keeps retrying and the sign-in page won't load, temporarily disable On Demand, disconnect, authenticate using the network's usual process, then test the connection manually. Restore the original setting after leaving the network. Don't create a broad, permanent exception just to connect to one hotspot. This can look much like an unavailable server, but if the same config works as soon as you leave the hotspot, check hotspot authentication first.
If the connection comes back shortly after a manual disconnect, check whether the trigger conditions still apply and whether a new request was made. If you only want to pause automatic triggers, changing the relevant condition or disabling the feature is more effective than repeatedly disconnecting. If it never triggers, confirm system authorization is in place, the network is stable and the conditions match, then make a controlled request. Don't rebuild the system configuration and change servers at the same time; if the issue clears, you won't know whether authorization, conditions or the network was responsible.
Compare behavior instead of judging by the toggle label
On Demand won't necessarily save power for every usage pattern. Frequent network changes, repeated reconnects and intensive testing can offset the benefit of spending less time connected. First check foreground and background activity in system battery usage, then compare two similar time periods: one with manual connection and one where only On Demand changes. Keep testing frequency, network type and everyday app use as similar as possible, and note how often and when connections are rebuilt. A brief reading or one anomaly on a weak signal isn't enough to judge long-term impact.
The right setting depends on how you use it: if you connect occasionally, keep manual control; if you need a consistent trigger, keep only the minimum conditions you've verified; if networks change frequently, address authentication or reconnect issues rather than adding conditions and hoping for the best. If power use doesn't change after reverting, also check Ping testing and other background activity. For a more complete comparison, see troubleshooting On Demand and background battery use.
Ping and Connectivity Test: How to read the results
Know whether you're measuring a response, a handshake or a real request
Ping is often used as shorthand for latency testing, but interpret the displayed time in light of the actual test. If the selected option measures a host response, it shows the time for that probe to reach the host and return. A test that establishes a connection or accesses a specified address may also include DNS resolution, a handshake or application-layer processing. Don't assume every result is ICMP based on its label, and don't mistake a single probe's time in milliseconds for download speed. Before comparing devices, confirm the test type, destination and timing scope are the same.
Connectivity Test helps determine whether the route used by the current test can complete a controlled request. Start with the default or a test destination already known to work. If the client allows you to change it, choose a stable address with a small response that doesn't require sign-in or redirect to an authentication page. Don't use your subscription URL or business admin site as a test destination. For the first test, record the destination, network, server and time. If you change the destination later, the results describe different conditions and can't be directly compared for latency changes.
Control the variables when retesting
On the same network, run a few tests against the same existing server details. Record success and approximate variation instead of selecting the lowest reading. The first test may include extra cold-start overhead, while later tests may reuse DNS results or a connection. After switching networks, wait until the system finishes connecting before testing; avoid treating reconnection time as steady-state latency. If the device is transferring large files in the background, retest when it's idle so local queuing doesn't look like a remote issue.
To compare Wi-Fi with cellular, keep the server, mode and test destination fixed. To compare two existing servers, keep the network and destination fixed. Don't combine both experiments in one round. If a test times out, check whether it was an isolated event or can be reproduced. If it happens repeatedly, check whether ordinary access works on the same network and whether the destination itself is reachable. For a brief outage, success rate and the stage where the error occurs are usually more informative than a difference of a few milliseconds.
Compare test results with actual access
| Result combination | What it tells you | Next step |
|---|---|---|
| Test succeeds, service fails | The route used for that test can complete its probe. | Check the service's DNS, matched policy and connection errors. |
| Test times out, service works | The test destination or probe may differ from the service. | Check the test destination and whether it responds to this type of probe. |
| Both keep timing out | There may be a shared issue, but its location isn't clear yet. | Check the current network, server resolution and connection authorization in order. |
If the test address is reachable but the service still loads slowly, consider the number of page requests, the destination's response time and whether the active rules select the same route. A small-response probe covers only part of a connection; it can't tell you about sustained throughput, upload stability or long-lived connections. Conversely, a host may ignore one type of probe and still serve an app normally. The most useful check is a non-sensitive request that resembles your actual usage, after confirming the current mode and selected item.
Test frequency and timeout: Separate troubleshooting from everyday use
For everyday use, keep the current test destination and timeout, and test manually when you need to check the status. If the interface offers periodic checks, don't shorten the interval without a clear need. Frequently testing multiple existing servers adds requests and can increase connection activity on weak signals or when switching networks. A timeout that's too short may mark a congested but usable route as failed too soon; one that's too long slows each comparison. Note the original value before changing it. Check the failing destination first, then decide whether to extend the wait only while troubleshooting.
After troubleshooting, restore the test frequency and any temporary destination. Keep the conclusion, not a diagnostic process that runs continuously. If only periodic tests increased background activity, disabling extra checks doesn't mean you need to change routing rules. If the test destination works again but the service still fails, don't keep watching latency rankings; check the real requests from the same time in Log. A note such as “test succeeds, service fails” is more useful to revisit than “latency normal.”
Log and Data: Pinpoint an issue with a single reproduction
Start with a known time and an identifiable request
Log shows the connections and errors the client records. Entries vary by system, settings and connection stage. Before reproducing the issue, note the current mode, network, selected server and destination to open. Then note when you start the request. Open the page you're investigating once and stop when it succeeds, times out or shows an error. Find the related entries from that time; don't mistake earlier automatic updates, preconnections or activity from another foreground app for this issue. If filtering is available, narrow the results by time and destination first.
For everyday use, keep the client's current log level. If you need more detail and the interface offers the option, enable it only briefly and restore the original level when done. No entry after a disconnect doesn't necessarily mean nothing went wrong: the system may not have authorized the connection, the app may have reused an existing connection, or the destination may never have made a request. First check the Home connection status and what you just did in the app. If the connection switch can't establish a connection, check system permissions instead of continually increasing the log level.
Use the last successful stage as your boundary
Check whether the server resolved and connected, then review the destination name and matched rule, followed by the proxy handshake, destination connection or app response. The interface may not show each stage separately, so draw conclusions only from visible evidence. For example, a rule match means the rule was processed; it doesn't prove the destination returned a response. A connection timeout doesn't necessarily mean authentication failed. If the log shows both successes and failures, confirm they're for the same host, not separate requests made in parallel while the page loaded.
If errors occur during authentication or TLS, check the server address, port, protocol settings and system date and time against your existing connection details. Don't disable verification because the log shows a generic failure, and don't confuse the destination address with the server address. If the same mode and DNS setup produce repeatable results but the server connection still fails, share the briefest error summary with whoever provided your connection details. If the issue occurs only in Config while comparison modes work, check rule order, dependent domains and destination policies before replacing the server.
Data and system traffic stats aren't the same accounting
Traffic counters in Data show the traffic recorded by the client. Before interpreting them, check the displayed time range, what is being counted and the units. Numbers from different devices, networks or reporting periods can't be subtracted directly. The system may count by app or cellular period, and your service provider may use a different scope. A discrepancy alone doesn't prove a rule is wrong. To investigate it, make sure you're comparing the same period and route, and check whether other requests or retries are included.
To check whether an access produced traffic visible to the client, there's no need to clear your history. Note the counter, pause other downloads that could interfere, make one controlled visit to a small page, then check the increase. If there's no obvious change, consider whether the page was cached or never made a request. An increase doesn't mean every page resource finished loading. To investigate a sudden rise in traffic, first check background sync, media requests and connection retries from that period, then use Log to identify the specific activity.
Keep a minimal record and redact it before sharing
A record usually needs only the network type, mode, time range, failure stage and brief error summary. Don't paste a full subscription, config or unredacted log.
When describing an issue publicly, replace your domains, server addresses and local addresses with examples that don't correspond to real devices. Remove subscription query parameters, account details, passwords and keys. Also check screenshot edges, notifications, config titles and share links; they can expose network or account information too. To compare requests, label different destinations “Destination A” and “Destination B” while keeping their original order. This explains the issue without exposing a complete traffic history.
After troubleshooting, restore the temporary log level, return to the original config and run one brief retest. If the issue occurs only on a particular network, include that condition in your conclusion. Don't describe a one-off result as a confirmed general cause. Next time, start with the same destination and mode instead of collecting a full log from scratch. If the connection won't start at all, read the system VPN configuration guide; it's more useful than reviewing large amounts of unrelated traffic.
Widget: A displayed status doesn't verify the connection
Distinguish the setting, system component and actual connection
Widget provides a status view outside the main app. What it displays and whether it can perform an action depend on the system's widget capabilities and the types the client provides. Don't assume from its name that it offers the same controls as Home. The related setting in the client and whether the system has added the widget to a page are also separate: changing an app setting doesn't add it automatically, and removing it from a system page doesn't disconnect the current connection or remove the system VPN configuration.
A good starting point is to confirm that manual connection is stable on Home before deciding whether to add a widget. Use the system's widget list and the actual preview as your guide; don't treat a particular layout or visible field as the default on every device. If the system doesn't show the widget, first check that the main app opens, then look for the available locations and widget types on your device. Don't delete your config just to make a widget appear; a missing widget and a config resolution failure are different issues.
Use two comparisons to check whether the status is just delayed
For the first comparison, connect manually on the same network. Confirm Home shows a connection and complete a test request, noting the config and server used. Leave the app to view the widget, allow time for the system to refresh, then return to the main app and check again. For the second comparison, disconnect while you can control the state, then compare the same three places. If Home and the actual request agree while only the widget is slow to update, treat it as a display issue first; there's no need to change DNS or the rules file.
If the system's widget supports connection controls, tap once and check for a change in the main app; don't keep tapping just because the display still shows the previous state. If the widget only displays information, or requires unlocking or opening the main app to act, that doesn't mean the connection failed. When reproducing the issue, note whether you had just locked the screen, returned the app to the foreground or switched networks. The system may refresh the widget later, so seeing an old status and the connection remaining unchanged can both be true. Run the first comparison on the same network before checking network-switching behavior.
Check interactions between automatic connections and widget status
If the widget shows a recent disconnect but Home shows that you're connected again, first check whether On Demand still matches the current conditions. Another app may have made a request after the disconnect, prompting the system to reconnect. To test the widget display specifically, note your automatic trigger conditions and temporarily disable On Demand at a time when this won't disrupt essential access. Compare one manual connection and one manual disconnect. Restore the original conditions afterward; don't leave automatic connection disabled permanently just to remove a variable from the test.
If Home itself can't connect, troubleshoot the actual connection in this order: authorization, network, server. Treat the widget status as supplementary information only. If only the widget continues to show an old status, reopen the main app to confirm, then remove and re-add the widget if the system allows it. Check whether it updates on the same network. You're replacing the widget, not the subscription or system configuration. If the current system doesn't offer that widget type, use Home to check status instead.
Choose where to place it based on what's visible
Check what the widget actually displays before placing it somewhere other people might see. Pay particular attention to server notes, config names and traffic details; even an internal name can reveal information about your network. If the interface lets you limit what appears, keep only the status or shortcut. If you can't control what it shows, move it to a more appropriate page or remove it from that location. Before sharing a widget screenshot, also check notes and other details using the guidance in the Log section.
Keep a widget if it saves you a step in everyday use. To confirm whether a destination is reachable now or which rule actually matched, return to Home, check the status and make a real request to the same destination. Check Log if needed. If a brief discrepancy appears only after switching networks, record it as a refresh-timing issue unless there's separate evidence of a connection failure. This avoids repeatedly changing settings because of an outdated status card, or treating a widget that looks normal as proof of a successful connection.
iCloud sync: What syncs and what to check on a new device
Check synced data, imported files and system authorization separately
To decide whether iCloud sync fits your needs, first confirm which items the current client explicitly supports. Saving a config file in a file location, importing and selecting it in Config, and seeing it appear on another device through app sync are three different states. Even when an item syncs successfully, don't assume system connection authorization, Widget placement or the current network has migrated. Seeing a file with the same name on another device doesn't confirm its contents or whether it's selected.
Recommended approach: keep your current settings on one device. Before using multiple devices, check their iCloud sign-in status and the system's access settings for the app, then review the sync scope offered by the client. If the interface doesn't list a type of data, treat its sync status as unconfirmed; don't assume that servers, configs, rules and logs all sync. The initial toggle state doesn't prove what's in the cloud either. Enabling it allows or starts the feature; check the visible result on the other device to confirm completion.
Set a clear baseline and avoid editing on both devices at once
Before starting, choose which device holds the correct config. Note its filename, key rules, selected policy and network conditions, and keep a copy of your config somewhere you control. For an initial test, use a test file without connection credentials or a recognizable, non-sensitive note, but only if the client explicitly supports that type of content. On the other device, check the result while it has a normal network connection. Confirm it's the expected item, not an older copy that happens to have the same name.
If both devices have been edited, stop making changes for now. Check which rules need to be kept in each version, keep recoverable copies, then choose one as the baseline. The file at the top of a list isn't necessarily the newest, and conflicts aren't guaranteed to merge automatically. After making a change, check once on the baseline device, then on the other device. If you still can't tell versions apart, temporarily give existing copies clearly different names. That's easier than repeatedly editing items with the same name.
If sync is delayed, check scope and status step by step
First check whether all data is missing or just one file. If nothing appears, check the system account, app access settings, network and available storage. If only one item is missing, check whether it's in the sync scope, stored only locally or not yet visible in the relevant list on the other device. Keep the settings unchanged while you wait; don't rapidly toggle sync. Each change introduces another state and makes it harder to tell whether the original sync was still pending or a new action changed its scope.
If the interface offers Import from Cloud JSON, treat it as an import action through that entry. Don't assume that seeing this label means continuous sync or automatic refresh is enabled. After importing, check which item was imported, whether it's selected and whether it can connect over the current network. If you've received updated subscription details from your own provider, check separately whether the subscription content refreshed and whether the change reached the other device. Testing both will show whether the issue is refresh or sync.
Verify a new device after migration; check what will be deleted before cleanup
After moving to a new device, open the main app to check that the expected config is present, verify the server notes and current selection, then complete connection authorization if prompted. Connect manually from Home and test actual access before restoring On Demand and widget settings suited to the new device. The old device's Wi-Fi conditions may not apply to the new one; seeing the same config doesn't mean both devices use the same routing mode. Keep a working copy on the old device until you've verified a real connection on the new one.
Before disabling sync or cleaning up an old device, read the system and client prompts to see what will happen: stop sync on this device, remove a local copy or delete a cloud item. If the scope isn't clear, don't test by deleting an item on a device that's still syncing. Store files containing personal server details only in accounts and locations you trust, not a public shared location as a temporary transfer point. Sync provides a way to access data across devices; it isn't a separate backup and can't guarantee recovery after an accidental deletion.
Proxy port: Distinguish the local listener from the remote service
Three similar labels, three different purposes
Proxy in Global Routing is a routing mode. The port in Add Server is the service port on your existing remote server. If your platform provides a local Proxy listener setting, its port lets programs explicitly configured to use a proxy connect to your device. The client still chooses the remote route according to its actual mode and config. All three relate to proxies, but their addresses and ports aren't interchangeable.
If you use Shadowrocket normally on this device and no other program needs to connect explicitly to a local proxy, keep the current listener setting. Don't enable a listener just to troubleshoot a remote server issue. If a local app does need an explicit proxy, first check that your platform offers the required listener type and address. Use the default port shown in the interface; don't guess based on another platform or a sample file. Seeing the same port number doesn't mean the system automatically routes requests through Shadowrocket.
For most uses, restrict access to this device
If the listener is for apps on the same device, choose a loopback address if the interface lets you select its scope, such as IPv4 127.0.0.1. For a service explicitly listening on the IPv6 loopback address, use ::1. The address, port and protocol in the calling app must match. A loopback address entered on another device points to that device, not this one; don't expand the listener to your local network just because an app on this device needs it.
Don't disable the system firewall, change router port forwarding or expose a local service to networks that don't need access just to make a port appear available. On a shared network, a listener open to more than necessary can expose the port to other devices. If your work requires cross-device access, ask the network administrator to confirm the authorized scope and access controls. The recommendations and checks in this section apply only to your own local apps. If your platform doesn't offer this feature, don't change system networking to simulate a listener.
Check the listener, protocol and upstream in order
Keep the remote server settings unchanged. Check that the address and port in the calling app match the active listener. If the client reports that the port is in use, check whether another program already uses it; don't terminate an unfamiliar system process. Choose a port allowed by the system that isn't in use, update the same value in the calling app, then make one controlled request. If the calling app still points to an old proxy address, changing the client won't change where that app sends traffic.
If the local connection is immediately refused, check that the listener is running, the address family is correct and the calling app is using the specified port. If it reaches the local listener but reports a protocol error, check whether the app is configured for HTTP proxy or SOCKS5; changing the port alone won't change the protocol. If the local handshake succeeds but the destination is still unreachable, check the upstream connection, DNS and destination policy in Log. This distinguishes a request that never reached the local listener from one that failed afterward, without re-entering all your connection details.
Test both ways after a change, then restore temporary settings
Make a non-sensitive request from an app configured to use the local proxy and check whether the client logs a request at that time. Then remove the temporary proxy setting from that app alone, or restore its previous inherited setting, and visit the same destination again. If the device's VPN is still on, the second request may still be handled by the current routing mode. Check whether it still went through the listener you just configured; don't judge only by whether the page opens. If needed, check the app's own network indicator and whether it reused an existing connection.
When reverting, check the calling app, Shadowrocket's listener and the system proxy settings separately. Undo each change made in this test without changing the original remote port or credentials. If other apps fail after you turn off the temporary listener, find which app still points to that port rather than leaving the listener enabled permanently to hide the symptom. For another test, notes on the address scope, protocol, port and purpose are enough. If you haven't established a working basic connection yet, return to the Getting Started Guide to check the main setup first, then test the local listener.