This guide is for users who already have a WireGuard configuration from their provider. First, distinguish client keys from server keys. Then map the Interface and Peer addresses, ports and DNS settings to Shadowrocket. Finally, troubleshoot in order: handshake, routing, DNS and MTU. The addresses shown are examples only, not usable connection settings.
1. Understand Interface and Peer before adding a connection
A WireGuard connection in Shadowrocket requires a matching set of parameters; a server address alone is not enough. Typical WireGuard configuration files contain [Interface] and [Peer] sections: the first describes the local tunnel interface, while the second describes the remote peer. Sort the settings by section before entering them. Don’t copy a Public Key into just any key field.
This guide focuses on adding WireGuard manually from Home. If your provider gives you a Subscribe link, get it from your provider and import it via Home → + → Type → Subscribe. This is a separate setup path from entering WireGuard parameters manually. Don’t put a subscription URL in Endpoint or paste an entire configuration into Private Key.
Keys are usually represented as Base64 text, typically 44 characters in the standard encoding. Length can reveal obvious truncation, but it doesn’t prove a key is valid. WireGuard doesn’t authenticate with a username, password or TLS certificate. The server must have the client Public Key that corresponds to the client’s Private Key.
2. How Private Key, Public Key and Preshared Key fit together
Private Key is the secret identity material for this device. The Public Key under Peer identifies the remote endpoint. They may look alike, but they aren’t interchangeable. If your provider also shows a “client Public Key,” that is your local public key for registration on the server—not the value to enter as the remote Public Key.
| Field | What to enter | Common mistake |
|---|---|---|
[Interface] PrivateKey | Enter the client’s Private Key, preserving the complete Base64 string. | Pasting the server’s private key or using the client’s public key by mistake. |
[Peer] PublicKey | Enter the server’s Public Key. | Entering the client Public Key shown in the provider’s dashboard by mistake. |
[Peer] PresharedKey | Enter an additional preshared key only if your provider supplies one and the server has it enabled. | Generating one when the server isn’t configured for it, or omitting a required value. |
When copying a key, don’t include the field-name prefix, such as PrivateKey =. Don’t add quotes, line breaks or trailing spaces. If the configuration came from a QR code or imported file, make sure it belongs to this device. Reusing the same client identity across multiple devices can cause the Endpoint recorded by the server to keep changing, resulting in intermittent disconnections.
3. Address, Endpoint and AllowedIPs: what’s the difference?
Address is the IP assigned to the client inside the tunnel. Endpoint is the remote address the client contacts over the public internet or current network. They serve different purposes: Address identifies the local tunnel address; Endpoint specifies where encrypted UDP packets are sent. Don’t enter the Endpoint’s public IP as the local Address.
| Field | Example format | What to use |
|---|---|---|
Address | 10.66.0.2/32 | Use the address and prefix assigned to this client by your provider; don’t choose your own. |
Endpoint | vpn.example.com:51820 | The server’s hostname or IP address and the UDP port it actually listens on. |
| IPv6 Endpoint | [2001:db8::10]:51820 | Wrap an IPv6 address in square brackets when entering it as part of a single Endpoint string. |
AllowedIPs | 0.0.0.0/0, ::/0 | The IPv4 and IPv6 address ranges for this Peer. This doesn’t mean app-level routing is configured. |
Port 51820 is a common example, not a requirement. Use the port specified by your provider. A network allowing TCP 443 doesn’t mean UDP 443 will be reachable. If the editor has separate address and port fields, enter the hostname and numeric port separately; don’t include :51820 in the address field.
In WireGuard, AllowedIPs helps select a Peer for an address and restricts accepted source addresses. Shadowrocket’s Global Routing and Config determine which requests use the selected proxy. These are separate layers. Seeing 0.0.0.0/0 in a configuration doesn’t mean every request in Shadowrocket will bypass rule selection and use this connection.
- If your provider assigns only an IPv4 tunnel address, don’t add an IPv6 Address yourself.
- If Endpoint uses a hostname, that hostname must be resolvable before the tunnel is established. Don’t rely entirely on DNS available only through the tunnel.
- Multiple Address or AllowedIPs entries in a standard configuration may appear as separate fields in the editor. Follow the fields shown; don’t paste a comma-separated list into a single-address field.
4. Add and test a connection from Home
Keep a copy of the original configuration from your provider before entering anything. The steps below use English interface labels. Field layouts vary by platform, and a standard configuration file’s parameters may not all appear as fields with matching names. If a field isn’t shown, check what the platform’s import flow supports instead of putting the value in an unrelated field.
-
Select the type
Go to Home → + → Type → WireGuard and make sure you’re editing a WireGuard connection, not Subscribe or another protocol type.
-
Enter the keys
Enter the local and remote keys using Interface’s PrivateKey and Peer’s PublicKey. Add the Preshared Key if your provider requires one.
-
Enter the addresses
Map the Endpoint hostname and port to the server address and port fields, then enter the local tunnel address assigned by your provider. Use the original DNS and MTU settings.
-
Save and select
After saving, return to Home and select the connection you just added. Check the current Home → Global Routing mode and make sure your test request will use this connection.
-
Send a request
Turn on the connection and allow the requested network configuration if prompted by the system. Visit a known reachable destination, then check the connection logs and traffic in both directions; don’t rely on the switch alone.
For troubleshooting, you can temporarily select Global Routing → Proxy to reduce variables from Config rules. This still doesn’t guarantee that every type of system traffic is routed through the proxy. After testing, switch back to your usual Config and check which configuration is active. Direct doesn’t forward requests through the selected proxy, so it can’t test the WireGuard exit. For Scene, check the configured scene conditions; it isn’t a fixed global proxy mode.
5. Configure DNS, MTU and PersistentKeepalive
DNS determines which resolver handles domain lookups. MTU limits the packet size carried by the tunnel interface. PersistentKeepalive helps maintain some NAT mappings. They solve different problems: changing DNS won’t fix an incorrect Public Key, and lowering MTU won’t make an unreachable UDP Endpoint respond.
DNS: check the resolution path first
In standard WireGuard configurations, DNS is a common client-side extension, not a field in the WireGuard handshake protocol itself. After importing, check how it actually affects the current Shadowrocket Config and DNS settings; don’t assume the DNS value in the file will handle every query. If the configuration specifies an internal tunnel DNS address, it usually won’t be reachable until the tunnel is up.
- Endpoint hostname won’t resolve: check the DNS used by the network before the connection is established.
- Some domains fail to resolve after connecting: check the current DNS settings, reachability and any DNS rules in the configuration.
- Different results for IP and domain access: this may point to a DNS resolution issue. HTTPS requests made directly to an IP can also fail because of certificate or hostname mismatches, so don’t draw a conclusion from this alone.
MTU: start with the supplied value, then test one change at a time
Keep the provider’s setting or the default
RecommendedIf your provider specifies an MTU, use that value first. If not, start with the client’s default behavior to establish a repeatable baseline.
Best for: initial setup and connections where browsing and downloads work normally
Lower MTU manually
Only lower it gradually if the same issue consistently occurs—for example, small requests work but larger ones stall. You might test 1380 after 1420, changing only this setting each time.
Best for: targeted troubleshooting of suspected path MTU or encapsulation overhead issues
Bottom line: record what happens before keeping a change
Using the same network and destination, compare page loads and transfer behavior before and after the change. If a lower MTU doesn’t help, restore the original value. Neither 1380 nor 1420 is right for every network.
The right MTU depends on the underlying path and any additional encapsulation. Setting it too low can increase packet count. If the handshake hasn’t completed, check the keys and Endpoint first instead of repeatedly changing MTU.
PersistentKeepalive: maintain reachability during idle periods
PersistentKeepalive = 25 means sending a keepalive packet every 25 seconds. It’s a common NAT example, not a required value or a performance setting. In a standard WireGuard configuration, 0 disables periodic keepalives. If your provider specifies this setting and the client supports it, use the requested value. If there’s no field for it, don’t substitute a port or MTU field.
- If the first request after a long idle period is often delayed but ongoing transfers work, check NAT idle timeouts and keepalive settings.
- If transfers keep dropping, also check packet loss, network changes and server status. Shortening the keepalive interval alone may not help.
6. Troubleshoot by symptoms; the connection switch doesn’t confirm a handshake
A WireGuard handshake is typically triggered by data waiting to be sent. Turning on the Shadowrocket connection switch indicates that the local connection process has started; it doesn’t confirm remote authentication, DNS or access to your destination. Send a request and check the available logs. If your provider can supply server-side handshake records, check whether the client’s packets arrived at the same time.
| Symptom | Check first | Next step |
|---|---|---|
| No valid response after sending a request | Key pairing, Endpoint and UDP reachability | Check the server Public Key, client public key registration and listening port, then test again on another network. |
| Handshake recorded, but traffic doesn’t work | Address, AllowedIPs and server forwarding | Confirm the assigned address and return route, and check that the request is actually using this connection. |
| Some domains are unreachable | DNS and Config rules | Compare DNS results and rule matches. Make sure the request isn’t being handled by Direct or another policy. |
| Small requests work, but large transfers stall | Path MTU, packet loss and destination status | Test MTU changes one at a time against the same destination. Keep notes and don’t change DNS at the same time. |
| Brief outage after switching networks | UDP on the new network, Endpoint resolution and On Demand | Test manually on both Wi-Fi and cellular to distinguish network restrictions from automatic connection conditions. |
When troubleshooting from Config, first confirm which file is active, then check the order of its Rules. DOMAIN-SUFFIX matches domain suffixes, IP-CIDR matches address ranges, GEOIP matches based on IP geolocation, and FINAL handles requests that didn’t match earlier rules. The matching rule applies its assigned policy. If a rule sends a request to Direct, changing the WireGuard key won’t change the route for that request.
- Record the original value before making a change. Change one setting at a time so you can tell what helped.
- After a connection managed through Subscribe is updated, check whether its parameters changed. Manual edits may be overwritten by the next update.
- When contacting your provider, include the time, network type, symptoms and fields you’ve checked. Hide your Private Key, Preshared Key and subscription credentials.
7. Save your configuration for future use
After your first successful test, keep a protected copy of the original configuration and record the current Global Routing mode and working MTU. If problems arise later after a network change, subscription update or Config edit, you can retest with these known settings instead of guessing. If your provider changes the server Public Key or assigned address, review all related fields together.
Download Shadowrocket and get started
The iPhone / iPad version is a one-time $2.99 purchase on the App Store. The Mac (Apple silicon and Intel), Windows, Android and Linux versions are free. Buying the app doesn’t include a connection service; get subscriptions from your provider.