Shadowrocket
Protocol & Settings Reference

Protocol layers: four questions to ask about a connection

Protocol, transport, security, and routing are separate layers

Choosing a protocol type in Add Server tells the client how to identify the destination, authenticate, and exchange data with the server. Transport describes how that data is carried, such as over a TCP byte stream, WebSocket, or a UDP-based mechanism. Security covers encryption and how the remote endpoint is verified; routing determines whether a request uses this connection. Confusing these four concerns can lead to changing a protocol without fixing a mistyped hostname, or editing rules without resolving an authentication failure.

Connection details should specify at least the server address, port, and authentication method. Some combinations also require a transport path, a TLS server name, and other negotiation settings. The server address is where the client connects; the destination website address is the resource the user wants to reach. They are not the same. A port is just an entry point, and a familiar port number does not prove that TLS is enabled. After importing, check the type first, then review any additional options. Don’t move a set of details under another protocol just because some fields look similar.

Break speed down into handshakes, throughput, and stability

For a short webpage, DNS lookup, connection setup, and the security handshake can take longer than transferring the page itself. For large, continuous transfers, congestion control, server capacity, and the destination’s capabilities matter more. Voice and interactive tasks are more sensitive to jitter, packet loss, and reconnection. A single latency test covers only part of the picture. A lower test result doesn’t necessarily mean faster downloads, and more bandwidth doesn’t guarantee smoother interaction on a weak signal. For a fair comparison, keep the destination, network, and approximate time of day consistent; otherwise, the difference may have nothing to do with the protocol.

Battery trade-offs on iOS go beyond the encryption name

Battery use comes from processor work, wireless activity, background wakeups, and repeated attempts after failures. The cost of a modern encryption algorithm is only one factor. Retransmissions on a weak signal, continuous probing, and frequent reconnections are often more important to investigate. For battery comparisons, keep screen brightness, content, and signal conditions as consistent as possible, and give the system enough time to observe. Don’t attribute a battery drop to a protocol based on one session, or assume that more keepalives always improve stability. Keepalives may reduce reconnections but add network activity while idle.

Start by checking what the server supports, what the current network allows, and what you use the connection for—not by ranking protocols by speed. If your existing details support only one type, importing them correctly and verifying the connection reliably matter more than trying a different name. When comparing multiple existing configurations, keep the original records, change one variable at a time, and note whether the failure occurs during DNS resolution, connection, authentication, or destination access. That gives you findings you can use again when network conditions change.

A protocol type is an agreement between both ends, not a client-side preference. If the server has no matching entry point, changing the type in Shadowrocket won’t make the two compatible.

Shadowsocks: shared keys and streamlined transport

Design basics and settings to match

Shadowsocks uses a pre-shared credential to establish an encrypted proxy connection, then forwards the destination address and subsequent data through the server. It is not built around a web session or a full network interface, so its core settings are relatively compact. Typical connection details include an address, port, password, and encryption method. Fewer fields still need careful checking: a different encryption method or credential at either end, or a server entry point that uses another protocol, can prevent communication from starting.

Enter the encryption method exactly as shown in the server details. Different methods use different key derivation, data formats, and authentication; similar names do not mean they are interchangeable. Authenticated encryption also checks data integrity. A wrong key may cause the connection to close soon after connecting rather than show a clear password error. Don’t assume every authentication failure means the connection is unstable. Some newer protocol variants have specific key-format requirements, so don’t apply ordinary password-entry assumptions; follow the field definitions in your own connection details.

Check the base protocol and any additional transport separately

If your connection details also specify a plugin or other outer transport, make sure the corresponding Shadowrocket options match the server configuration. The base protocol, outer transport, and entry port work together; any missing layer can cause a timeout. When migrating older records, don’t copy only the address and password while overlooking additional instructions. Likewise, don’t enable extra features just to make a record seem more complete. Changing the format the client sends may leave the server unable to recognize it.

Verify TCP and UDP availability separately. A working webpage shows only that the path for that request works; it doesn’t mean tasks that depend on UDP will work too. The server’s UDP support, the access network’s handling of that traffic, and whether the current configuration carries the request can all affect the result. If one type of task fails, first identify its transport requirements and check that path instead of immediately changing the password. Test different protocols against the same destination to avoid attributing differences in the destination itself to the protocol.

