Official Guide · Getting Started

Shadowrocket
Import a Subscription and Connect

Follow five steps to add a server, choose a mode, connect, and verify access. First establish a connection you can check, then adjust rules and automatic connection settings.

01 · Add Server: Add a Server or Import a Subscription

After opening Shadowrocket, stay on Home for now and do not turn on the connection switch. Check which type of information you have: a complete subscription link, or a set of parameters that includes a server address, port, protocol, and authentication details. Choose either method; there is no need to import the same information twice. If anything is missing, check with your service provider rather than guessing based on the protocol name.

Existing subscription link: choose Subscribe

On Home, tap the plus sign in the upper-right corner to open Add Server. Tap Type, choose Subscribe from the list, and paste the complete subscription link into URL. You can enter a recognizable name in Remark, such as “Everyday use,” then tap the save button in the upper-right corner. Return to Home, wait for the subscription to load, and check whether server entries appear under the relevant group. Seeing a group name does not mean its contents loaded successfully; check that the group actually contains entries.

Check the beginning and end of the link, as well as its query parameters, before and after pasting. Line breaks, trailing punctuation, or a character missed during copying can cause the import to fail. Subscription links often contain personal access credentials. Do not share the complete link or include it in a public screenshot. If your service provider gave you an account management page rather than a subscription link, ask them for the correct link.

When the existing subscription contents change, find the relevant subscription group on Home, use its update action, and check whether the entries changed. Do not start by repeatedly deleting and re-adding it. First check for an update error, confirm that the local network is working, and then check the subscription status with your service provider. Updating a subscription retrieves a list; the subsequent connection test checks the selected server. They are different operations.

Existing server parameters: fill in each field for the selected Type

For manual setup, open Add Server using the plus sign on Home, then choose the Type that matches your information, such as Shadowsocks, VMess, VLESS, or Trojan. Enter Address, Port, and the authentication fields required for that type. Enter only the address specified in your server details; do not append a webpage path. Enter the complete port, and do not mistake the port for a subscription management page for the proxy server port.

Check TLS, transport method, Host, SNI, and path values against the original details, field by field. The server address and the name used for TLS may differ; do not replace one just to make them look consistent. After saving, return to Home, confirm that the new entry has a recognizable name, and select the one you want to test. At this point, the details have been entered, but remote reachability has not been verified. If you are unsure what the fields for different types mean, consult the Quick Reference rather than switching between Types at random.

02 · Global Routing: Choose How Traffic Is Handled

Once the list is ready, tap Global Routing on Home to choose how to handle connections. The three modes are Config, Proxy, and Direct. Global Routing determines how traffic is handled, while the server selected on Home determines which connection entry is used when a proxy is needed. Selecting a server alone does not choose a mode.

Config: Follow the Current Configuration

Config handles requests according to the rules and policies in the current configuration file, making it suitable when you have specific routing requirements. Before switching, open Config in the bottom navigation and check which configuration is selected. Do not judge its contents by the filename alone, and do not assume that importing a server subscription also provides a rules configuration that meets your needs. The subscription provides server details; Config defines connection handling. Check both separately.

Rules are generally matched in order; earlier specific rules and a later FINAL rule can affect the policy ultimately used. If a rule refers to a policy name, confirm that the name exists and points to the intended target. For your first use, keep a configuration whose purpose you understand, and avoid layering many rules and DNS changes at once. For now, select and check the configuration; see Rule Keywords and Configuration Concepts for more on the keywords.

Proxy: Check the Proxy Path

Proxy can be used during troubleshooting to compare the proxy path while reducing interference from rule-based routing. Select a server to test, switch to Proxy, and test the same destination. This does not mean all types of system traffic will necessarily take exactly the same path, nor will it restore an unavailable server. After the comparison, switch back to Config if you need rule-based routing.

Direct: Establish a Local Network Baseline

Direct provides a comparison without a proxy, helping you check whether the local network itself can reach a destination. It is not the same as turning off the system VPN configuration: while the connection switch is on, the system may still show a VPN status. To end the client connection completely, return to Home and turn off the switch at the top rather than only changing Global Routing to Direct. Once you have chosen a mode, continue to authorization and connection.

03 · Home: Turn On the Connection and Authorize It

Return to Home and check that the selected server and Global Routing mode match your choices, then turn on the connection switch at the top. When establishing a connection for the first time, the system will ask to add a VPN configuration. Confirm that the prompt was triggered by your action, allow it as instructed, and authenticate with your device passcode or biometrics on the system screen. Then return to Shadowrocket. Enter your device passcode only on the system authentication screen, never in a server authentication field.

If you previously canceled authorization, turn on the switch again to start the process. If your device is managed by an organization, restrictions may prevent a VPN configuration from being added. Check the device management requirements rather than repeatedly changing server parameters. Connection authorization determines whether the client can use the system network extension; server parameters determine whether a remote connection can be established. Assess these separately.

