Shadowrocket Setup Guide
Import a Subscription and Check the Connection
Using the iPhone or iPad interface, follow these steps: add your details, choose a mode, connect, verify a request, and check for failures. First confirm that one connection works, then adjust rules.
Keep your current configuration for now; there is no need to make bulk changes. Prepare a familiar page address as a test destination. If something goes wrong, note the step where it stopped and the message shown; this makes the cause easier to identify than reinstalling repeatedly. Layouts may vary slightly between versions, so look for the corresponding entry by its English interface name.
Add Server: Add a server or import a Subscribe link
First identify the type of details you have. A subscription link, individual server parameters, and a configuration file are different kinds of input.
Open Shadowrocket and find the SERVER group below Home. Tap Add Server. On the add screen, check Type first; it determines which fields are required. The official screenshot on the right shows one server type. Different fields appearing after you change Type is normal; do not treat the fields in the screenshot as a universal form for every protocol.
Existing subscription link: Choose Subscribe
If your details include a subscription address, choose Subscribe under Type, paste the complete address into the URL field, and enter a label that is easy to recognize. Check the entire address after pasting: keep the scheme, path, and parameters after the question mark intact, and do not include line breaks, quotation marks, or explanatory text. The example https://example.com/sub?token=xxxx only illustrates the format; it is not a real subscription and does not need to be opened.
After saving, return to Home and wait for the subscription to be fetched, then check whether server entries appear in the group. A successful save only means the app stored the address; it does not confirm that remote content was downloaded. If the group is empty, check the subscription fetch message first, then confirm that the address has not expired, whether extra authentication is required, and whether the current network can reach it. Do not substitute an ordinary webpage address to test a subscription; webpage content is not a server list.
Existing single server: Fill in each field for its Type
If you have details for a single server, choose the protocol that matches them, such as Shadowsocks or Trojan, then enter Host and Port. Host is usually just a hostname or IP address, without a webpage path; enter the port from your details in Port. Then check the Password, Method, UUID, or TLS-related fields required by that type. Some fields are specific to certain protocols and cannot be substituted just because their names look similar.
Manual entry can accidentally add spaces or line breaks to a password, so check both ends after copying. If your details include a QR code, scan it using Scan QR Code and allow camera access when prompted by the system. Check the parsed Type, Host, and Port before saving. Use Import from Cloud JSON only when your existing details use the corresponding format; do not enter an arbitrary subscription or plain text.
After adding the details, return to the SERVER group and tap the server you plan to use. Confirm that the selection mark is on the intended entry. At this point, you have prepared the details but have not confirmed the system connection or rules. If the subscription contains multiple entries, select one for verification. Keep it selected; the next step is to choose how requests should be handled in Global Routing.
Global Routing: Config / Proxy / Direct
The server determines connection parameters; Global Routing determines how requests are handled.
Return to Home and tap Global Routing to check the current mode. A common first-time misunderstanding is to assume that selecting a server means all requests will use it. In practice, the Global Routing selection and the rules in the active configuration together determine the request path. Decide whether you are testing the server itself or an existing routing configuration before choosing a mode.
Config: Apply the active configuration's Rule
With Config selected, requests are checked against the active configuration's rules in order and use the policy specified by the matched rule. Open Config and confirm which configuration file is active, then open its edit screen and check Rule. General, Rule, Hosts, URL Rewrite, and HTTPS Decryption in the screenshot are separate settings sections. For an initial connection, just confirm that the relevant rules and policies exist; there is no need to enable or modify every section.
For example, DOMAIN-SUFFIX,example.com,PROXY means that requests matching the specified domain suffix use the policy named PROXY. The policy name must resolve to a valid target in the active configuration; the presence of rule text alone does not confirm that its policy reference is correct. Rules are generally checked in order, so place more specific matches appropriately and check the final FINAL fallback. Before making changes with Add Rule, consider keeping a copy of the original configuration.
Proxy: Narrow the scope of a temporary test
To first check whether the selected server can handle requests, you can temporarily choose Proxy to reduce the effect of routing rules on the test. Proxy here is a Global Routing mode, while PROXY in rule text is a policy name; do not confuse the two. Proxy can still be affected by system routing, app behavior, and existing settings, so it does not prove that every type of traffic on the device must follow the same path.
Direct: Do not use a proxy server
Direct connects to the destination directly; a selected server under SERVER does not automatically change this. If you are testing the proxy server, check whether Direct was selected by mistake. If you are comparing the device's basic network connection, Direct can serve as a reference. A destination that the basic network cannot reach does not, by itself, prove that the server is faulty.
For this test, note the selected mode. If you have a trusted configuration and understand its purpose, start with Config. If you do not yet understand the configuration, use Proxy to test the server first, then return to Config to check routing. For detailed explanations of rule order, protocol fields, and selection, see the technical reference. Keep the changes limited here to avoid introducing multiple unknowns during the first connection.
Home: Turn on the connection and allow system configuration
Check your selection before connecting. System authorization and remote server availability are separate things.
After the first two steps, return to Home and check the target server under SERVER, the mode under Global Routing, and the active configuration in Config. Avoid updating a subscription and switching multiple servers at the same time; otherwise, even if the connection recovers, it will be difficult to tell which change made a difference. If another VPN connection is active on the device, disconnect it before testing Shadowrocket.
Tap the connection switch at the top of Home. When setting up the system configuration for the first time, iPhone / iPad may show an authorization prompt to add a VPN configuration. Read the prompt, confirm that it matches the action you just initiated, allow it, and complete device authentication as required by the system. This is authorization for the device's network configuration, not a subscription password; do not enter device authentication details in Add Server.
After authorization, return to Shadowrocket and check whether the previous Not Connected status at the top changes and whether the switch stays on. The official screenshot shows Home before connection, so do not use the status shown in the image as the completion criteria. A status change only indicates that the device's connection process has progressed. In the next step, verify the remote connection and rule handling with a real request.
If the switch turns off immediately, check for a permission prompt, system configuration error, or in-app error record. If you previously denied authorization, initiate the connection again and check the system prompt. If the device is managed by an organization, its policies may restrict permissions; ask the device administrator to confirm rather than deleting unfamiliar management configurations. Repeatedly tapping the switch will not restore missing parameters and may make prompts and records harder to match.
You can leave On Demand disabled during testing so each change to the switch comes from an explicit manual action. Otherwise, the system may reconnect when conditions are met, which can look like a faulty switch. Keep the app in the foreground and complete a basic verification first, then observe what happens when switching to a browser, locking the screen, or changing networks. Do not try to judge every scenario in the first test.
At this point, the details are saved, a mode is selected, and the system connection has been initiated. Keep the server and mode unchanged, then complete the Connectivity Test and webpage checks. Continue adjusting everyday routing or on-demand connection settings only after these results are consistent.
Connectivity Test: Check results against a real request
Use Connectivity Test on Home to check the server. Results depend on the selected test method, target, and current network, so treat them as troubleshooting clues, not as a guarantee that every website and app will work. If the test fails, note the target server and the error before deleting an entry. If it succeeds, continue by making an actual request.
Make a request, then check the records
Open a browser, visit a familiar page that is working normally, and wait for a new request to complete. Avoid relying only on a cached page, and do not judge the connection by old content displayed in an app. If the page does not change, refresh it or open it again, then return to Shadowrocket and check Data or the connection records available in your version.
When checking the records, focus on whether the destination, handling policy, and time for this request match the action you just took. In Config mode, check the matched Rule in particular, and whether the final result is DIRECT, PROXY, or another defined policy. DIRECT is a valid routing result and does not necessarily indicate a failed connection. Conversely, seeing a proxy policy name does not mean the remote server returned content successfully; check error records and the actual response as well.
Compare modes to locate the issue
If a real request succeeds under Proxy but fails under Config, first check the active configuration's matching rules, policy references, and DNS-related settings. Do not start by re-entering a server password that has already been verified. If both modes fail, check the server parameters and basic network connection again. When comparing, change only Global Routing and keep the server, destination page, and network the same. Restore the mode you need after testing.
Some requests involve multiple domains. If the main page opens but images, login, or video fail, check the connections for the failed resources rather than only the domain in the address bar. App cache, existing long-lived connections, and system network settings can also affect the result; after changing rules, make a new request before checking again. If the records do not match your expectations, first note the destination and matched policy, then read the troubleshooting and rules guidance in the FAQ.
Settings: Check the failure stage instead of starting over
Find the last step that worked, then check the input, permission, or request immediately after it.
Import failure: Check the input and content format
If Subscribe cannot fetch content, check the complete URL, expiration, and authentication requirements. If it fetches content but no entries appear, check whether the response uses a supported subscription format. If manual entry fails, return to Add Server and compare Type and required fields against your original details. A successful QR code scan only means that content was parsed; check the parameters before saving. Do not post a complete subscription link when asking for help, as its parameters may grant access.
Server test failure: Check parameters and network
Open Settings and check Test Method to confirm the test target and method. A timeout from one test does not cover every real request; also use the webpage verification in the previous section. Then check Host, Port, authentication fields, and device time. For TLS, also check the server name and certificate requirements in your details. Do not hide a name or time error by disabling certificate checks.
Without changing your original settings, you can make the same request over Wi-Fi and cellular networks to see whether the issue occurs on only one basic network. After switching, wait for the system network to stabilize before testing; otherwise, a timeout during the switch may be mistaken for a persistent server failure. If multiple entries have the same issue, first check whether the device itself can reach a known working destination over a direct connection.
Switch issues or failed requests: Check Diagnostics
If the connection switch will not stay on, check system permissions and the VPN configuration. If the switch works but some requests fail, find Diagnostics in Settings and review the error records available in your version. Proxy, TCP, and UDP in the screenshot are separate settings entries, not a list of settings that must all be changed. Read the error first, then decide whether to open the corresponding section.
When documenting an issue, note the Global Routing mode, the step where the failure occurred, whether only specific destinations are affected, and whether switching the basic network changes anything. Hide subscription addresses, passwords, keys, and personal network details before sharing records. For protocol parameter explanations, see the technical reference. For common import, permission, or rule-order issues, check the FAQ; there is no need to repeat every step on this page.
Configure On Demand after basic verification
After confirming that a manual connection is stable, open On Demand and set the required trigger conditions. It controls whether to initiate a connection when conditions are met; it does not replace Global Routing rules or restore parameters for a failed server. After enabling it, check what happens when connecting to the target network, leaving that network, and turning the connection off manually. If the result differs from what you expect, disable On Demand and return to manual testing before adjusting the trigger conditions separately.
Finally, restore the mode you use day to day and keep a copy of a verified working configuration. When you later update a subscription or change rules, adjust only one category at a time and retest the same page. This makes it possible to return to the most recent working state instead of guessing all the parameters again.