Speed, battery use, and troubleshooting

With a good network and a reasonably loaded server, streamlined encapsulation can reduce extra processing, but actual speed still depends on path capacity and server performance. How an encryption method performs on one device doesn’t predict its performance on another; hardware acceleration, implementation, and task size all matter. For mobile use, pay more attention to smooth browsing, recovery after a network change, and repeated reconnects while idle than to a single connection-start time.

Troubleshoot in order: check whether the address and port are reachable, verify the encryption method and credentials, then check any additional transport. If all destinations fail, look at the shared entry point first. If only one site fails, check rule matches, DNS resolution, and the remote response. Some failures don’t return clear authentication details, so the absence of a password error doesn’t prove that the credentials are correct. You can import a fresh copy from the original record for comparison, but avoid keeping many entries with the same name; you might end up testing a different one from the one you just edited.

This type may suit a server that provides the matching entry point and connection details, especially when you want a relatively straightforward set of settings. It is not another name for TLS certificate configuration, and it doesn’t mean its security works the same way as TLS. To assess remote identity and manage credentials, understand what the protocol relies on for trust. Keep the passwords and keys in your connection details private. When reporting a problem, share the type, failure stage, and field structure with sensitive values hidden—not the full credentials.

Check the encryption method first, then the password. Changing the encryption name at random rarely fixes compatibility and may make valid connection details unusable.

VMess: check authentication and outer transport separately

Understand what the protocol handles

VMess combines user authentication, destination information, and data protection in its protocol structure, and can work with different outer transports. This reflects a design choice: rather than leaving every function to the outer layer, VMess retains session and authentication mechanisms within the protocol. For users, that means understanding both protocol and transport settings. A UUID alone is not enough to recreate a connection. Without the transport type or security settings, communication may fail even when the user identity is correct.

A UUID identifies a user; it is neither the server address nor the name in a TLS certificate. Copy it in full without adding spaces or invisible characters. Older records may include fields associated with legacy authentication; don’t fill in a value based on habit—check what the server currently requires. Importing a link often preserves fields better than assembling them by hand, but a successful import only means the client read the data structure. It doesn’t verify remote authentication, certificates, or the transport path.

WebSocket, Host, and path each have a different role

With WebSocket, the connection uses an upgrade process, and the path and Host information in the request may determine which server entry point handles it. The path is an entry point defined by the server, not an arbitrary website directory. Differences in capitalization, a leading slash, or query parameters may send the request somewhere that doesn’t handle the protocol. If the server returns a regular webpage or error page, the underlying connection may appear to be established even though no proxy session was created. A reachable address alone doesn’t prove the settings are correct.

When WebSocket and TLS are both used, distinguish the connection address, TLS server name, and HTTP Host. They may be the same, or differ depending on the deployment. The client connects to an address, verifies a name during the security handshake, then uses an application-layer request to reach the specified service. A mismatch at any layer can cause failure. Don’t copy one domain from server records into every field; understand each field’s role and enter the values from the original details.

Time-related checks and authentication errors

VMess authentication involves time-based checks, so a device clock that is significantly wrong can cause connection problems. Check the system date and time, but don’t assume every failure is a clock issue. TLS certificate validity also depends on time, but it is a separate verification step. Authentication and certificate failures can look similar from the outside but call for different fixes. Review the available error details first, then decide whether to check the device clock, user identity, or server certificate.

Extra transport can add some handshake or encapsulation overhead, but there is no fixed performance penalty across all networks. During long transfers, that overhead may be spread out; with frequent short connections, session setup is more noticeable. On mobile, also observe recovery when switching from Wi-Fi to cellular data. Whether an old session is rebuilt promptly and whether the server retains its state can affect the experience. A static latency number can’t predict how the connection will feel throughout the day.

Keep a checklist in this order: identity fields, transport, entry-point information, and security settings. If another existing entry for the same server works, compare the fields before re-entering everything. If only entries using a particular outer transport fail, focus on the entry path and its server-side mapping. A connection that works on another network is a useful clue, but it doesn’t prove the original network blocked a protocol. DNS results, address families, and entry-point reachability may all change between networks.

