Shadowrocket Protocol Guide

01 / Choosing a Protocol

Separate the protocol, transport, and routing

Protocol type is first a compatibility requirement and only then a performance choice. If the server uses Trojan, select Trojan in the client. Changing the type to Hysteria2 will not make the same port accept a different protocol. Imported subscriptions usually include the type, address, port, and authentication details; when editing manually, follow the server’s instructions. If you have only one working set of details, reproduce it accurately rather than picking a name that simply sounds newer.

A connection has at least four layers

Layer one is reachability: DNS resolution, the destination port, and whether the current network allows the required traffic. Layer two is transport, such as TCP, QUIC over UDP, or WebSocket over TCP. Layer three is protocol authentication and encryption, such as a password, UUID, TLS certificate, or key. Layer four is the application destination and routing policy. If an earlier layer fails, later ones usually never run. A matching rule therefore does not prove that the server handshake succeeded.

These layers can be combined, but they are not interchangeable. Some VMess or VLESS deployments add TLS and WebSocket; common Trojan deployments use TLS; Hysteria2 is based on QUIC. If imported settings show Type, TLS, Host, and Path, that does not mean you need to choose among four protocols. They are separate conditions for the same connection, and fields with the same name can mean different things in different protocols. Read each field in its protocol’s context.

Speed, battery life, and privacy are different measures

Speed includes at least initial connection time, small-request response, and sustained throughput. A protocol may download a large file quickly yet load a webpage slowly because of handshakes, DNS resolution, or a longer route. Battery use also depends on wireless signal, retransmissions, background keepalives, and device temperature. A single Connectivity Test result does not represent an entire day, and a protocol’s name cannot tell you how much power it will use. For a fair comparison, keep the server region, network, and test task as similar as possible.

Understand the scope of encryption separately. Protection between the client and proxy server does not mean the connection from that server to every destination is automatically encrypted; HTTPS on the destination site still matters. What the server can observe depends on the protocol, destination traffic, and DNS path. This guide focuses on correct configuration and measurable performance, not on presenting any protocol as a universal privacy guarantee.

Keep a known-good baseline in Shadowrocket

Before making changes, note the subscription for the entry, its current Type, and key settings; back up Config. Subscription entries may be regenerated during an update, so check whether manual changes will be overwritten. Keep experimental copies separate from everyday entries. Hide passwords, UUIDs, private keys, and subscription URLs in logs or screenshots. When sharing troubleshooting details, include only field names, the failure stage, and suitably redacted host information. Start with a confirmed working baseline so later comparisons have a reference point.

02 / Passwords & Encryption

Shadowsocks: a straightforward configuration

Shadowsocks was designed as a lightweight encrypted proxy, forwarding traffic securely between client and server without providing full virtual-network management. It typically requires an address, port, password, and encryption method, making the setup relatively straightforward. “Lightweight” describes its structure; it does not mean it will be faster on every network, or that all Shadowsocks deployments are compatible. Both sides still need to agree on the encryption method, extensions, and UDP support.

Check Method and Password together

Method determines how data is encrypted and authenticated; it is not a performance setting to switch at will. If the server uses a particular AEAD method, the client needs the same method and password. AEAD provides encryption and integrity checks; if data is altered or the key does not match, the connection may fail without displaying a clear “wrong password” message. Blaming a slow network for a failed handshake skips the most basic settings check.

Different methods may require different key material. Some derive a key from a regular password; others require a key of a specific length and encoding. Don’t assume every Password field accepts any phrase. When copying, avoid extra line breaks, full-width characters, or leading and trailing spaces. If an import link contains encoded data, let the client parse it instead of rebuilding it from the text you see. A subscription can parse successfully even if the server-side settings have changed.

Working TCP does not mean UDP works

Shadowsocks handles TCP and UDP forwarding through different data paths. A working webpage only confirms that the relevant TCP request completed; voice, games, or some DNS requests can still fail if UDP forwarding is unavailable. Check that the server allows UDP, the relevant client settings are enabled, the server is listening, and the network allows the traffic. If your current task does not use UDP, its results cannot assess UDP support.

