At a glance

This guide is for users who have already imported their own service details into Shadowrocket and are ready to edit routing rules. First check the active config and Global Routing mode, then distinguish domain, IP, and fallback conditions. By the end, you’ll know which requests a rule covers, where to place it, and which connection record to check after making changes.

1. Check how to get the app and where to find rules

If you haven’t installed Shadowrocket yet, visit the downloads page for all platforms and choose your device: iPhone and iPad versions are available on the App Store for a one-time payment of $2.99. The developer is Shadow Launch Technology Limited; check the App Store listing for system requirements. The Mac (Apple silicon and Intel), Windows, Android, and Linux versions are free. This guide covers client rules only. It does not provide, sell, or recommend nodes or subscriptions; the steps below assume you already have your own provider and subscription.

Routing rules are in the [Rule] section of a config file. The connection selected in Home provides the proxy route, while the config enabled in Config determines how traffic is routed. These are separate selections. Importing service details does not mean a config with rules is enabled, nor does it guarantee that a request will use a proxy.

  1. Back up your config

    Open Config, check which config is enabled, and save a copy before making changes. Edit only the [Rule] section in the copy, leaving the existing connection settings and other config sections intact so you can revert if needed.

  2. Check the proxy route

    Return to Home and make sure your own service details are imported and the proxy route you need is available. PROXY in a rule is a routing policy; it does not create a server address, port, or authentication details.

  3. Choose a routing mode

    Go to Home → Global Routing → Config to route traffic according to the config. If Proxy or Direct is selected, don’t assume a particular line in [Rule] is active based only on the result of a connection.

  4. Edit and verify

    Return to Config, open the config’s editor, make your changes, and save. Confirm that the same config is still enabled. Then start a new request and check its destination, matched rule, and routing policy in the connection log.

2. Rule format: condition first, policy last

Common rules use commas to separate fields. Most conditional rules follow the format type,match value,policy. FINAL has no match value, so specify the policy directly. For domain rules, don’t include https://, a page path, query parameters, or a port. For https://example.com:8443/docs, the domain value is example.com, not the full URL.

[Rule]
DOMAIN,example.com,PROXY
DOMAIN-SUFFIX,example.com,DIRECT
DOMAIN-KEYWORD,example,REJECT
GEOIP,CN,DIRECT
IP-CIDR,192.0.2.0/24,DIRECT,no-resolve
FINAL,PROXY

The examples above show six formats; don’t paste the whole set into a live config without reviewing it. A request may match more than one condition, and an earlier rule takes precedence over later ones. 192.0.2.0/24 is a documentation-only example subnet, not a usable server address. example.com and its subdomains are also used only to illustrate the syntax.

6 types
Common match keywords covered in this guide
3 policies
Example policies: PROXY / DIRECT / REJECT
Last line
FINAL handles requests that didn’t match earlier rules

Check in order: find the matched rule, then check the route

After editing rules, first check which line a new request matched. If the policy is correct, then check whether the route it uses can connect. Don’t use whether a webpage loads as a substitute for checking the matched rule.

3. DOMAIN, DOMAIN-SUFFIX, and DOMAIN-KEYWORD: where each applies

All three rule types depend on a target domain being available for matching, but they cover different scopes. DOMAIN matches an exact domain. DOMAIN-SUFFIX covers the specified domain and its subdomains. DOMAIN-KEYWORD matches a string anywhere in the domain, regardless of domain levels. The more specific the requirement, the more useful a clearly scoped rule is.

How three rule types match the same example domain
Rule exampleMatchesScope
DOMAIN,example.com,PROXY example.com Doesn’t include api.example.com; add a separate rule for it.
DOMAIN-SUFFIX,example.com,DIRECT example.com、api.example.com、img.api.example.com Matches at domain boundaries, not by checking for any arbitrary string at the end.
DOMAIN-KEYWORD,api,REJECT api.example.com、myapi.example.com Matches if the keyword appears anywhere in the domain, which may catch unrelated requests.

If you want to route just one API domain through a proxy, DOMAIN,api.example.com,PROXY is easier to verify than a keyword rule. To send all subdomains of the same domain directly, use DOMAIN-SUFFIX,example.com,DIRECT. Use a keyword rule when you genuinely need to match the same string across different domain levels; a short keyword match doesn’t prove that a domain belongs to a particular service.

4. GEOIP and IP-CIDR: match by destination IP

GEOIP,CN,DIRECT matches based on the destination IP’s result in a geolocation database; CN is a region code. It doesn’t check the webpage content, domain suffix, account region, or the device’s current location. CDNs, different DNS results, and differences between databases can all lead to different IP matches for the same domain.

IP-CIDR matches a specific IPv4 subnet. In 192.0.2.0/24, the first 24 bits are the network prefix, covering addresses from 192.0.2.0 through 192.0.2.255. To specify a single IPv4 address, use /32. A larger prefix length usually means a smaller match range. Don’t assume a single IP returned by one DNS lookup is the website’s permanent, complete set of addresses.