VMess UUIDs, WebSocket paths, and TLS server names each serve a different purpose. A correct field cannot make up for an error at another layer.

VLESS: lightweight protocol and security-layer boundaries

Less protocol overhead doesn’t mean skipping security checks

VLESS keeps identity and destination handling relatively streamlined and does not provide general-purpose data encryption in its base protocol, so it is typically used with an appropriate security layer. “Lightweight” describes how the protocol divides responsibilities, not a speed guarantee or a reason to skip server verification. Consider two questions: how does the remote server accept the user’s identity, and which layer protects data in transit? The VLESS name alone doesn’t tell you enough to assess a connection’s security.

The UUID, address, and port in your connection details still need to match exactly. Also check the transport type, security method, and related fields. A UUID is not a substitute for TLS: authentication proves that a request has credentials the server accepts, while the security handshake protects the session and verifies remote identity. An incorrect identity may be rejected after the secure connection is established; an incorrect server name may fail earlier. Pinpointing the stage helps avoid aimless changes.

TLS, REALITY, and flow settings

For TLS configurations, check the server name and certificate verification requirements. If your details specify REALITY, make sure the client supports it and that the server settings and required parameters, such as the public key, match. It is not a general option to add to any TLS entry point. Fields required by different security methods are not interchangeable. If key details are missing, retrieve them from your own original connection information; don’t look online for values that seem plausible, since they correspond to a specific server configuration.

Some combinations also include parameters such as flow that constrain how data is handled. This is not an automatic speed boost, and you shouldn’t add it just to chase better performance. Server support, transport compatibility, and the client’s implementation all affect whether the combination works. Preserve the imported values and, if you need to enter them manually, check each one against the original details. For an unfamiliar option, first check which fields the app provides instead of putting it in a different field with a similar name.

Assess speed and battery use in context

A protocol doing less work itself doesn’t mean the whole connection will use less battery. The connection still involves security handshakes, outer transport, congestion control, and wireless activity; connection reuse also affects the cost. For continuous streaming, sustained throughput may matter more than the initial handshake. For intermittent access, wakeups and connection setup may matter more. If two configurations use different servers, bandwidth, or security settings, you can’t attribute the results solely to differences between VLESS and another protocol.

If a test succeeds but a website won’t load, check whether the test and the actual request used the same path. Some tests check only entry-point reachability or one specific destination; a website also requires DNS resolution, a new connection, and multiple resources. Confirm that Global Routing is set to the intended mode and that the selected configuration uses the server you just checked. Use a controlled request alongside connection records to narrow down the issue. Don’t turn off all verification just to get a result that appears to work.

Evaluate suitability based on your existing details. Performance trade-offs are worth considering only when the server provides a complete combination, the client supports all required settings, and you can verify the remote identity. If the information is incomplete, filling in what’s missing is more useful than repeatedly switching security methods. To import a subscription again, see Four ways to import a subscription. Importing won’t supply information the server hasn’t provided.

Trojan, HTTP, and SOCKS5: authentication and encryption are different

TLS requirements for Trojan

A common Trojan setup uses a TLS connection to carry the proxy protocol, with authentication and destination information handled inside the secure channel. It relies on an established security layer rather than assigning encryption duties to every field. A correct password is only one requirement: the server certificate, name, and entry point must also be right. If the domain’s certificate is valid but the connection reaches a different entry point, the proxy session still won’t work. If the entry point is right but certificate verification fails, don’t mistake it for a password problem.

The server name is used for the security handshake and identity verification; it is unrelated to the website you intend to visit. The certificate must cover the name being verified, and the device clock must be reasonably accurate. Some deployments also require options such as application-layer protocol negotiation. Enter these as specified in your existing details; don’t add them arbitrarily. For a certificate error, check the spelling of the name, device time, and server certificate chain, then contact your own server administrator. Skipping verification weakens identity checks and is not a routine fix.

An HTTP proxy connection does not automatically use TLS