Also distinguish between “the app uses UDP” and “the protocol connects to the server over UDP.” Some proxy protocols carry application data over a different transport, so the two are not equivalent. When troubleshooting Shadowsocks, specify whether webpages fail, UDP-based services fail, or all traffic fails. “The server doesn’t work” combines distinct problems and makes diagnosis harder.

How to assess whether it suits iOS

Fewer settings usually mean fewer items to check when entering details manually, but mobile performance still depends on server load and the wireless link. Encryption overhead may be lower when the device has suitable hardware support for the algorithm, but everyday battery use is often driven more by sustained transfers, weak signals, and retransmissions. Don’t focus on CPU algorithms while overlooking the difference between cellular reception and Wi-Fi in the same room.

If you already have a server with clearly specified Shadowsocks settings and mainly use common TCP apps, it can serve as a baseline. If the first request fails after a long idle period, distinguish a recycled connection from a DNS change or a server issue before changing Method. If the deployment requires an extension, check whether the client provides the corresponding field. If it doesn’t, ask your service provider rather than borrowing Host or Path settings from another protocol.

03 / Separating Identity from Transport

VMess / VLESS: similar names, not interchangeable

VMess combines user authentication, proxy requests, and data protection within one protocol mechanism, and can use different transport methods. VLESS has a more minimal protocol layer and relies more on an external security layer or the deployment’s security setup to protect the connection. Both often use UUIDs to identify users, which can make them look interchangeable if you change only Type. They are not: the server’s listening protocol and associated transport must match, and sharing a UUID does not fix a protocol mismatch.

A UUID is not a server address or transport setting

A UUID is an authentication credential used to identify a user. Copy it in full; don’t shorten it because it looks long. Address and Port specify the connection endpoint, UUID identifies the account, and settings such as TLS and WebSocket determine how the request is carried. Record these separately when troubleshooting. That helps avoid repeatedly pasting the UUID while overlooking the actual port being used.

VMess authentication depends on time, so a significantly incorrect device clock can cause connection problems. Enable automatic date and time in system settings and check the time zone before changing advanced authentication options. Keep any additional subscription fields required by the server’s current configuration. Copying defaults from an old guide may let the import succeed while the connection fails. VLESS is not an “authentication-free” mode; it still requires identity verification, but organizes it differently.

Why WebSocket Host and Path matter

When a server accepts requests over WebSocket, Path often determines which endpoint is matched, while Host may be used for HTTP host routing. Match the Path’s capitalization, leading slash, and contents to the deployment. Host is not a field where entering any website domain will improve speed. If the server does not use WebSocket, enabling it turns an otherwise valid connection into an incompatible request.

TLS Server Name is generally used for server name indication and certificate name verification; it is not automatically the same as the WebSocket Host. They may match in many deployments, but they serve different layers. Address can be an IP while Server Name remains the domain on the certificate; alternatively, all fields may use the same domain. Follow the exact combination provided for the server. Don’t remove a field just because its value looks repeated in another setting.

Evaluate speed and battery use for the actual combination

“VMess speed” is not a single fixed value. The number of handshakes and route can vary with direct TCP, WebSocket, or additional relays. If the first visit is slow but downloads work normally once connected, check DNS, TLS, and the transport endpoint before blaming the encryption algorithm. Extra encapsulation adds some bytes and processing, but it is not necessarily the main bottleneck on a real network.

VLESS has a minimal protocol layer, but that does not guarantee lower battery use. If its server is farther away or the wireless link has more retransmissions, any savings from protocol processing may be outweighed by network costs. To compare the two, use similar server conditions and the same app task where possible, and record the first request, continued use, and recovery after backgrounding. One test before and after connecting cannot represent a full day of use.

What to check first after importing

