For users who already have a WireGuard configuration they are authorized to use and need to check its fields in Shadowrocket. First distinguish the local PrivateKey from the peer's PublicKey, then enter the Endpoint, tunnel address, and AllowedIPs. Finally, rule out effects from Global Routing. This guide explains the parameters and troubleshooting sequence; it does not provide connection details. Example addresses are for illustrating the format only and cannot establish a real connection.
1. Identify the two sides of a WireGuard configuration
A WireGuard configuration usually contains an [Interface] section and one or more [Peer] sections. The first describes the local tunnel interface; the others describe the peers it can communicate with. When transferring a configuration into Shadowrocket, enter each value in the field it belongs to. Do not assume the first PublicKey in the configuration is the server's key.
WireGuard uses UDP for transport. The peer configuration determines the Endpoint port; 51820 is a common example, not a required default. Being able to browse websites or get a response from a regular TCP port test does not, by itself, prove that the current network allows WireGuard traffic over UDP.
Keys are usually represented as Base64 text. A 32-byte value typically encodes to 44 characters, ending in =. This length can help spot an obvious copy error, but does not prove that the key belongs to the right device or peer. Never post a PrivateKey, PresharedKey, or QR code containing either in a public forum.
2. How PrivateKey, PublicKey, and PresharedKey fit together
| Field | Value to enter | Common mistakes |
|---|---|---|
PrivateKey | The private key for this client, from its [Interface] section. | Entering the server's private key, or generating a new key without registering the client's public key with the peer. |
PublicKey | The public key from the target [Peer]—the peer you want to connect to. | Entering the public key derived from the local PrivateKey. |
PresharedKey | A preshared key agreed on by both sides; enter one only if the original configuration provides it. | A value is set on one side but not the other, or it is confused with the PrivateKey. |
Address | The tunnel address assigned to this device, such as 10.66.0.2/32. | Entering the Endpoint's public address, or using a tunnel address assigned to another device. |
The PrivateKey identifies the local device, and its corresponding client public key must be registered in the peer configuration. Changing the PrivateKey in Shadowrocket while the peer still has the old client public key will usually prevent a handshake. A PublicKey is not a password or an arbitrary label; it must match the peer's actual private key.
When copying a key, preserve its capitalization, plus signs, slashes, and trailing equals sign. Remove any quotation marks or line breaks copied by mistake. If a key has been exposed, replace it and update the peer's registration; deleting a chat message does not invalidate the old key.
3. What Endpoint, AllowedIPs, DNS, and MTU do
The Endpoint is the external address contacted to establish the encrypted tunnel, not an address inside the tunnel. An IPv4 example is 192.0.2.10:51820. For IPv6, if the address and port go in one field, use [2001:db8::10]:51820. If the interface has separate address and port fields, enter only the hostname or IP address in the address field, and the number in the port field.
| Setting | What it means | How to check |
|---|---|---|
AllowedIPs | The address ranges selected for a WireGuard peer and the source traffic it accepts. | The client's outbound destination must fall within the relevant peer's range. Also check that the peer allows the client's tunnel source address. |
DNS | A resolver setting found in many configuration files; it is not part of the WireGuard handshake itself. | Make sure the resolver address is reachable over the current route, and check the DNS settings under the current Config in Shadowrocket. |
MTU | The maximum IP packet size the tunnel interface can carry. | Keep the value supplied by the configuration provider. Adjust it separately only if large requests stall while smaller ones work. |
PersistentKeepalive | Send periodic keepalive packets while idle; the interval is in seconds. | Use this if needed to maintain a NAT mapping, as directed by the configuration provider—for example, 25. It will not fix an incorrect key. |
AllowedIPs is not Shadowrocket's complete traffic-routing ruleset
0.0.0.0/0 covers all IPv4 addresses, while ::/0 covers all IPv6 addresses. Entering only the former does not cover IPv6 as well; entering only 10.66.0.0/24 covers that subnet alone. Choose ranges that match your use case and the peer's capabilities. Do not expand them just to make the list look complete.
In Shadowrocket, Global Routing and the current Config determine which route a connection takes. When the connection is passed to the WireGuard outbound, it must also fall within that peer's AllowedIPs range. So having an IP in AllowedIPs does not mean traffic to it will automatically use this WireGuard profile; likewise, selecting the profile in a rule does not add any missing AllowedIPs ranges.
# For address-format illustration only; this is not a complete, importable configuration.
# The addresses below are examples and do not correspond to real services.
[Interface]
Address = 10.66.0.2/32
MTU = 1420
[Peer]
Endpoint = 192.0.2.10:51820
AllowedIPs = 0.0.0.0/0, ::/0
PersistentKeepalive = 251420 is a common MTU reference, not the best value for every network. If the handshake succeeds but larger responses stall, note the original value, try a lower one such as 1380, and repeat the same request before deciding whether to keep it. Do not change MTU, DNS, and keys at the same time, or you will not know which change made a difference. Also, do not assume that DNS, MTU, and other settings from the original file will all take effect automatically with every import method.
4. Check the steps for adding WireGuard in Shadowrocket
The manual setup sequence below follows the Home, Config, and Settings structure. Field order and the location of the save button may vary by platform; match fields by their English labels. If your configuration has multiple peers, do not assume that adding one connection manually will reproduce all peer-selection behavior. First confirm which peer you intend to use.
-
Prepare the original configuration
Separate the
[Interface]section from the target[Peer]. Have the client PrivateKey, Address, peer PublicKey, Endpoint, and AllowedIPs ready. Include the PresharedKey if the original configuration has one. -
Choose the type
Go to Home → tap “+” in the top-right corner → Type → WireGuard. Choose a descriptive name to avoid selecting the wrong profile if another one has the same name.
-
Enter the fields
Enter keys and addresses in the fields for the local interface and peer. If Endpoint has separate address and port fields, fill them separately. Keep the CIDR prefix length in AllowedIPs. Do not generate a substitute PresharedKey if none was provided.
-
Save and select
After saving, return to Home and select the WireGuard profile you just added. Check the current Global Routing value, then connect. Respond to the first system permission prompt on your device.
-
Test, then restore
Test with a destination you are authorized to access and that falls within AllowedIPs. When troubleshooting is complete, restore your usual Global Routing setting. In Config, check that the policy referenced by the active rules still points to the intended outbound.
5. Use Global Routing to separate parameter issues from rule behavior
Before troubleshooting, note the current value under Home → Global Routing. Config, Proxy, Direct, and Scene are routing modes, not WireGuard key settings. Scene follows its configured behavior, so do not treat it as a fixed test route until you have checked what the scene does.
Config
RecommendedChoose a policy according to the rules in the current Config. Rules such as DOMAIN-SUFFIX, GEOIP, IP-CIDR, and FINAL may send different destinations to different outbounds; only connections matched to the relevant policy will use this WireGuard profile.
Best for: everyday rule-based routing after you have checked the rules.
Proxy
Route connections handled by Shadowrocket through the selected proxy path, reducing variables introduced by Config rule selection. Make sure the selected profile is the intended WireGuard entry and that the destination is within its AllowedIPs range.
Best for: briefly checking whether the WireGuard outbound can reach a specific test destination.
Direct
Use the direct route. If a webpage loads, that only shows it is reachable over a direct connection; it does not prove the WireGuard configuration works or indicate the peer's outbound status.
Best for: checking basic connectivity on the device's existing network.
If a destination is reachable under Proxy but fails under Config, first check which rule matches it and which policy that rule uses. Do not immediately replace the PrivateKey. If it also fails under Proxy, check the Endpoint, UDP reachability, both sides' keys, and AllowedIPs. Settings → On Demand controls when a connection starts automatically; it does not change the peer keys. To rule out automatic reconnection effects, note its current state, then temporarily turn it off and manage the connection manually.
6. Troubleshoot failed handshakes, DNS failures, and idle disconnects
The connection is on, so why can't I access anything?
Turning the connection on does not mean the peer has completed a successful exchange. First confirm that the intended WireGuard profile is selected in Home. Then check the Endpoint address and UDP port, whether the public key corresponding to the client's PrivateKey is registered with the peer, and whether the PublicKey really belongs to the peer. If logs or peer-side handshake records are available, check for a new successful handshake after starting a test. Do not rely on the connection toggle alone.
The handshake succeeds, but no webpage content loads?
Check AllowedIPs on both sides: does the client's configuration cover the destination, and does the peer allow the local tunnel source address? If the destination is on a network behind the peer, the network administrator should also check forwarding, firewall rules, the return route, and any required NAT. A handshake shows that the keys and basic UDP path work; it does not guarantee that the peer can forward traffic to the destination network.
IP addresses work, but domain names fail to resolve?
Check the DNS settings in the current Config and whether the resolver is reachable. Distinguish a failure to resolve the Endpoint hostname from a failure to resolve a destination domain. When testing a raw IP address, use a destination that supports access by IP. An HTTPS site may reject a raw IP because of certificate or virtual-host requirements; do not assume that error is caused by DNS.
It stops working after sitting idle, but reconnecting fixes it?
First check whether the device switched between Wi-Fi and mobile data, or whether the system went to sleep and changed the connection state. If you suspect an expired NAT mapping, check PersistentKeepalive against the original configuration—for example, 25 seconds—and check whether Settings → On Demand has a relevant trigger configured. Keepalives add periodic traffic and do not replace retesting after a network change.
When sharing troubleshooting details, include the time of failure, network type, destination category, Global Routing value, and whether a handshake occurred. Hide the PrivateKey, PresharedKey, and full subscription URL. Keeping a record of one change at a time is more useful than replacing several sets of parameters in a row.