An HTTP proxy handles destination requests using the relevant request format or the CONNECT method. It’s common in environments with an existing proxy gateway, and its settings are often straightforward to identify. But the name “HTTP proxy” does not mean the connection between client and proxy is encrypted. If the destination website uses HTTPS, end-to-end TLS may protect its content, while the proxy can still see the destination and connection metadata. That is a separate security boundary from connecting to the proxy over TLS first.

Check whether the proxy entry point requires a secure connection, uses a username and password, and allows the destination ports you need. Some gateways allow only specific access methods, so being able to open one webpage doesn’t prove that every task will work. Authentication failure, a rejected destination port, and an unreachable upstream server are different problems. When something fails, note the failure stage and status instead of simply repeating the test. Don’t mistake a login or denial page from the website for a client-to-proxy authentication failure.

SOCKS5 negotiation and security boundaries

SOCKS5 negotiates destination addresses and authentication methods and defines several request capabilities, but the base protocol does not encrypt the entire connection. Username-and-password authentication is not the same as an encrypted channel. If your gateway requires a secure transport, follow its complete requirements; otherwise, understand the trust relationship between the access network and remote entry point. Choose the type that matches the server’s actual interface rather than treating HTTP and SOCKS5 as interchangeable names.

SOCKS5 handling of domains and UDP depends on how requests are represented, client behavior, and server implementation. A capability defined by the protocol does not guarantee that the current entry point supports it. For real-time communication in particular, test the traffic the task actually uses instead of drawing conclusions from successful web browsing. Don’t infer which side resolves a domain from the protocol name alone; check the client DNS settings and request path. Otherwise, a local DNS issue may be missed while troubleshooting a remote connection.

For speed and battery comparisons, look at the actual transport, not just the protocol name. Security handshakes, connection reuse, and gateway response times affect short requests, while sustained traffic is limited by entry-point capacity and network quality. If you’re using an existing HTTP or SOCKS5 gateway, following its interface requirements is usually more reliable than layering on an unsupported combination. Where identity verification matters, establish the security boundary before considering the benefit of one fewer handshake. A small difference in startup time is no substitute for necessary identity checks.

WireGuard: from destination proxy to network-layer tunnel

The design model determines what the settings mean

WireGuard is a network-layer tunnel that uses public-key identities and encrypted datagrams to carry IP traffic. Its model differs from proxy protocols that handle a connection to a specific destination, so its settings include interface addresses, a peer public key, an endpoint, and allowed address ranges. Its relatively fixed cryptographic suite simplifies negotiation, but that doesn’t make network configuration simple. You still need to understand how addresses are assigned, which destinations go through the peer, and how return traffic reaches the device.

The private key proves your identity; the public key identifies the corresponding peer. Don’t mix them up. The endpoint is the address and port used to contact the peer, while the interface address is used inside the tunnel. They are not interchangeable. If a preshared key is required, both ends must use the same value. After importing, don’t copy the entire identity and internal address set freely between devices. The server may map them to a specific peer, and reusing them can cause session conflicts or incorrect return routing.

AllowedIPs, routing, and MTU

AllowedIPs associates addresses with a peer and helps select traffic; it isn’t simply a website allowlist. In a client integration, consider it alongside the app’s routing policy: one layer determines whether a request enters the connection, while the other defines which addresses are associated with the peer in the tunnel. A range that’s too narrow may leave a destination without a usable route; one that’s too broad may exceed the intended access scope. Preserve the network plan in your server details instead of expanding every range to its maximum based on guesswork.

MTU is the maximum packet size supported on the relevant interface. Outer encapsulation takes up space, and if the underlying path can’t handle larger packets reliably, small requests may work while larger responses stall. That’s only one possible cause, so don’t change the MTU as soon as a page loads incompletely. First rule out problems with the destination service, DNS, and packet loss. Then make small adjustments in a repeatable test and record the original value. Setting it too low can increase fragmentation and processing overhead.

Network changes and keepalives serve different purposes