In Home, open the entry’s edit screen and check Type, Address, Port, and UUID in order. Then review the transport, TLS, Host, Path, and any other server-required settings. Reconnect after each change so an old session doesn’t obscure the result. If several entries in the same subscription fail authentication, first check whether the subscription has updated and whether the device clock is accurate. If only one endpoint fails, focus on its unique path and certificate settings.

04 / Certificates & Identity

Trojan: check all TLS settings

Common Trojan deployments use a TLS connection to carry proxy requests, with a password to identify the user. TLS provides the protected client-to-server connection, making the certificate, server name, and system time part of the connection requirements. A configuration may appear to need only an address, port, and password, but TLS still matters. Many cases where “the password is right, but it won’t connect” fail before the server even checks the password.

Understand Address, Server Name, and certificates

Address identifies the server. Server Name typically affects TLS server name indication and certificate verification. The server may use the supplied name to select a certificate and server entry point. The client then checks whether the certificate is trusted, within its validity period, and valid for the requested name. Replacing Address with an IP without keeping the correct Server Name can reach the right machine and still fail verification.

A certificate name mismatch, incomplete certificate chain, or incorrect device clock can all cause a TLS handshake failure. First identify the stage where the error occurs. If TLS has not completed, repeatedly resetting Password won’t help. If TLS succeeds but authentication is denied, check the password, account status, and server protocol. If the error message is incomplete, test the same entry on a known-good network to distinguish a network-path issue from incorrect settings.

Don’t make disabling verification your go-to fix

Certificate verification confirms the server’s identity. Disabling it may make an error disappear temporarily, but it also removes that check and does not prove the original configuration is fixed. If the deployment uses specific trust material, follow the server’s trusted setup instructions. Don’t permanently ignore a name or certificate error just to make the connection button report success. Recording the exact error and checking the server certificate configuration is usually more useful than bypassing verification.

Connection reuse and network changes

A TLS handshake has a cost, but an established session is not the same as a first connection. Browsers and apps reuse some connections, and the system may cache DNS results, so a second page load is often faster than the first. That does not automatically mean a protocol has a special acceleration feature. For comparisons, record cold starts separately from repeat visits; don’t compare a new session with one that is already warm.

When an iPhone switches from Wi-Fi to cellular, its source address and existing connection state change. TCP sessions generally need to reconnect, so a brief pause while the page recovers can be normal. On Demand controls when a connection is triggered; it does not keep every existing TCP session intact across network changes. If recovery consistently fails, check system network permissions, the selected server, and whether the app is retrying correctly.

When it fits and what to expect

When an existing deployment provides a clear TLS name, valid certificate, and password, Trojan is relatively straightforward to verify and can be considered for common web and app traffic. Using TLS does not make it inherently faster than other options, nor does a handshake necessarily mean higher battery use. Repeated reconnects on a weak signal, server congestion, and background keepalives can consume more power in practice than a single handshake.

If only a few apps fail, investigate what each app needs rather than switching protocols immediately. Some apps require UDP; others depend on different DNS results; some requests may be sent DIRECT by a Rule. First confirm that the request is actually going through this Trojan entry, then check whether the server supports the required traffic. For a general connection-timeout checklist, see Latency Tests, Protocol Settings, and System Time: Troubleshooting Steps.

05 / General-Purpose Proxy Interfaces

HTTP / SOCKS5: forwarding and encryption boundaries

HTTP proxies originated to forward application-layer traffic and are common in browsers and managed networks. SOCKS5 provides a more general proxy negotiation and forwarding mechanism. Their advantage is a clear interface supported by many apps—not built-in end-to-end encryption. Before choosing one, find out whether the client-to-proxy connection has separate TLS or trusted-network protection, which authentication method is used, and whether UDP forwarding is needed. A username and password alone do not answer these questions.

HTTP CONNECT does not encrypt the proxy connection

