This guide is for users who have already imported their own service into Shadowrocket and are ready to edit Config. First, distinguish Global Routing from rule policies; then learn how domain, IP, and fallback rules work. Finally, test matching with a minimal rule snippet. The key question is “Which condition does the request match, and which policy does that rule specify?”—not which route to use based on the website’s name.
1. Check that Global Routing is set to Config
Having rules in a file doesn’t mean your current connection is using them. Home manages existing connections and subscriptions, Config manages configuration files, and Settings manages app preferences. Before troubleshooting, open Global Routing on Home, make sure it’s set to Config, and check which file is enabled in Config. The steps below use the iPhone/iPad interface.
| Global Routing options | What to check |
|---|---|
| Proxy | Handles traffic in global proxy mode; don’t use it to verify individual rules in Config. |
| Direct | Handles traffic in global direct mode; editing rules doesn’t switch routing back to Config. |
| Config | Uses the current configuration’s rules to determine connection policies. This is required for the rule tests in this guide. |
| Scene | Changes routing behavior according to the selected Scene. When troubleshooting, first confirm which settings the current Scene is using. |
Settings → On Demand controls when a VPN connection is established based on conditions. It doesn’t determine whether a domain uses DIRECT or PROXY. Before testing, make sure the connection is established, then check which rule matches; otherwise, you might mistake “the tunnel isn’t connected” for “FINAL isn’t working.”
2. A rule consists of a type, a condition, and a policy
Common rules use commas as separators. The first three fields are typically the rule type, matching condition, and policy; some rules also accept additional parameters. FINAL is an exception: it has no separate matching condition, so the policy goes right after it. Don’t use Chinese commas or enter a full URL from the browser’s address bar as a domain condition.
[Rule]
DOMAIN,api.example.com,PROXY
DOMAIN-SUFFIX,example.org,DIRECT
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
FINAL,PROXY
Here, [Rule] is the rules section in the configuration. If the file already contains this section, add rules to it instead of repeatedly appending sections with the same name at the end of the file. The example above is a rule snippet, not a complete configuration with all other settings, and it won’t create proxy connections automatically.
DIRECT: Connects directly to the target without proxying the outbound traffic.PROXY: Routes traffic through a proxy. A usable connection and the appropriate selection must already be available in Home.REJECT: Blocks matching connections. Use it only for targets you explicitly want to block.- Custom policy names: Use a name that matches a policy or policy group already defined in the current configuration. You can’t just enter a new name at the end of a rule.
3. DOMAIN, DOMAIN-SUFFIX, and DOMAIN-KEYWORD: What’s the difference?
Domain rules check the target hostname, not the URL path or query parameters. For example, when visiting https://api.example.com:443/v1/status, use api.example.com as the domain condition—without https://, port 443, or /v1/status. Port numbers aren’t matching fields for these three domain rule types.
| Rule examples | What it matches | Boundary examples |
|---|---|---|
DOMAIN,api.example.com,PROXY | Matches only the exact hostname api.example.com. | Doesn’t match www.example.com or x.api.example.com. |
DOMAIN-SUFFIX,example.com,PROXY | Matches example.com and all its subdomains. | Matches api.example.com, but not notexample.com. |
DOMAIN-KEYWORD,example,PROXY | Checks whether the hostname contains the string example. | May match notexample.com; this is broader than a suffix rule. |
To match a domain and all its subdomains, use DOMAIN-SUFFIX; there’s no need to write *.example.com. The asterisk isn’t required to express the subdomain scope here. To make an exception for just one API hostname, put DOMAIN before the broader DOMAIN-SUFFIX rule.
[Rule]
DOMAIN,api.example.com,PROXY
DOMAIN-SUFFIX,example.com,DIRECT
FINAL,PROXY
In this order, api.example.com matches the first rule and uses PROXY. www.example.com doesn’t match the first rule, so it continues to the second and uses DIRECT. If you move the second rule to the top, api.example.com will match DIRECT first; later, more specific rules won’t change its policy.
4. How IP-CIDR, GEOIP, and no-resolve work
IP-CIDR matches an address based on its network range; GEOIP matches an IP based on its location in the geolocation database. These rules work with IP information—not webpage language, account region, or domain registration location. A domain may resolve to multiple addresses or use content delivery nodes in different regions, so a GEOIP result doesn’t necessarily tell you where a website is based.
[Rule]
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXY
192.168.0.0/16covers 192.168.0.0 through 192.168.255.255 and is commonly used on local networks. It doesn’t cover all private address ranges.10.0.0.0/8covers 10.0.0.0 through 10.255.255.255. If your network uses other ranges, add them as needed; don’t assume these two rules cover every internal network.GEOIP,CN,DIRECTsends target IPs that the database identifies as belonging to CN through DIRECT. Database classification and actual connectivity are separate issues.no-resolvemeans not to trigger an additional domain lookup just to match this IP rule. It doesn’t disable DNS or prevent an existing IP address from matching.
If the target is a domain and no IP is available for the check, an IP rule with no-resolve won’t trigger an extra lookup just to match itself. So “the domain eventually resolves to a private IP” doesn’t mean “this no-resolve rule will definitely match earlier.” To handle known internal domains reliably, add an explicit DOMAIN or DOMAIN-SUFFIX rule before the IP rule.
5. Rules are checked from top to bottom; put FINAL last
In normal rule processing in Config, rules are checked in order, and the first match determines the policy. Don’t assume that a more specific rule automatically takes priority: DOMAIN won’t skip a DOMAIN-SUFFIX rule above it just because it’s more precise. The configuration author must set the order explicitly.
[Rule]
DOMAIN,api.example.com,PROXY
DOMAIN-SUFFIX,example.com,DIRECT
DOMAIN-SUFFIX,blocked.example.net,REJECT
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXY
These snippets illustrate, in order, an exact-match exception, a domain range, an explicitly blocked target, a local network address, a geographic IP rule, and a final fallback. This is an example of rule order, not a recommended configuration for every network. If your existing services or local resources need different policies, keep your own conditions and check for overlaps one by one.
| Test target | Expected match | Why |
|---|---|---|
| api.example.com | First rule: DOMAIN | PROXY; the later example.com suffix rule is not checked. |
| www.example.com | Second rule: DOMAIN-SUFFIX | DIRECT; there’s no need to wait for GEOIP to decide. |
| blocked.example.net | Third rule: DOMAIN-SUFFIX | REJECT; blocking the connection is the intended result. |
| 192.168.1.20 | Fourth rule: IP-CIDR | DIRECT; the target itself is an IP address in this range. |
| A target that matches none of the earlier rules | FINAL | PROXY; this doesn’t mean an earlier rule is broken. |
Put FINAL at the end of the rule list. If it appears earlier, later rules won’t get a chance to match as intended. When editing an existing configuration, find its current FINAL and insert new rules before it; there’s no need to add another FINAL for each rule type.
6. Test whether a rule works with minimal changes
Don’t change DNS, connection parameters, policy groups, and a large number of rules all at once; if something goes wrong, it’ll be hard to identify the cause. Keep a copy of the original configuration, then add just one easy-to-identify domain rule. Rules determine the outbound policy; connection parameters for protocols such as Shadowsocks, VMess, VLESS, Trojan, Hysteria2, WireGuard, and others come from your existing service configuration. Changing rules can’t fill in missing connection details.
-
Back up the current configuration
Open Config and save a copy of the current configuration or export a backup before editing the file in use. Don’t replace the original with an example snippet containing only [Rule]; it isn’t a complete configuration.
-
Add a single rule
Add the target rule inside [Rule], before the existing FINAL. For a single-host test, use DOMAIN and enter only the hostname as the match condition. Also check whether an earlier rule already covers that same domain.
-
Check the current routing mode
After saving, confirm in Config that the file is enabled, then go to Home → Global Routing → Config. If you were using a Scene, first rule out any automatic switching it may cause, then run a single test.
-
Establish a new connection
Close the target page or app and reopen it; if needed, disconnect and reconnect the VPN. Existing long-lived connections may keep the policy they used when first established, so refreshing the same page alone won’t confirm that all rules have been reevaluated.
-
Check the connection log
Use the connection log to check the target hostname, target IP, matching rule, and final policy. First confirm whether the expected rule matched, then check whether the selected connection can reach the target. Don’t rely solely on whether the webpage loads.
Updating Subscribe in Home mainly refreshes connection details provided by an existing subscription; it doesn’t automatically change the rules in the current Config to the ones you just wrote. By contrast, downloading a remote configuration again may replace its contents. Before editing, make sure you know whether you’re working with a subscription, a remote configuration, or a local copy.
7. Tell connection errors apart from rule issues
The messages below are network errors that may appear in the connection log, not fixed messages from the rule parser. First check the final policy in the log: a REJECT match, a failed connection to the proxy service, and a target server refusing the connection each call for a different fix. An error message alone doesn’t prove that your DOMAIN-SUFFIX syntax is wrong.
Error: Connection refused
Cause and fix: The other end refused the connection, often because no service is listening on the port at that address. Check the log to see whether the proxy server or the target server refused it, then verify the address and port of your existing service. Changing a domain rule to GEOIP won’t fix an incorrect port.
Error: Operation timed out
Cause and fix: The connection didn’t complete before the timeout. The selected outbound, target service, or current network may be involved. Check which policy matched, then test one variable at a time with the same target and network conditions. Don’t reorder the entire rule list at once.
Why doesn’t DOMAIN also match subdomains?
DOMAIN matches only the exact hostname. To match both example.com and api.example.com, use DOMAIN-SUFFIX,example.com,PROXY. Then check whether an earlier rule matches first.
Why isn’t a rule at the bottom doing anything?
Open [Rule] in the active Config and find FINAL. Move the rules you want evaluated above FINAL, then check whether an earlier DOMAIN-SUFFIX or DOMAIN-KEYWORD rule already covers the same target.
If switching to Proxy works, does that mean the rule is wrong?
It only shows that the two routing modes produce different outbound results. Go to Home → Global Routing → Config and check whether the target matched DIRECT or REJECT. If the wrong condition matched, adjust that condition or its order instead of deleting all direct-connection rules.
Why didn’t updating Subscribe change the rules?
First distinguish Subscribe in Home from the configuration file in Config. In Config, check which file is enabled and review its [Rule] entries. Updating a connection subscription doesn’t update the rules file or automatically switch global routing to Config.
Get Shadowrocket and the basics
iPhone and iPad: a one-time $2.99 purchase on the App Store from Shadow Launch Technology Limited. Check the App Store listing for system requirements. Mac (Apple silicon/Intel), Windows, Android, and Linux versions are free. The download page lists how to get Shadowrocket on each platform, and the getting-started guide covers importing and checking connections for services you already have.