2026-10-24 · Rules · About 8 min read

How to Write Shadowrocket Rules: A Beginner’s Guide to DOMAIN-SUFFIX, DOMAIN-KEYWORD, GEOIP, IP-CIDR, and FINAL

Learn what each Shadowrocket rule type matches, how rule order works, and how to write your first rule with PROXY, DIRECT, or REJECT.

At a glance

For readers who have installed Shadowrocket and want to add a routing rule to an existing Config. Start by distinguishing domain rules from destination IP rules, put exceptions before broader rules, then check the matched rule and final policy in the connection log. The example domains and addresses illustrate the syntax; you can read and verify them without importing a subscription.

Rule order: evaluated top to bottom; the first match wins

Set Global Routing to Config on Home to route Shadowrocket connections according to the active configuration. In the [Rule] section, each line usually contains one rule in the format type,match value,policy. FINAL is the exception: it takes no match value and is written as FINAL,policy.

App starts a connectionDestination details are readRules are checked in orderFirst matching policy is selectedConnection is handled

The app does not automatically move exact DOMAIN rules to the top. If a DOMAIN-SUFFIX rule matches first, an exact-domain exception below it will never apply. Likewise, placing FINAL in the middle means any connection that reaches it gets the fallback policy, leaving later rules no chance to match.

Domain rules: exact host, suffix, and keyword

Domain rules check the hostname, not the full URL. For https://docs.example.com:443/guide, enter docs.example.com as the match value—not https://, port 443, or path /guide. The three domain rule types below cannot route two paths on the same hostname differently.

Type and match valueMatchesDoes not match
DOMAIN,example.comexample.comdocs.example.com: a different hostname.
DOMAIN-SUFFIX,example.comexample.com、docs.example.comnotexample.com: no label boundary.
DOMAIN-KEYWORD,exampleexample.com、notexample.netsample.net: does not contain the specified string.

For DOMAIN-SUFFIX, enter example.com; there’s no need to write *.example.com. Use DOMAIN when you want to match one host. Use DOMAIN-SUFFIX when the root domain and its subdomains should share a policy. DOMAIN-KEYWORD can match more broadly than expected, especially with short terms: the keyword does not need to be a complete domain label or appear at the start of the hostname.

[Rule]
DOMAIN,docs.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
DOMAIN-KEYWORD,example,REJECT
FINAL,DIRECT

In the examples above, docs.example.com matches the first rule and uses DIRECT; www.example.com matches the suffix rule and uses PROXY; and notexample.net is blocked by the keyword rule. That keyword rule illustrates unintended matches and is not recommended for everyday use. Swap the first two rules and docs.example.com will match the suffix rule first—why exact exceptions need to come earlier.

IP rules: IP-CIDR, GEOIP, and the fallback

If no domain rule matches, destination IP rules can determine the policy. IP-CIDR checks whether the destination IPv4 address falls within a specified subnet. GEOIP uses the destination IP’s classification in a geolocation database; it does not check the domain suffix or the phone’s location. Put domain exceptions before broad IP rules when specific domains need different handling.

[Rule]
IP-CIDR,192.0.2.0/24,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXY

Add and verify your first rule

For your first edit, add just one narrowly scoped rule; don’t change DNS, proxy routes, and the fallback policy at the same time. The steps use DOMAIN,example.com,DIRECT as an example. If the site is not reachable directly on your current network, use a test hostname you know is accessible directly.

  1. Back up the current configuration

    In Config, confirm which file is active and save a copy before editing. If the file updates remotely, make changes to a local copy for your own use so the next update does not overwrite them.

  2. Add an exact-match rule

    In Config, open the configuration details you want to edit, then add a DOMAIN rule under Rules with example.com as the match value and DIRECT as the policy. If editing the text directly, add the rule to the [Rule] section.

  3. Check the rule position and routing mode

    Place the new rule before any suffix or keyword rules that could match first, and before FINAL. Save the file and make sure the edited configuration is active. Then go to Home → Global Routing, select Config, and turn on the connection switch.

  4. Start a new connection to verify

    Close the test page and make a fresh request so the browser does not reuse an existing connection. Open Data and find the record for that request by hostname and time; check that its policy is DIRECT. If the page redirects or loads resources from other hosts, check those records separately.

Troubleshooting: distinguish DNS, destination port, and rule matching

A page failing to load does not necessarily mean the rule failed. First, use Data to check the failed connection’s destination and policy. If a matching record appears but the page still fails, check the browser error. The messages below are Chromium errors, not Shadowrocket rule names.

Error: ERR_NAME_NOT_RESOLVED

Cause: The browser could not resolve the destination hostname to a usable address. The hostname may be mistyped, or the DNS server in use may not be able to resolve it. Fix: Check the actual hostname in the address bar, then try a known resolvable domain on the same network. Confirm DNS is working before changing the position of FINAL; moving it will not fix a DNS problem.

Error: ERR_CONNECTION_REFUSED

Cause: The connection attempt was refused—for example, an HTTPS destination did not accept a connection on the expected TCP port 443. Fix: First check whether the actual policy is REJECT, then verify the URL scheme and port. If you are testing a service you manage, make sure it is listening on the expected port.

FAQ: what to check first when a rule does not match

Why does the log show PROXY after I added DIRECT?

First, go to Home → Global Routing and confirm Config is selected. Then return to Config and make sure the active file is the one you edited. Next, check the [Rule] section from the first line down for an earlier suffix or keyword match. If you find one, move the exact exception above it.

Why does one webpage show different policies?

A page’s text, images, and scripts may come from different hosts, and the page may redirect. In Data, compare the request times with each connection’s destination hostname; don’t rely on the browser tab title alone. To apply the same policy to another resource host, add an exact rule for that host instead of broadening the match to a keyword.

Connectivity Test passes, so why won’t the site load?

Connectivity Test checks its test target. It does not confirm that the current webpage matched the expected policy or that all page resources are reachable. Reload the target page, then find its connections in Data. If a connection uses DIRECT, first check whether your local network can reach the site. If it uses PROXY, check the selected route.

Can Scene in Global Routing replace Config?

When verifying an individual rule, keep Global Routing set to Config. Proxy and Direct are global routing modes, not modes for testing individual rules. Scene selects a routing method based on its settings, so changing scenes can change the result. First confirm how the same destination matches under Config, then switch back to your usual Scene and check again.

Download Shadowrocket and browse the guides

The iPhone and iPad app costs $2.99 as a one-time App Store purchase; check the App Store listing for system requirements. The Mac (Apple silicon and Intel), Windows, Android, and Linux versions are free. Download installers from this site’s download page.

Download Shadowrocket