An HTTP proxy can handle regular HTTP requests or use CONNECT to create a tunnel to a specified destination. When accessing an HTTPS site, the site’s TLS connection is generally established inside that tunnel. Whether negotiation between the client and proxy is encrypted is a separate matter. HTTPS on the destination site does not mean proxy credentials receive the same protection in every connection setup. Distinguish the site’s TLS from TLS used to connect to the proxy endpoint.

If the server explicitly provides an HTTP proxy endpoint protected by TLS, configure its address, port, certificate name, and authentication details as specified. Don’t enable an option just because the website URL starts with HTTPS. Conversely, enabling TLS on the client does not upgrade a regular HTTP proxy endpoint. If the two sides disagree, the handshake will often fail or the connection will close.

SOCKS5 authentication, DNS, and UDP

SOCKS5 can negotiate authentication and specify destinations by domain name or IP. Whether the domain is resolved locally or by the proxy affects the result and where a failure occurs. The actual path also depends on Shadowrocket DNS settings and routing behavior, so the protocol name alone does not tell you. Check whether the request uses a domain or IP and review the order of resolution and forwarding shown in the logs.

The SOCKS5 standard includes UDP ASSOCIATE, but not every server, account, or network provides usable UDP forwarding. A successful control connection does not guarantee that the UDP port is reachable on the current network. Regular HTTP CONNECT is generally for TCP tunnels and should not be treated as general UDP support. For voice or real-time apps, verify the server’s actual capabilities rather than inferring them from the phrase “proxy support.”

Assessing use on mobile devices

If you already have an HTTP or SOCKS5 endpoint provided by a workplace or organization, follow its setup instructions rather than replacing it just because another protocol has a different name. Mobile networks change frequently, and an organizational endpoint may accept connections only from specific networks. If it works on office Wi-Fi but not cellular, the client password is not necessarily wrong. Check which networks can access the endpoint, how its address resolves, and its authentication requirements before comparing protocol overhead.

These interfaces may have relatively simple negotiation, but actual speed still depends on the connection between the server and destination. An endpoint close to your device can still respond slowly if traffic takes a detour to a distant exit. There is also no rule that a protocol with no extra encryption always uses less battery. Repeated reconnects can wake the device, and an unsuitable keepalive policy can outweigh any savings in processing.

If authentication fails, check the server’s required method, username format, password, and account permissions in that order. If domain destinations fail while IP destinations work, investigate the DNS path. If only UDP-based apps fail, check forwarding support and network ports. Recording these as separate issues is usually more useful than repeatedly switching Global Routing.

06 / Layer 3 Tunneling

WireGuard: check keys, addresses, and routes together

WireGuard is designed as a streamlined Layer 3 encrypted tunnel. It identifies peers by public key and carries IP traffic over UDP. That differs from application proxies that forward requests, so you also need to understand tunnel addresses, peers, and routing scope. In Shadowrocket, distinguish the WireGuard peer configuration from the client’s Rules: they operate at different layers, and neither replaces the other.

Private Key and Public Key: which side uses which

The Private Key belongs to the current peer and must be kept secret. The Public Key can be shared with the peer that needs to identify it. The peer Public Key in the client configuration should identify the server; the server must, in turn, recognize the client’s Public Key. Reversing the keys or changing a private key without updating its corresponding public key prevents the handshake. Keys are not ordinary passwords and cannot be swapped just because their strings are similar in length.

If the configuration includes a Preshared Key, both sides need the same additional authentication material. Endpoint is the remote address and port, not the address inside the tunnel. Interface Address is the device’s tunnel address and should not be copied from Endpoint. The server may also restrict which source addresses a peer can use, so if the handshake succeeds but data does not flow, check address assignment too.

What Allowed IPs and Rules each do

Allowed IPs help select a peer and constrain accepted source addresses in WireGuard; they are not the same as domain rules in a regular proxy. How WireGuard is integrated into the client also affects which traffic enters the tunnel, so a full-network range does not prove that every Shadowrocket request will use it. First check the policy selected by Global Routing and Rules, then verify that the traffic sent to WireGuard matches the peer settings.

