Shadowrocket Setup Guide

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

First, identify what you have: a subscription link that provides multiple servers and can be updated, or the address, port, and authentication details for a single server. These are added to the app differently. Don't enter a subscription URL as a server address. Open Shadowrocket, go to Home, tap the add button in the top-right corner, and open Add Server. Check Type before saving; it determines which fields appear.

Have a Subscription? Use Subscribe

In Add Server, set Type to Subscribe, enter the full subscription link in URL, and add a name you can recognize. After pasting, check that the beginning, end, and query parameters are all present. Watch for spaces, line breaks, or explanatory text copied from a messaging app. Subscription links often contain access credentials, so keep the full URL intact and don't share it in forums or screenshots.

Save the details and wait for the app to retrieve and parse the subscription, then return to Home to check the result. The step is complete only when the subscription group and its servers appear; saving the subscription name alone doesn't mean the contents were retrieved. If the group has no servers, check the subscription response and validity before moving on to connecting. Updating a subscription refreshes connection details; it doesn't replace the provider's access permissions or expiration period.

Have a Single Server? Enter Its Details for the Selected Type

If you have the details for a single server, choose the matching protocol Type in Add Server, then enter the address, port, and authentication details. Required fields vary by protocol. For example, check the encryption method and password for Shadowsocks; VMess and VLESS often require a UUID; and Trojan requires a password and TLS settings. Similar-looking fields aren't interchangeable. Don't enter details for one protocol into another protocol's form.

If your provider specifies a transport method, path, Host, or SNI, enter it as described. The server address may differ from the name used for TLS verification. Don't change either just to make the form look consistent, and don't turn off certificate verification instead of checking the settings. After saving, return to Home, confirm the new server appears, and select it. This saves the details but doesn't yet confirm that the connection works.

If you have a share link or QR code, you can also import it from the clipboard or use Scan QR Code. After importing, open the entry to check its protocol and address. For scanning and import options, see Scanning and Import Management; for protocol concepts, see the Glossary. Select a specific server before choosing how to route traffic.

02 · Global Routing: Choose How Traffic Is Handled

From Home, open Global Routing and choose Config, Proxy, or Direct for your current needs. These options determine how requests are handled; they aren't protocols or speed settings. Selecting a server doesn't mean every request will use it. If the routing mode isn't what you expect, the connection switch may be on while a particular request takes a different route.

Config: Apply the Rules in the Configuration

Use Config when you need rule-based routing. Open Config and check that the configuration file you intend to use is selected, then return to Global Routing and choose Config. These are two distinct functions: the Config screen manages configuration files, while the Config option in Global Routing applies the selected configuration to requests. Importing a server subscription doesn't automatically import or enable a rule configuration.

Rules are generally matched in order, and the matching rule determines whether a request uses PROXY, DIRECT, or REJECT. If a request matches DIRECT, it may connect directly even when the connection switch is on. A request matching REJECT will be blocked. Don't infer how all requests are routed from the final rule alone. For rule examples and keyword explanations, see Rule-Based Routing.

Proxy: Check the Selected Proxy Route

When first checking whether a server works, you can temporarily select Proxy so applicable requests use the proxy route, reducing interference from rule-based routing. After selecting it, confirm the target server is selected in Home. Proxy won't fix an incorrect password, an invalid server, or transport restrictions. It changes how traffic is handled; it doesn't guarantee that the server is working.

Direct: Access Directly

Direct is for direct access, not for confirming that a proxy server is working. If Direct is selected and a page loads, that only shows the direct route works under those conditions. You can use it as a comparison when testing your local network against the proxy route, but note the selected mode each time so you don't mix results from different conditions.

After choosing a mode, return to Home and check the current Global Routing value again. Connect and run tests with this setting in mind. If you temporarily selected Proxy for troubleshooting, switch back to the Config mode you need and verify the routing results again.

03 · Home: Connect and Complete System Authorization

Back on Home, select the server you just checked, then turn on the connection switch at the top. If your subscription contains entries with similar names, check where the selection indicator is rather than relying on the most recently displayed name. After updating a subscription, check your selection again so you don't mistake another server's behavior for that of the server you tested.

The first time you connect, the system may ask for permission to add a VPN configuration. This allows the app to establish the relevant network connection; it isn't the same as buying the app or importing a subscription. Read the prompt, confirm that Shadowrocket initiated it, and complete the confirmation or authentication as required by the system. If authorization isn't complete, a switch that turns off when you return to the app doesn't by itself indicate incorrect server settings.

After authorization, return to the app and check whether the connection switch stays on. The system's VPN status and the app's enabled state can confirm that the connection mechanism has started, but neither proves that a particular service is reachable. Server authentication, DNS resolution, or rule matching can still fail while the switch is on, so continue with an actual test.