After authorization, wait for the connection status on Home to stabilize before opening the app you want to use. A VPN indicator in the system usually means the local connection configuration is enabled, but it does not confirm that the selected server can transfer traffic or that the current rules behave as expected. Do not treat “the switch stays on” as a final check. The next step is to use Connectivity Test and check actual access.

For your first verification, use the manual switch and wait before setting up On Demand. If another VPN connection is enabled, first check for configuration conflicts and test each one under controlled conditions. To end the test, turn off the switch on Home. If the connection starts again automatically, check the On Demand triggers so you do not mistake automatic reconnection for a switch that failed to turn off.

04 · Connectivity Test: Verify Actual Access

Check a connection at three levels: whether Home shows the expected connection status, whether Connectivity Test gets a response, and whether the webpage or app you actually need works. Observe each separately. A response in one test only means that the test returned a result under those conditions; it does not guarantee sustained download speeds, access to every destination, or a stable connection later.

  1. Use Connectivity Test on Home and first check the result for the currently selected server. If the list contains multiple entries, a response from another entry does not mean the selected one is also working.
  2. Open a familiar page that should be reachable on your current network and confirm that basic access works. Then test the destination you actually need and note whether it does not open at all, only some content fails, or it loads slowly.
  3. When using Config, check the connection records or logs to see which rule and policy were applied to the destination. A system VPN indicator alone does not prove that a destination is using the proxy.
  4. To compare modes, test Proxy and Config on the same network, with the same server and destination. Change only one condition at a time, then restore your usual setup.

Webpage cache and existing long-lived connections can affect what you observe. After switching modes, reload the page or reconnect the app before comparing results. Do not judge routing only by whether one page element changes. Some services connect to multiple domains; one successful request does not mean every request used the same policy. You do not need to change the entire configuration just to verify your first connection.

If the Direct baseline, proxy path, and rule-based path have all been checked but the destination still fails, record the time, network type, selected server, and error message. These details help reproduce the conditions; do not include subscription links, passwords, or other authentication details. Once the test succeeds, keep the working selections and adjust Config or On Demand one setting at a time. If something changes, you can return to a known working state.

05 · Common Failure Points: Start with the Earliest Issue

Troubleshoot in the same order as the setup: check the list first, then the test, authorization, and actual access, and finally the rules. Change one setting at a time and test immediately, noting the result. Do not change servers, switch networks, import a configuration, and adjust DNS all at once. Even if that fixes the issue, you will not know which step made the difference.

The subscription group appears, but the server list is empty

Check that the Subscribe URL is complete and that you did not enter a login page or include extra spaces, then try updating the subscription. If an error appears, keep the error text and confirm that the device can connect to the internet. An expired link, changed content from the service provider, or an issue with the subscription status must be checked with your provider; changing Remark will not change the returned content. If existing entries still work, do not delete them in bulk before you know why.

Connectivity Test times out or gives inconsistent results

First use Direct to confirm that the local network works, then compare the result with another existing server entry. If all entries fail, check the current network, device time, and recently changed settings. If only one entry fails, first check that server's status, Address, Port, authentication, and transport parameters. Latency depends on the test method and network conditions at the time; do not judge availability from one number alone.

The switch is on, but the destination still will not open

First check Global Routing. If Direct is selected, choosing a server does not automatically route the destination through a proxy. If the destination works with Proxy but fails with Config, open Config and check rule matching, policy names, and DNS settings rather than immediately purchasing again or reinstalling the client. If both modes fail, check the server parameters, local network, and remote availability.

Some pages work, but some content keeps failing

First determine whether the issue affects only a specific domain or app, then check the rules and policies for the relevant requests. A single page may depend on multiple domains, so a partial failure does not necessarily mean the entire connection is down. Keep the current working state and adjust only one setting related to the affected destination. For DNS, rule order, or protocol field details, consult the Quick Reference before making changes rather than replacing the entire configuration and hiding the specific cause.

The connection returns after being turned off, or performance changes after switching networks

If the connection returns automatically after being turned off, open Settings and check On Demand, then check the VPN configuration status in the system. If a problem occurs after switching between Wi-Fi and mobile networks, establish a Direct baseline on each network and test the same server again; a network change may interrupt an existing connection, requiring it to be re-established. Do not ignore actual access results just to keep the switch on. After the first connection works, decide whether to enable automatic connection for your everyday use.

If you need to report an issue to your service provider, share only the necessary error message, protocol type, network conditions, and retest results. Keep the complete subscription link and authentication details private. For questions about getting Shadowrocket from the App Store, restoring a purchase, or the store region, see the Getting Shadowrocket Guide rather than mixing them with connection troubleshooting.