With Config selected under Home → Global Routing, Shadowrocket checks the rules in the active configuration from top to bottom. The first match determines the policy. Domain rules inspect hostnames, address rules inspect destination IPs, and FINAL handles connections that match none of the rules above it. This guide is for anyone organizing routing rules or investigating why a connection uses DIRECT or PROXY.
Rule order: Select Config, then find the first match
Select Config under Home → Global Routing, then check the active configuration file on the Config page. In the first location, Config is a routing mode; in the second, it’s the page for managing configuration files. Changes to a different file won’t affect connections using the active configuration. Proxy and Direct aren’t modes for checking this rule order.
Rules are typically written as “type, match value, policy,” for example DOMAIN,api.example.com,DIRECT. DIRECT connects directly; PROXY routes through a proxy. Shadowrocket doesn’t automatically choose the most specific rule: even if a DOMAIN rule is more specific than a DOMAIN-SUFFIX rule, an earlier suffix rule takes precedence as soon as it matches.
Domain rules: DOMAIN, DOMAIN-SUFFIX, and DOMAIN-KEYWORD
All three rules match hostnames, not full URLs. For https://api.example.com:443/v1/status, the domain value is api.example.com; leave out https://, port 443, and path /v1/status. These rules can’t distinguish between paths on the same host.
| Rule type | Match value | Match example | No-match example |
|---|---|---|---|
DOMAIN | api.example.com | api.example.com | img.api.example.com |
DOMAIN-SUFFIX | example.com | example.com、api.example.com | notexample.com |
DOMAIN-KEYWORD | example | notexample.net | An unrelated host other than api.example.net, such as api.demo.test |
Use DOMAIN to set an exception for one host. To match a root domain and its subdomains, use DOMAIN-SUFFIX; there’s no need to write the match value as *.example.com. DOMAIN-KEYWORD matches a substring, which doesn’t have to fall between two dots. The table’s notexample.net contains example, so it matches—even though it belongs to an entirely different site. When you know the destination domain, exact-match or suffix rules offer more control.
Address rules: IP-CIDR matches subnets; GEOIP checks IP location
IP-CIDR: Matches an IPv4 subnet. For example,192.0.2.0/24covers192.0.2.0through192.0.2.255.192.0.2.18is in the range;192.0.3.18isn’t. To match a single IPv4 address, use/32, as in192.0.2.18/32. The addresses in this article are documentation examples, not for connectivity testing.GEOIP: Matches a country or region code based on the destination IP’s location in a geolocation database. For example,GEOIP,CN,DIRECTmatches destination addresses that the database classifies asCN. It doesn’t check whether a domain ends in.cn, the device’s language, or a region setting on a website.
Address rules need a destination IP to evaluate a connection that starts with a domain name. For example, IP-CIDR,192.0.2.0/24,DIRECT,no-resolve uses no-resolve to prevent an additional DNS lookup for this rule; it doesn’t disable DNS for the entire configuration. If a destination IP is already available, Shadowrocket can still check whether it falls within the subnet. If only a hostname is available and there’s no usable IP, don’t expect this rule to resolve the hostname and match it.
The same hostname can resolve to different IP addresses. A domain suffix rule’s match condition doesn’t change with those addresses, but a GEOIP result depends on the destination IP being checked and its database classification. To keep a host on the same policy, put its domain rule before the geolocation rule.
FINAL fallback and rule order examples
FINAL takes no domain, subnet, or region code. For example, FINAL,PROXY routes connections that matched none of the preceding rules through a proxy. Put it at the end of [Rule]. The rules below illustrate evaluation order; they aren’t a complete configuration. To test the PROXY route, use a proxy you’ve configured and confirmed is working.
[Rule]
DOMAIN,api.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
DOMAIN-KEYWORD,demo-example,DIRECT
IP-CIDR,192.0.2.0/24,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXY
- For the hostname
api.example.com, the first line selectsDIRECT. Swap the first two rules and the suffix rule matches first, routing the same hostname throughPROXY. - For the hostname
demo-example.example.com, both the suffix and keyword rules match. Since the suffix rule comes first, the connection usesPROXY. A keyword match won’t override the policy already selected. - When the destination is given directly as
192.0.2.18, the first three domain conditions don’t match, so the subnet rule selectsDIRECT. Changing it to192.0.3.18only tells you that the subnet rule didn’t match. Check the followingGEOIPrule before concluding thatFINALapplies. - The final-line
PROXYapplies only if none of the domain, subnet, or geolocation conditions match. If that outbound connection fails,FINALwon’t try another policy; it handles unmatched connections, not connection failures.
Troubleshoot unmatched rules and failed connections
First determine whether the wrong policy was selected or the right policy was selected but the connection failed. Retry with a specific destination host—for example, add a DOMAIN rule for a test host you can reach, place it above broader rules, save, and start a new connection. A webpage may also request images and scripts from other hosts, so whether the whole page loads doesn’t tell you which policy was used for every request.
Browser errors
These are examples of errors a browser may display, not Shadowrocket rule-match results.
Error: ERR_NAME_NOT_RESOLVED
Cause: The browser couldn’t resolve the requested hostname to an address. Fix: Check the hostname spelling and DNS resolution first, then decide whether to adjust rules that depend on a destination IP.
Error: ERR_CONNECTION_TIMED_OUT
Cause: The connection wasn’t established in time. This error doesn’t indicate which rule matched. Fix: Check the expected policy against the active configuration’s rule order. If the expected route is PROXY, run Connectivity Test on the active proxy under Home.
Frequently asked questions
Why does traffic still use a proxy after I add a DOMAIN rule?
First, check that Config is selected under Home → Global Routing and that you edited the active file. Then check whether an earlier DOMAIN-SUFFIX or DOMAIN-KEYWORD rule already matches. If so, move the exact-match exception above it and start a new connection.
Why does GEOIP give different results for the same domain?
Compare the actual destination IPs used by the two connections first. The same domain doesn’t guarantee the same IP address on each connection. To keep a domain on a fixed policy, use an earlier DOMAIN rule rather than relying on a later GEOIP rule.
Which rules should I check before changing FINAL?
Start with a test destination that doesn’t match any known domain rule, then check whether it matches an IP-CIDR or GEOIP rule. Changing FINAL affects the connection only if none of the preceding conditions match. Change one thing at a time so you can compare the results.
Download Shadowrocket and get started
Get Shadowrocket for iPhone and iPad on the App Store for a one-time payment of $2.99. Check the App Store listing for system requirements. The Mac (Apple Silicon and Intel), Windows, Android, and Linux versions are free and available from this site’s download page.