If the switch turns off immediately, first check whether system authorization is complete and whether another VPN connection is active on the device. Different VPN configurations can compete for the connection, so identify which one is currently running. Managed devices may also have organization-imposed restrictions. Follow any system prompts; don't repeatedly delete the app to try to bypass device policies.

During initial testing, leave other settings unchanged and avoid adjusting automatic connection options such as On Demand. On-demand behavior is a later preference, not a requirement for connecting manually. Once you have confirmed the manual switch, server selection, and routing mode, move on to verification. This makes it easier to identify where things first stopped working as expected.

04 · Connectivity Test: Verify Test Results and Actual Requests

Once connected, use Connectivity Test on Home to check the server. Test the selected entry first, then compare other entries if needed. This avoids losing track of which server was actually selected after running tests in bulk. Interpret each result in light of the test method: different methods check different stages, so a value from any single test doesn't prove that all services are accessible.

A response means the relevant test completed its corresponding step under those conditions. It doesn't indicate download speed or guarantee access to every service. A timeout means the test didn't complete within the waiting period, but the cause could be the server, local network, or test target. Treat one result as a clue, not a lasting verdict on the entire route. For more on test methods and sorting, see Latency Tests and Server Organization.

Next, open a website or app you need to use and repeat a simple action, such as refreshing the same page. Note whether it loads, whether only some resources fail, and what network you were using. Don't judge success only by the in-app switch or the system VPN indicator. Check whether the actual request completed as expected and took the route specified by the current mode.

When using Config, also check the matched rule and handling result in the actual request record. A request matching DIRECT doesn't mean the proxy failed; that may be exactly what the configuration specifies. If it matches REJECT, first check the rule's intent. If you suspect the rules are responsible, temporarily switch to Proxy and repeat the same request with the same server and local network, then restore Config and compare the results. Don't change servers and DNS at the same time; that makes the comparison difficult to interpret.

You can record the results in a few words: selected server name, Global Routing value, local network, action tested, and whether it worked. Don't include the full subscription URL, password, or UUID. Once the actual request works, restore your usual settings one at a time and repeat the same test after each change. This makes it easier to connect any later issue with the setting that changed.

05 · Common Issues: Check Where the Problem Occurs

Troubleshoot in stages instead of changing every setting at once. Follow this sequence to find the first failure: is the imported content complete → did the system establish the connection → did the server test respond → does the actual request match the rules? Keep your original working configuration, change one thing at a time, and repeat the same test from step four. This approach works for first-time setup and for checks after a subscription update or local network change.

Subscription Saved, but No Servers Appear

Open the subscription entry and confirm Type is set to Subscribe and URL contains the full subscription link, not your provider's account page. Check for quotation marks, spaces, or missing query parameters, and review any retrieval or parsing message from the app. Being able to open a webpage in a browser doesn't mean its response is an importable subscription. If the content is empty or access has expired, check the original link with your provider rather than trying random parameter changes.

Connection Switch Won't Stay On

First check authorization for the system VPN configuration and any device management restrictions, then check the status of other VPN connections. If the app shows a configuration error, review the configuration you most recently changed. If the system connection hasn't been established, replacing multiple servers usually won't explain the issue. Check server authentication and transport settings only after the switch stays on.

Connectivity Test Times Out and Actual Access Fails

First confirm the device can use the current network normally, then check the server address, port, password or UUID, TLS, and transport settings. A single extra character can cause authentication or a handshake to fail. Compare each field with the original details from your provider; don't rely on the server name alone. Try comparing Wi-Fi with cellular. If the result changes only with the local network, investigate that network's access conditions instead of immediately rewriting the entire configuration.

Test Responds, but Some Services Fail

Distinguish between a reachable server test and a working target service. First check Global Routing, then review the rule result and any DNS-related symptoms for the request. If it works in Proxy but fails in Config, check the selected configuration file, rule order, and policy destination first. If both modes fail, check the target service, server egress conditions, and protocol settings. Don't attribute every service-specific failure to high latency.

Issues After a Subscription Update or Network Change

After an update, check that the selected server still exists, whether its settings changed, and whether the group now contains similarly named entries. After changing networks, test the same server again instead of relying on results from the previous network. Stop repeatedly updating or switching between multiple entries. Hold one set of conditions steady and test a complete request to distinguish changes to connection details from changes in the local environment.

After confirming a basic connection, see the Server Management Manual for subscription updates, organizing multiple subscriptions, deleting servers, and backups. If you encounter an unfamiliar protocol or rule keyword, consult the Glossary before changing settings. By the end of this guide, you should be able to identify the selected server and routing mode, and verify the result with a repeatable real-world request.