WireGuard can identify peer address changes during authenticated data exchange, which matters on mobile networks. Actual recovery still depends on the access network, NAT state, and server reachability. When a phone switches from Wi-Fi to cellular data, an old mapping may expire and new traffic may need to establish a working path. This doesn’t guarantee seamless switching every time, and one failed switch doesn’t prove that the key is wrong. First confirm stability on a single network, then check recovery after switching.

PersistentKeepalive sends periodic traffic to help maintain certain NAT mappings; it is not a speed boost. Sending traffic while idle increases wireless activity, but without keepalives, inbound recovery may be slower on some networks. Decide whether to use it and at what interval based on your server details and network conditions. If the app works during active traffic but the first request fails after a long idle period, investigate mappings and keepalives rather than enabling them for every configuration.

Assess performance benefits against the task and conditions. A fixed encryption design and streamlined data path can make overhead more predictable, but UDP reachability, packet loss, and server forwarding capacity can still be bottlenecks. One large file transfer won’t tell you whether the connection uses less battery while idle in the background. On a mobile device, observe continuous tasks, short idle periods, and multiple network switches. Avoid changing several tunnel settings during one test, or you won’t know what made the difference.

Never share a private key or a screenshot showing complete tunnel details. For troubleshooting, keep only field names, obscured address ranges, and the failure stage.

WireGuard is better suited to setups with a complete tunnel plan and clear management of internal addresses and peer identities. If you have only a regular proxy address and password, don’t try to turn them into WireGuard settings. Conversely, a successful handshake proves only that some requirements are met. Check destination routing, DNS, and the server’s return path before concluding that access works end to end.

Hysteria2: QUIC transport and bandwidth trade-offs

Check UDP and security-handshake requirements first

Hysteria2 uses QUIC-based transport. QUIC runs over UDP and combines a security handshake with stream management. This design makes different trade-offs from traditional TCP combinations on unstable links, but it can’t overcome a weak wireless signal, network congestion, or limited server capacity. Before comparing speeds, confirm that the client can reach the UDP entry point. If the current network handles these datagrams poorly, switching to this protocol may not improve the experience.

Connection details typically include an address, port, authentication, a security name, and possibly other requirements. Don’t assume Hysteria2 is compatible with an earlier protocol just because their names are similar; confirm the imported type. Even if the entry-point port resembles one commonly used by web services, that doesn’t tell you which transport it uses. Establish whether you’re testing TCP reachability or a real UDP handshake. Success with the former doesn’t verify the latter, and opening a webpage doesn’t prove the entry point works.

Bandwidth settings are inputs, not speed-test results

Some configurations include upload and download bandwidth settings. Interpret these values in light of the client’s mode and server limits. They may affect sending or congestion-control behavior; entering a larger number won’t create more capacity. Actual capacity is limited by the access network, shared links, server, and destination. If you mistake a target value for sustainable capacity, you may increase queueing, packet loss, and retransmissions—making downloads seem more aggressive while interactive requests get slower.

Consider upload and download capacity separately, especially on networks with limited upload bandwidth. Once uploads saturate the uplink, acknowledgments and control data for other connections may queue up and affect the whole experience. If that happens, reduce concurrent tasks, compare idle and loaded conditions, then check the bandwidth settings. Don’t change the server, increase multiple bandwidth values, and switch to a different test file all at once. Even if the result improves, you won’t know which change helped.

On weak networks, observe both throughput and jitter

On links with packet loss or variable latency, QUIC’s stream management and connection mechanisms may recover differently. But whether it’s “good for weak networks” is something to test, not assume. Sustained download throughput and prompt responses to short requests are separate measures. Start with lightweight interactive tasks, then add a steady transfer and check whether using both noticeably increases wait times. Tests that resemble your actual use are the most useful way to assess a configuration on your network.

Battery effects also need cautious interpretation. Datagram retransmissions, continuous sending, encryption work, and wireless activity all contribute to power use. Finishing the same task faster may shorten active time, but heavy transfers or repeated failures may use more power. UDP alone doesn’t guarantee better battery life, and device heat doesn’t immediately point to the protocol. Keep screen use, media decoding, background sync, and signal changes as consistent as possible. Observe usage over a sufficiently long, repeatable period.