If the tunnel needs access to internal networks, check that those ranges do not conflict with addresses on the current Wi-Fi. The same private address range may exist on both a home network and a remote network, making routing ambiguous. Adjust routes based on the actual network topology; don’t simply send every local network to the remote side, as that can affect local device access and DNS.

Keepalive and battery use on mobile networks

Persistent Keepalive helps maintain a NAT mapping; it is not a download-speed switch. It can help when outside connections need to reach the peer or when the network quickly drops idle mappings. More frequent keepalives also give the wireless radio more chances to stay active. For use that initiates requests only in the foreground, don’t set an aggressive keepalive interval without evidence. First confirm that idle connections really fail to recover.

WireGuard can update a peer’s endpoint address using valid authenticated data and can adapt to some address changes. That does not mean every app session will move between networks without a pause. After switching between Wi-Fi and cellular, recovery depends on whether the new UDP path is reachable, the NAT mapping is updated, and the app retries. Check the handshake and traffic counters first to determine whether the tunnel or the app is stalled.

A larger MTU is not always better

Tunnel encapsulation adds overhead, and the path may support smaller packets than the local interface limit. An unsuitable MTU can cause small requests to work while large responses stall, or make some websites reload repeatedly. First rule out server load and packet loss, then make a documented adjustment based on the deployment instructions. Change one value at a time and retest with the same task. Don’t copy a number from a different network or blame MTU for every slow large download.

If you have a complete WireGuard configuration and need a defined tunnel range or a long-lived connection, use the original settings to establish a baseline. A regular proxy subscription does not provide enough information to infer keys, interface addresses, or routes. Choose based on the server’s actual capabilities and the task—not on the assumption that a Layer 3 tunnel is inherently more advanced than an application proxy.

07 / QUIC & Congestion Control

Hysteria2: check the UDP path first

Hysteria2 builds proxy transport on QUIC and is designed for connection performance under conditions such as packet loss and long round-trip times. QUIC runs over UDP and integrates a TLS-based secure handshake and multiplexed streams. This design handles traffic differently from a single TCP byte stream, but its benefits depend on the real network. If the current network blocks the required UDP traffic, congestion control cannot make the server reachable.

What waiting can multiplexed streams reduce?

On a TCP connection, lost data at the front must be recovered before later bytes can be delivered in order. QUIC can deliver data on separate streams more independently, reducing cross-stream waiting. Each stream still needs reliable delivery, and all streams share the underlying network capacity. Multiplexing does not eliminate the effects of packet loss, nor does it guarantee that every webpage will load faster.

QUIC still requires encryption, congestion control, and packet processing. On mobile devices, the processing and wake-up costs depend on the implementation and task. Retransmissions on a weak signal may increase battery use; a high-throughput task that finishes sooner may also reduce the time spent transferring. Compare short requests, long downloads, and recovery from idle separately rather than drawing an all-day battery conclusion from one peak download speed.

Check authentication, TLS, and obfuscation separately

A Hysteria2 entry typically includes the server address, port, authentication details, and TLS settings. Server Name must match the server certificate and endpoint configuration; keep the password or authentication string exactly as provided. If the deployment also uses obfuscation, both client and server need matching types and passwords. Obfuscation is not a feature you can turn on independently for any server; mismatched settings will affect the connection.

The protocol generation must match too. Similar names across generations do not imply the same authentication format or handshake, and changing the display name alone will not convert a connection. Use the server’s importable details where possible, and confirm that the imported Type is actually Hysteria2. If the subscription contains unfamiliar fields, don’t delete them just to make the settings look tidy. First confirm what they do and whether the client supports them.

Bandwidth settings do not buy you more speed

If the configuration includes upload, download, or congestion-control settings, first check what each field does and which units it uses. Some settings tell the algorithm what bandwidth to expect; they do not add physical capacity. Setting expectations too high can push traffic beyond what the link can handle, causing queues, packet loss, or a worse experience in other apps. Setting them too low can limit throughput. Server limits and current network bottlenecks still apply.