IP-CIDR,192.0.2.8/32,DIRECT,no-resolve
IP-CIDR,192.0.2.0/24,PROXY,no-resolve
GEOIP,CN,DIRECT

In this set of standalone examples, a destination of 192.0.2.8 matches the single-address rule first, while 192.0.2.20 matches the subnet rule below. If /24 is on the first line, the single-address exception won’t take effect. Whether to use no-resolve depends on your routing design; it isn’t a universal speed-up switch.

5. FINAL and rule order: exceptions first, broader rules next, fallback last

Rules are generally checked from top to bottom, and the first match determines how the request is handled. Shadowrocket doesn’t combine all matching results and then choose the “most specific” rule. “Specific rules first” means arranging them in that order yourself; the app doesn’t sort them automatically. FINAL handles requests that didn’t match earlier rules and belongs at the end of the rule list.

[Rule]
DOMAIN,blocked.example.com,REJECT
DOMAIN,api.example.com,PROXY
DOMAIN-SUFFIX,example.com,DIRECT
IP-CIDR,192.0.2.0/24,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXY

This example uses the order “individual domain exception → domain scope → IP condition → fallback”; it isn’t a fixed template for every setup. Before using it, decide whether you actually want traffic for a particular region to go direct and whether unmatched traffic should use PROXY. If your existing config uses policy group names, keep them and verify their definitions; don’t substitute a name that doesn’t exist.

  1. blocked.example.com is rejected by REJECT on the first line, so the domain-suffix rule below isn’t checked.
  2. api.example.com is handled by PROXY on the second line. It won’t be changed to a direct connection just because it belongs to example.com.
  3. www.example.com matches the third line and connects directly over the current network using DIRECT.
  4. Requests that don’t match any domain or IP condition are ultimately handled by FINAL,PROXY.

DIRECT doesn’t guarantee access; it simply bypasses the selected proxy route. PROXY doesn’t guarantee the destination is reachable; it still depends on the current proxy and remote service. REJECT actively blocks matching requests. If your browser reports a connection failure, first check whether the rule is meant to reject the request before changing protocol settings.

6. What to check when rules don’t work as expected

When testing, change one condition at a time and start a new connection. An existing browser connection may continue using the route chosen when it was established; saving rules and refreshing the page may not trigger a fresh routing decision. Record the test destination, current Global Routing mode, enabled config, matched rule, and final policy to distinguish syntax issues from connection issues.

Why isn’t a subdomain routed through the proxy when I use DOMAIN?

Check whether the request is going to api.example.com while your rule only specifies example.com. To include the domain and its subdomains, use DOMAIN-SUFFIX. To match just one subdomain, add a corresponding DOMAIN rule and place it before broader rules.

Why are all requests still going direct after I added a rule?

First go to Home → Global Routing and make sure Config is selected instead of Direct. Then open Config and check which file is actually enabled. Editing a copy that isn’t enabled won’t change how current connections are routed.

Why did my local rules revert after a subscription update?

First distinguish a service subscription update in Home from a remote config update in Config. The former mainly maintains service entries; the latter may replace config contents. To keep local rules, save a separate copy and compare the [Rule] sections before and after an update. Don’t repeatedly test changes in your only copy.

Does enabling On Demand automatically apply the rules?

Settings → On Demand controls when a connection is triggered; it doesn’t replace the routing mode selected in Global Routing. After a connection starts, check the active mode and config. A connected status alone doesn’t mean a particular rule handled the request.

If the connection log shows the expected rule matched, check the transport layer next. The following raw error messages may appear during connection diagnostics; they aren’t standard messages for [Rule] syntax errors. Wording varies by system, so consider whether the error occurred on a direct connection or through the proxy route.

Error: Connection refused

Cause: The destination host or an intermediary explicitly refused the connection, possibly because nothing is listening on the port. Fix: Check the matched policy first, then verify your own service address, port, and service status. If the match is DIRECT, check the direct destination rather than changing only the proxy settings.

Error: Operation timed out

Cause: The connection or data transfer didn’t complete within the allotted time. This message alone can’t tell you whether the cause is the rules, DNS, or the network route. Fix: Record the destination and matched policy, test domain resolution and the selected route separately, then check the service port. Don’t change multiple rules and protocol settings at once.

7. Quick checklist before saving a config

More rules don’t necessarily make a config easier to maintain. Duplicate suffixes, overly short keywords, and an early fallback can all make exceptions harder to verify. After making changes, test at least three destinations: an exact-match exception, another subdomain under the same suffix, and a domain that doesn’t match. For IP rules, also check the destination address and DNS result separately.

A useful way to remember the rule types is to group them by what they answer: DOMAIN, DOMAIN-SUFFIX, and DOMAIN-KEYWORD check whether a domain matches; GEOIP and IP-CIDR check whether a destination IP matches; FINAL determines how to handle everything else. Learn these three roles and the top-to-bottom order before adding more complex policies, and you’ll be able to pinpoint the relevant line when troubleshooting.