If the handshake fails, check the address, port, and UDP reachability first, then review authentication and the security name. If the connection starts but becomes unstable during transfer, check bandwidth settings, concurrent load, and changes in network capacity. If only one website fails, revisit DNS and routing. Some connection details include specific obfuscation parameters; enter them only when the server requires them and provides matching values. They are not a universal fix for incorrect authentication or certificates.

Compare Hysteria2 using real tasks on your current network. A larger bandwidth setting or a faster test result alone doesn’t prove that sustained access will be more stable.

Consider trying it only if you have the matching server details, complete security settings, and a network that permits the required UDP traffic. If you can’t confirm these conditions, first establish a baseline with an existing, verified connection. Keep a restorable copy of the original details and change one parameter at a time under controlled conditions. That’s more reliable than repeatedly reimporting and comparing from memory.

DNS, rules, and choosing a setup: make findings repeatable

DNS resolution determines where the connection starts

DNS translates a domain name into a reachable address. It can affect access to the destination and the client’s connection to the proxy server itself. Check these separately: a failed lookup for a website doesn’t necessarily mean the server entry point is unreachable, while a DNS problem with a server hostname may cause every request to fail. Encrypted DNS doesn’t guarantee that subsequent website traffic uses the proxy. DNS and access traffic follow their own settings and routing rules. Trace the actual path instead of drawing conclusions from a DNS name alone.

DNS also has a bootstrap dependency: if the DNS server itself is specified by a hostname, it needs an initial lookup or connection path. A misconfiguration can create a dependency loop, making all domains unavailable as soon as the connection starts. Don’t replace every DNS setting at once. Keep a working baseline, then check how the selected configuration handles server and destination hostnames. IPv4 and IPv6 results may follow different paths. If some destinations time out, check the address family and actual reachability; a successful lookup alone doesn’t finish the diagnosis.

Global Routing determines whether traffic uses the selected connection

Config mode follows the rules in the current configuration; Proxy mode routes applicable traffic through the proxy; Direct mode connects directly. Routing choices don’t change the server’s authentication or security requirements and can’t fix an invalid certificate. Before comparing protocols, make sure both tests use the intended path; a direct connection and a proxy connection aren’t comparable. Scene also involves scene settings, so don’t confuse it with these three basic modes.

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
FINAL,PROXY

The snippet above illustrates rule syntax only: the example domain uses PROXY, requests matching the relevant address range use DIRECT, and FINAL handles everything else. It is not a complete configuration and cannot replace your server details. Rules generally take effect in the configured matching order, so a broad rule may prevent more specific rules from being reached. To proxy only selected sites, see Using DOMAIN-SUFFIX and FINAL,DIRECT, then check the actual match in Config mode.

Choose a setup based on the task

For everyday browsing, focus on startup delays, reliable DNS, and recovery after network changes. For sustained transfers, consider throughput, queueing under concurrent load, and server capacity. For real-time interaction, look at jitter, packet loss, and the task’s UDP requirements. For extended mobile use, include idle traffic and battery use in your checks. With an existing HTTP or SOCKS5 gateway, first meet its interface and security requirements. With an existing WireGuard network plan, verify addresses and return routing. For other protocols, start with a complete match rather than a ranking by name.

Keep a simple test log with the access network, task, selected entry, Global Routing mode, any network switches, and the failure stage. Run short requests and sustained tasks on a stable network first, then switch networks under controlled conditions. Change one field at a time and restore its original value if the test fails. Connectivity Test can provide clues, but it doesn’t represent every app’s experience. See the connection verification steps for the full process, and the 10 common beginner questions for troubleshooting.

Keep records while protecting troubleshooting evidence

Subscription updates may change server entries and some settings. Before editing, identify which values come from the subscription and which are local. If an update overwrites a manual correction, review how the details are managed instead of assuming the protocol changed automatically. When contacting your own provider, describe the first failure stage, whether only certain destinations are affected, and what happens on another network. Hide passwords, UUIDs, private keys, and full subscription URLs. A reproducible description is more useful than a screenshot that only says “can’t connect.”

State conclusions conditionally: this combination works better with these existing details, on this access network, for this type of task. If the network or server changes, test again instead of relying permanently on a one-time ranking.