Available bandwidth on mobile networks varies with signal, location, and congestion. Settings suited to fixed broadband may not suit cellular. If downloads are fast but webpages become less responsive, check whether the connection is saturating the link before raising the values further. For tasks that depend on quick responses, stable queueing delay can matter more than peak throughput. Choose a protocol for the task, not for a single result in the speed test screen.

On failure, separate reachability from authentication

If the same device cannot connect on one Wi-Fi network but works immediately on cellular, check the UDP path and network policy first. If the handshake fails at the same stage on both networks, review the type, authentication, certificate, and system time. If large transfers fail after connecting, investigate packet loss, server load, and packet size. Record symptoms and each change to assess whether Hysteria2 suits the current environment; an occasional successful connection does not prove it is reliable.

08 / Testing & Decisions

Compare the same task, then troubleshoot layer by layer

Choose a protocol based on repeatable results from real tasks on the same device. First confirm that candidate settings are correct and the server is working. Then test webpage load time, continued browsing, long transfers, and recovery after idle. Change only one major factor—protocol or server—per round, and record the network, signal, and task. Servers in different regions or under different loads cannot prove that one protocol is inherently faster.

Keep Global Routing separate from protocol type

Global Routing options Config, Proxy, and Direct determine how requests are routed; they do not change the server protocol. Config routes traffic according to the active configuration’s rules; Proxy sends applicable traffic to a proxy policy; Direct connects without a proxy. Temporarily selecting Proxy can help rule out some routing differences, but it does not rewrite all system traffic, local-network exceptions, or DNS behavior. Check the actual settings and logs.

The following is a standalone Rule syntax example, not a complete configuration to replace your existing file. Rules are evaluated from top to bottom; FINAL handles requests that did not match earlier rules. Here, PROXY means the proxy policy and DIRECT means a direct connection. Back up Config before editing, and confirm that the referenced policy exists in the active configuration.

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT
GEOIP,CN,DIRECT
FINAL,PROXY

Rule matching and DNS are related: IP-based rules need the relevant destination address, while domain rules need the request to retain a matchable domain. If the logs show a request going DIRECT, check the Rule order first; that result does not assess proxy protocol performance. For more on match targets and rule order, see A Beginner’s Guide to Rule Keywords.

Keep records for four kinds of tests

First, record whether the connection is established and where it fails. Second, record response consistency for the same small request. Third, note any major variation during a sustained transfer. Fourth, check recovery after locking the screen, unlocking it, and switching networks. Connectivity Test is a useful quick clue, but its target and method do not represent every app. One low-latency result does not outweigh repeated request failures, and one timeout does not prove the server is permanently unavailable.

For battery comparisons, keep brightness, signal, temperature, apps, and data transferred similar, and observe for a sufficiently long period. System battery statistics may attribute some usage to the foreground app or network-related processes, so don’t focus only on Shadowrocket’s percentage. If the device heats up, first rule out a sustained large transfer or weak signal. Don’t rank protocols by precise power consumption without stable test conditions.

Narrow down the cause by failure stage

If the connection times out completely, check the address, port, network reachability, and TCP / UDP conditions. For a TLS error, check the server name, certificate, and system time. For authentication denial, check the password, UUID, or key direction. If only some apps fail after connecting, check DNS, Rules, UDP support, and the destination service. Change one setting per round, reconnect, and repeat the same task. If it doesn’t help, return to the baseline instead of stacking changes.

For everyday browsing, start by checking that the existing configuration is complete and stable. For apps that explicitly require UDP, verify end-to-end support. For internal network access, check tunnel addresses and routes; for high-throughput tasks, compare sustained performance. If the cause is still unclear, review the FAQ with a record of symptoms that hides sensitive details. To follow the setup process from the beginning, return to the Getting Started Guide. Don’t use frequent protocol switching as a substitute for checking each layer.