Shadowrocket Quick Start
Follow five steps to import your existing details, choose Global Routing, and check the connection. Allow about ten minutes for a first setup; the actual time depends on whether your details are complete and the current network conditions.
Follow the steps in order. Avoid changing the server, rules, and DNS at the same time. Check the result at each step before moving on. If something goes wrong, note the screen you were on and the exact error text.
Add Server: Add a server or import a subscription
Open Shadowrocket and go to Home. First identify what kind of details you have. If you have a URL that updates a server list, use Subscribe. If you have a single server's address, port, protocol, and authentication details, add it manually. Choose the method that matches your information; you do not need to use both. A subscription URL may contain access credentials, so protect it like a password. Do not post it publicly or forward it casually.
If you have a subscription link
On Home, tap the add button in the upper-right corner to open Add Server. Tap Type, choose Subscribe, and enter the full subscription link in URL. Confirm and save. When pasting, check the beginning and end of the link, especially for spaces, line breaks, or explanatory text copied along with it. Do not remove parameters after a question mark or use an account login page as the subscription URL.
Return to Home and wait for the subscription to load. Normally, the list will show the relevant group and server entries. If you see a subscription name but no selectable servers, first check that the device can access the subscription URL. Then check whether the subscription is still valid and whether its response is suitable for the app. Resolve import issues first; changing Global Routing will not fix an unreadable subscription URL.
If you have details for a single server
From Home, open Add Server and choose the protocol shown in your details under Type, such as Shadowsocks, VMess, VLESS, or Trojan. Then enter the address, port, and authentication fields one by one. Required fields vary by protocol; a password, UUID, encryption method, and TLS settings are not interchangeable. Do not guess the protocol from a similar-looking name, and do not paste an entire share string with a protocol prefix into the server address field.
If your details include a QR code, scan it using the Scan QR Code option in the app and allow camera access when prompted by the system. After scanning, check that the detected protocol and address match the original details, then save. When entering details manually, fields such as the TLS server name may differ from the connection address. Follow the original details rather than changing values to make them look consistent.
Completion check: A selectable server appears on Home, and you have selected the one you want to test. The entry name is only a label; it does not prove that the server is available. Keep the original details so you can compare them if the connection fails. For field definitions, see the Concept Reference. For protocol design and parameter explanations, see the Protocol Manual.
Global Routing: Understand the three modes
After saving the server, do not turn on the connection just yet. Tap Global Routing on Home and confirm how you want traffic handled. The three modes are Config, Proxy, and Direct. They determine how connections are handled; they do not correct server parameters or indicate the server's protocol. Before changing modes, note the currently selected value so you can restore it after testing.
| Mode | How it handles traffic | What to check during first setup |
|---|---|---|
| Config | Applies policies according to the rules in the active configuration. | Is your configuration selected in Config? |
| Proxy | Routes traffic through the proxy; useful for a temporary proxy-path check. | Is the correct server selected on Home? |
| Direct | Connects directly to the destination without forwarding through the current server. | Do not mistake successful direct access for a successful proxy test. |
To use rules, first open Config and confirm that your configuration file is selected. Then return to Global Routing and choose Config. A server subscription and a configuration file are not the same thing: the former mainly provides a server list, while the latter determines which policies match conditions such as domains and addresses. Do not assume that importing a subscription also sets up rule configuration.
If you only have server details and have not prepared a rule configuration, you can briefly use Proxy to check connectivity. This lets you see whether the server path works before mixing connection issues with rule issues. After testing, switch back to Config if that is how you plan to use your own configuration. This guide does not decide which route should be used for particular websites.
Direct can serve as a baseline for comparison, but it is not evidence of a successful proxy connection. If a webpage opens in Direct mode, that only shows that the page is available through the current direct-access path. For the next check, record the mode, selected server, and page you visit together rather than noting only whether the page opened.
Completion check: You know which mode is selected. If using Config, you have also confirmed the active configuration in Config. For rule order and the meanings of PROXY / DIRECT / REJECT and FINAL, see the Concept Reference. You do not need to change every setting during your first connection.
Home: Connection switch and system authorization
Return to Home and check the selected server and Global Routing mode once more. After confirming the details and mode, turn on the connection switch at the top of Home. The first time you connect, iPhone / iPad may show a system prompt to add a VPN configuration. Confirm that the prompt follows the action you just took, choose Allow, and complete device passcode or biometric authentication as requested by the system.
This system authorization lets the app establish a VPN configuration on the device. It is not a subscription account login or server authentication. Enter your device passcode only in the system-provided verification screen, not in the Password field under Add Server. Likewise, the server password does not unlock the device. When a prompt appears, check whether it belongs to the system or to the server form in the app.
After authorization, return to Shadowrocket and check whether the switch stays on. If a VPN indicator appears in the system status area, treat it as one indication of connection status, not proof that the destination webpage is accessible. Establishing the system configuration, reaching the server, and applying the expected rules are three separate things. The next step checks real-world access.
If the switch turns off immediately, stop tapping it repeatedly and check whether authorization is incomplete or an explicit error appears. Then check that a server is actually selected on Home and that fields such as the port and password are complete. If another VPN connection is active on the device, end it before trying again to avoid confusion about which connection is handling network traffic.
During your first manual check, leave On Demand settings unchanged. On Demand triggers a connection under specified conditions; it is not a prerequisite for every manual connection. If the connection turns back on automatically after you switch it off, then check any existing On Demand conditions. Avoid changing multiple automation settings to troubleshoot one issue.
Completion check: System authorization is complete, the connection switch on Home stays on, and there are no pending prompts. If you need to edit the current server, turn off the connection first, save the changes, and then reconnect. This makes it clear which set of parameters each test uses and makes it easier to restore the previous state if a test fails.
Connectivity Test: Compare test results with real-world access
After connecting, use Connectivity Test to check the current server, then try accessing a webpage. A test result reflects a specific probe and depends on the method, destination, and network conditions. A response does not mean every website and app will work, while a timeout should be assessed against real-world access. Do not decide whether setup is complete based on a single value.
- Check the basic network. If nothing is accessible, turn off the Shadowrocket connection and open a known-working webpage in a browser. If the basic network also fails, check Wi-Fi or cellular service before changing protocol fields in the app.
- Check the server path. Turn the connection back on and confirm the selected server has not changed, then run Connectivity Test. Note whether it responds and the network conditions during the test. Next, open the same webpage and check that new content loads rather than a previously cached page.
- Check the configuration. In Config mode, use known rules in your own configuration to check one destination expected to use PROXY and another expected to use DIRECT. The fact that both open does not prove they matched the expected policies; if needed, check the connection logs available in the app.
If access works in Proxy but not as expected in Config, check the active configuration and rules before deleting the server. Conversely, if the same server cannot provide access in either mode, check the connection path and server parameters first. Comparing modes can narrow down the issue, but avoid changing the server and network at the same time; the results will be difficult to interpret.
If Wi-Fi works but cellular does not, that is useful information. After switching networks, reconnect and test again in the new environment. Do not use an old Connectivity Test result to assess the new network. Transport conditions for some protocols may vary between networks. Check the existing server details for specific issues; one failed test does not prove the entire app configuration is broken.
Completion check: You have opened at least one webpage and can identify the server, Global Routing mode, and network used for the test. After confirming access, keep these working settings as a baseline. Use them for comparison if you later change rules or DNS. Turning on the connection switch without checking access does not complete this step.
Troubleshoot import, connection, and rules
If something fails, return to the earliest step you did not complete. Do not start by reinstalling the app: reinstalling cannot fix an expired subscription, an incorrect server password, or mismatched rules, and may make an existing configuration harder to recover. First note the error text and recent changes, then check the following in order. Change one item at a time, save, and retest against the same destination.
No server entries after import
First check that Subscribe contains the complete subscription URL, not an account homepage, help page, or note for a single server. Check whether the link was truncated or contains extra characters, and whether the subscription is still valid. A login prompt or webpage in the response cannot be used as a server list. If you have questions about the details, ask the provider of your existing service to confirm the correct URL and supported format. Do not post the full link in a public discussion.
An entry is present, but the test or connection fails
Compare Type, server address, port, and authentication fields with the original details. Then check whether TLS-related parameters were changed unintentionally. The device's date and time should also be accurate, as a time discrepancy may affect certificate verification. Do not disable certificate verification just to remove an error; first check the server name and certificate requirements. If you have another server of your own that you know works, you can compare them on the same network, but there is no need to repeatedly import unfamiliar details.
The test responds, but webpages do not open
First determine whether only one page is affected or several known-working destinations. A single failure may relate to the destination service, name resolution, or matching policy; it does not show that all connections are failing. Check whether Global Routing was left on Direct by mistake, or whether a different configuration is selected in Config. If only domain access is affected, check DNS settings. Avoid layering multiple groups of settings you do not understand.
Only Config mode behaves unexpectedly
After confirming the active configuration, check the rule order from top to bottom and the policy for the fallback rule FINAL. A broad rule placed earlier may match a request before a later, more specific rule gets a chance. A successful subscription update does not mean that configuration rules have also changed. First compare with a configuration you know works, then adjust rules one by one. See the Concept Reference for rule keywords and the Protocol Manual for protocol and transport field issues.
When troubleshooting is complete, switch from temporary Proxy mode back to the mode you plan to use, then verify access again. If you still need help narrowing down the issue, note the device system, network type, protocol, failed step, and an error description with sensitive details removed. Do not disclose passwords, full subscription URLs, or QR codes containing credentials. This preserves useful diagnostic details without exposing connection credentials.
After your first connection, keep three routine checks in mind: what is selected on Home, which mode Global Routing uses, and which configuration is active in Config. After updating an existing subscription or changing a configuration, repeat the verification in step four.