Official Manual / First Connection
Import a Shadowrocket Subscription
and Connect for the First Time
Start with an existing configuration and follow the steps to add it, choose Global Routing, connect, and verify. Check the result of each step before moving on to avoid changing multiple settings at once.
01 / IMPORT
Add Server: Add a Server or Import a Subscription
Open Shadowrocket and stay on Home. SERVER below lists available servers; an empty list is normal if you have not added any details yet. First identify what you have: a set of Host, Port, and authentication details is for a single server, while a complete address used to retrieve a set of servers is a subscription link. These are imported differently. Do not enter a full subscription link in Host.
Have a subscription link? Select Subscribe
On Home, tap Add Server. On the add screen, tap Type and select Subscribe. Enter your full subscription link in the URL field. If there is a notes field, use it to label the source. After pasting, check for leading or trailing spaces and line breaks. In particular, make sure you have not omitted any parameters after the question mark. These parameters may be needed to identify your subscription access; without them, the link may return an error or no content even if it looks almost right.
Save and return to Home. Wait for the subscription content to load, then check whether entries appear under SERVER. If you see a subscription name but no servers, first check the result as described in Step 5. Do not immediately import the same address repeatedly. To refresh a subscription later, update the existing entry. Importing it again may create multiple similar groups and make it harder to tell which one is selected.
Have individual server details? Fill in the fields for the Type
When you open Add Server again, choose the Type that matches the protocol provided by your service provider. For Shadowsocks, for example, enter Host, Port, Password, and Method as provided. Host usually contains only a domain name or IP address; enter Port in its separate field. Do not put explanatory text, a web page path, or an entire share string in Host. Other protocols may show different fields; use the fields displayed for that Type and the details you were given rather than copying a field combination from a screenshot.
If you have a compatible QR code, use Scan QR Code on the add screen, then check that the detected Type and address are correct. Import from Cloud JSON is for the corresponding JSON import; it is not a general-purpose entry point for arbitrary subscription links. After saving, return to Home and confirm that the new entry can be selected. This only confirms that the details were added to the app; it does not prove the server is usable. Next, decide how traffic should be handled.
Subscription links, QR codes, and authentication fields may contain access credentials. Before sharing a screenshot for help, hide the complete address and authentication details. You do not need to share your entire configuration to troubleshoot.
02 / ROUTING
Global Routing: Choose Config, Proxy, or Direct
Once the server appears on Home, tap Global Routing to check how traffic is currently handled. This setting determines the route for traffic; it does not fill in server details or correct authentication errors. The three modes are Config, Proxy, and Direct. Before connecting for the first time, understand which mode is selected so you can interpret the test results that follow.
Config: Match requests against the current configuration
Config uses the active configuration to decide whether requests use DIRECT, a proxy policy, or another action. Open Config to view configuration files; within a file, sections such as General, Rule, and Hosts manage different settings. Add Rule in the screenshot is for adding a rule, not a server. When you first use the app, confirm which file is active. If you already have a configuration, save a copy before making changes; avoid rewriting an entire rule set while testing a server.
For example, DOMAIN-SUFFIX,example.com,DIRECT matches the domain and its subdomains, then uses DIRECT. Rules are generally checked in order, so earlier matches affect subsequent handling. FINAL is the fallback policy when no earlier rule matches. If the configuration uses policy names, also confirm that each policy points to a valid target. Having a rule file does not mean every policy it references is correctly connected.
Proxy and Direct: Compare traffic routes
Proxy sends eligible traffic through the selected proxy and is useful for briefly checking whether a request can complete through that server. It does not mean that every type of traffic on the device will necessarily use the proxy; behavior also depends on app capabilities and the system network. Direct connects directly. Even with the connection switch on, Direct does not prove that requests are being carried by the selected server.
Make a note of the current mode. If you know the source and purpose of your configuration, you can leave Config selected. To isolate the effect of rules, temporarily switch to Proxy for comparison, then restore Config when testing is complete. Do not treat Proxy as a fix for every issue. For protocol fields and technical trade-offs, see the protocol guide. This page focuses on completing the connection process.
03 / CONNECTION
Home: Select a Server and Connect
Return to Home and select the server you want to use under SERVER. Confirm that the entry shows a selection indicator. A subscription name is only a way to organize entries; seeing a group does not mean you have selected an actual server. If the list is long, note the selected entry's label so you can compare it clearly if you switch servers later. Then check that the Global Routing mode matches your choice in Step 2.
Tap the connection switch at the top of Home. The first time you connect, the system asks whether to allow a VPN configuration to be added. This authorization is required to establish a system network connection. Confirm that the request was triggered by your action, allow it, and follow the device prompts to authenticate with your passcode or system authentication. If you cancel midway, return to the app and check its status. A server appearing in the list does not mean system authorization is complete.
After authorization, return to Home and check whether the status at the top changes from Not Connected. If it remains Not Connected or the switch quickly turns off again, check system authorization and any app prompts first rather than changing Rule. If another VPN connection is active on the device or a device management policy applies, the system may not establish this connection as expected. Confirm that the device allows this VPN configuration, then try again.
Once the connection is established, do not immediately switch between multiple entries or enable On Demand at the same time. Keep one server, one mode, and the same network for the next verification step. The status at the top mainly indicates that a system connection has been established; it does not by itself prove that remote authentication, the target service, and every rule are working. Treat “connection switch is on” and “request succeeded” as separate checks to avoid unnecessary repeated changes.
04 / VERIFICATION
Connectivity Test: Check Connectivity and Rules Separately
Once connected, tap Connectivity Test on Home and wait for it to finish. It checks connectivity under the current conditions, but its test target may differ from the service you actually use. One successful test does not mean every website or app is accessible. Likewise, interpret a failure in light of the test method, current network, and target service status; do not delete a subscription based on one result alone.
First, check whether the target request completes
Open a browser or the app you need and visit a service you are authorized to use and whose expected behavior you know. Where possible, make a new request instead of relying on a cached page. If the test succeeds but the target still fails, note whether the domain cannot be resolved, the connection times out, or the service returns a login or permission message. These occur at different stages; a response from the service itself is not necessarily a proxy connection failure.
Then, check which route the request took
To confirm whether Config is taking effect, review the available request records and check the domain, matched rule, and final policy for the same target. A page loading under DIRECT does not mean the request went through the server. Conversely, a request matching a proxy policy does not guarantee that the remote destination will accept it. If the expected domain is missing from the records, make the request again and check whether it was served from cache or whether the app used a different domain.
If the result is unclear, keep the server and network unchanged, temporarily switch Config to Proxy, and visit the same target again. If Proxy works but Config does not, check rule order, policy references, and DNS-related settings first. If neither works, recheck server details, remote status, and network conditions. After comparing, restore the original mode, note the symptoms and changes, and continue with the checks in the next step.
05 / DIAGNOSTICS
Settings: Check Settings by Failure Stage
Start troubleshooting at the earliest step that failed. If the server details have not been retrieved yet, there is no need to investigate rules. If the connection is established but a particular target has an issue, focus on requests to that target. Test Method, On Demand, and Diagnostics in Settings relate to testing, on-demand connections, and diagnostics. Do not switch them all together as a set of “general fixes.” Note the original values before making changes so you can restore them afterward.
Import failure: Check the details and their format first
Make sure the subscription is entered in the appropriate Subscribe field, not Host. Check that the link is complete, contains no extra spaces, and that your subscription access is still valid. A web page opening in a browser does not mean that the address contains subscription content the app can read. If it returns a login page or an error message, check the details with your own service provider. Do not delete existing entries that still work while repeatedly trying to import the subscription.
Connection failure: Check server details and system authorization separately
If the switch will not stay on, first check that the system VPN configuration was added successfully and is not occupied by another connection. If the switch stays on but requests fail, check Type, Host, Port, and authentication fields one by one. QR code imports also need to be checked, especially if the details have changed but the QR code is out of date. An incorrect device date or time can also affect secure connections, so keep the system clock accurate. For rejected authentication or an unavailable remote server, ask your own service provider to confirm the server status.
Test results differ from actual use: Check Test Method
Review Test Method in Settings to understand which method the current test uses. Different methods measure different things, so a failed test does not necessarily mean an actual request will fail. Likewise, getting a test result does not prove that the target service is available. Return to Step 4, make an actual request to the same target, and compare the records. If you suspect the current network restricts a particular type of traffic, try another network you are authorized to use while keeping the server and mode unchanged.
Status keeps changing: Check On Demand and diagnostic records
On Demand triggers connections based on conditions. During initial troubleshooting, note its status and, if needed, temporarily disable automatic triggers. Then manually test a complete connection and disconnection to avoid automatic behavior affecting your observations. You can also review available information in Diagnostics. When reporting an issue, include the error text, steps to reproduce, and network type; hide subscription links, authentication details, and unnecessary request details.
When finished, you should be able to answer three questions: Were the details imported successfully? Was the system connection established? Which policy did the target request actually use? If any answer is uncertain, return to the relevant step and verify it rather than adding more settings. To repeat the process, return to the add and import steps. For protocol field descriptions and selection guidance, see the protocol guide.