This guide is for users who already have their own service configuration. It explains how to distinguish device parameters from remote Peer parameters, enter each WireGuard field using the correct source, and locate issues in three stages: handshake, data transfer, and access to the target address. Addresses and ports shown here illustrate formatting only; they are not usable connection details.
Before you begin: separate the details for each side
A WireGuard configuration describes an encrypted tunnel between a device and a remote Peer. Shadowrocket is a paid client for Apple platforms. iPhone and iPad users can get it from the App Store; check the App Store page for system requirements. Purchasing the client does not provide a remote service. Before entering any details, obtain the configuration intended for this device from your existing service management page or administrator.
The two directions of the keys are easiest to confuse: PrivateKey belongs to the local device and must be used and kept secure there; the remote Peer provides the PublicKey to enter. The remote side also needs the device public key corresponding to the local PrivateKey to identify this Peer. Do not copy the remote public key into the local private key field, and do not expect entering the same string in both fields to establish a connection.
Check configuration sources by role
Local device
PrivateKey: The private key used by this device; do not share it as public information.Address: The address assigned to this device inside the tunnel, usually with a prefix length.DNS: Enter the resolver specified in the service configuration, if one is provided.
Remote Peer
PublicKey: The remote public key, not the local device's public key.Endpoint: The remotely accessible hostname or IP address and UDP port.AllowedIPs: The destination addresses that can be sent to this Peer, as defined by the service configuration.
In short: compare each item against the original details in the “local” and “remote” columns. If a required field is missing, check with the configuration provider instead of guessing.
If you have a standard WireGuard configuration file, first identify [Interface] and [Peer]: the former usually lists local parameters, while the latter usually lists remote parameters. The fields in the app may be arranged differently from those in the text, but their roles do not change based on where they appear. Do not paste the entire text into a single PrivateKey or Endpoint field.
What PrivateKey, PublicKey, Endpoint, and MTU do
PrivateKey lets the local device participate in the WireGuard handshake. Its corresponding public key must be registered in the remote configuration. This is a sensitive credential: when troubleshooting, you can check whether it is in the right field or belongs to another device, but do not show its contents in screenshots or public support requests. Replacing this private key also changes the corresponding local public key, so the existing remote registration must be updated accordingly.
PublicKey identifies the remote Peer to connect to. If it is incorrect, the two sides cannot complete a valid handshake using the right identity, even if the hostname and port are correct. Endpoint is the address used to reach the remote side, commonly written as “hostname:port,” such as vpn.example.com:51820 shown here for formatting only. 51820 is an example UDP port; use the value in your own service configuration.
MTU limits the size of individual packets inside the tunnel. If it is too large, some network paths may allow small requests but stall on large pages or file transfers. If it is too small, transfer overhead increases. 1420 is a common starting point for testing, not a value that should be used on every network. Start with the value from your configuration provider. Only adjust it gradually, following their guidance, if you have confirmed the handshake succeeds and the issue is limited to large-packet transfers. Record the results before and after each change.
Enter values in Add Server using their source
Manual entry is suitable if you already have WireGuard-specific parameters and want to check them one by one. If your existing service provides only a subscription URL, first confirm whether it includes a usable WireGuard configuration. The subscription link itself is not an Endpoint; do not enter the full URL in the remote address field. The steps below describe manual setup; the fields shown may vary in the current app interface.
Open the add screen
Go to
Homein Shadowrocket, tap+in the top-right corner to openAdd Server, then selectWireGuardunderType.Enter local details
Use your existing configuration to enter
PrivateKeyand theAddressassigned to this device. EnterDNSonly if the configuration specifies it. Do not use an example address as the address assigned to your device.Enter remote details
Enter the remote
PublicKey,Endpoint, andAllowedIPsin their respective fields. If the configuration includesPresharedKey, enter it as provided; do not make one up if none is provided.Check MTU
Use the
MTUvalue from your configuration first. If none is specified, keep the default allowed by the interface and avoid changing multiple parameters before the first connection attempt.Save and test
After saving, return to
Home, select the entry you just added, and enable the connection. When enabling it for the first time, follow the system prompt to allow adding a VPN configuration. Then check the connection status and test actual access.
AllowedIPs is especially worth checking character by character against the original configuration. It specifies which destination addresses the Peer accepts. 0.0.0.0/0 represents the entire IPv4 address space, and ::/0 represents the entire IPv6 address space, but whether to use these ranges depends on your existing service configuration. This is not the same setting as Shadowrocket’s Global Routing: the former limits the destination range for a WireGuard Peer, while the latter determines how the app handles requests in its current mode.
No handshake: check address, identity, and route in order
An enabled switch does not mean that WireGuard has completed a handshake. First confirm that the selected entry is the WireGuard entry you just saved, then check for an actual response from the remote side. If your existing management interface or service diagnostics show the time of the most recent handshake, use it as a reference. If the interface does not show this metric, do not assume the handshake succeeded based only on the switch color.
No handshake at all—what should I check first?
Check the hostname, colon, and UDP port in Endpoint, and confirm that the address comes from your existing service. Try again on another available network. If it fails only on one network, first check whether that network can reach the relevant UDP endpoint.
The address is correct, so why does it still fail?
Compare the remote PublicKey, local PrivateKey, and optional PresharedKey one by one. Ask your configuration provider to confirm that the remote side has registered the public key for this device, and check that the device Address matches the remote record.
It sometimes works after switching networks. How can I narrow it down?
Record which network the failure occurs on and whether the same configuration completes a handshake on another network. If the service configuration specifies PersistentKeepalive, check that its value was entered correctly. This setting can help maintain a mapping for some connections behind address translation, but it cannot fix an incorrect key or port.
The handshake succeeds, but pages still fail to load completely. Why?
Test a small request and a larger page separately, then check AllowedIPs, DNS, and Global Routing. If larger transfers are the main issue, record the current MTU and then test gradual adjustments. Change only one setting at a time.
The key to troubleshooting is to preserve a comparison: use the same configuration and destination address, changing only one setting or network condition at a time. If you change keys, ports, routing mode, and MTU together, you will not know what fixed the issue even if access is restored. When reporting an issue to your configuration provider, describe the step where it occurred, the network type, and what you observed. Never include the contents of PrivateKey.
After a successful handshake: distinguish routing from transfer issues
A successful handshake confirms that the two sides completed the required negotiation. It does not prove that every destination will use the tunnel, that DNS will resolve as expected, or that the target service will be available. First use Connectivity Test in Home to help assess the connection, then test again with a specific destination address. If only certain destinations fail, check whether they fall within AllowedIPs and whether the current Global Routing mode sends requests through the selected connection.
Config
RecommendedRoutes requests according to the configured rules. When troubleshooting a single destination, check which rule it matches and the resulting action; a completed WireGuard handshake alone does not determine the rule outcome.
Use for: everyday rule-based routing and checking routing results one rule at a time.
Proxy
Temporarily sends requests through the selected proxy connection. This can help determine whether the issue is with the current rule path; first confirm that the WireGuard configuration itself connects.
Use for: briefly comparing rule-based routing with the connection itself.
Direct
Sends requests directly. If this mode remains selected, the result does not indicate whether WireGuard transfers are working correctly.
Use for: creating a direct-connection comparison, then checking the required mode after testing.
When using Config, rule keywords such as DOMAIN-SUFFIX, GEOIP, IP-CIDR, and FINAL refer to domain suffixes, geographic locations, IP ranges, and fallback matching, respectively. First confirm which rule matched the test destination, then decide whether to check WireGuard. If no destinations transfer data, recheck the Peer parameters first. If only some domains fail, compare DNS results, rule matches, and destination address ranges.
After testing, restore any temporarily changed Global Routing, MTU, or DNS settings to verified values, and save a troubleshooting record that does not contain the private key in plain text. The next time you encounter a connection that handshakes but cannot access a destination, you can compare the network, target, and setting changes without having to guess what each field does.
Verify the official App Store listing before configuring
Shadowrocket is available from the App Store. The developer is Shadow Launch Technology Limited, and the app ID is 932747118. The client is a one-time purchase; users must prepare their own service details for connections. This is an official manual. Before purchasing, refer to the information shown on the App Store page.
View App Store verification View the guide