This guide is for users who have made their first connection and are ready to edit Config. Start by distinguishing match conditions from actions, then use six rule types to understand how rules are evaluated from top to bottom. The examples explain syntax; they are not a complete configuration to replace your existing setup. Proxy connections assume you already have a service provider, server, and subscription.
1. Check Global Routing Before Editing Config
Shadowrocket rules answer two questions: what conditions a connection matches, and which action to take when it does. Rules do not create servers or make unavailable servers work. Before editing, make sure a usable server is selected in Home and run a basic connectivity test.
Home manages servers and connection status, Config manages configuration files, and Settings manages app preferences. To route traffic according to configuration rules, select Config under Home → Global Routing. Editing a file without enabling that configuration does not show whether its rules work.
| Mode | What it does | How to check it in this guide |
|---|---|---|
Config | Uses the rules in the current configuration to choose an action. | Use this mode to test rules. |
Proxy | Routes traffic through a proxy instead of applying the domain-by-domain rules in this guide. | Can help check whether the proxy route is working. |
Direct | Routes traffic directly to its destination. | Cannot verify whether a particular PROXY rule matches. |
Scene | Routes traffic according to the configured scene. | Check the scene configuration first; use Config when learning how a single ruleset works. |
On Demand controls when a connection starts or stops; it does not replace domain or IP rules. If the connection reconnects automatically, check Settings → On Demand separately. Do not assume that an automatic connection means a DOMAIN rule triggered it.
2. Rule Structure and Evaluation Order
Most basic rules use a comma-separated structure: type, match value, and action. Rules go in the [Rule] section of the configuration and are generally checked from top to bottom. The first matching rule determines how the connection is handled; later, more specific rules do not override it automatically.
[Rule]
DOMAIN,login.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECTIn this example, login.example.com matches the first line and uses DIRECT. www.example.com does not match the first line, so it reaches the second line and uses PROXY. FINAL handles any other connection that does not match. If you move the second line above the first, the login host will match the suffix rule first.
These figures describe the basics covered in this guide; they do not mean Shadowrocket supports only six rule types. Use English commas and put one rule on each line. Avoid copying full-width punctuation or invisible characters from rich text.
3. DOMAIN, DOMAIN-SUFFIX, and DOMAIN-KEYWORD
Domain rules match the hostname associated with a connection, not the webpage path. Enter example.com, not a full URL with a scheme, port, and path. A word in the URL path does not match DOMAIN-KEYWORD just because it appears in the URL.
| Rule type | Matches | Does not match |
|---|---|---|
DOMAIN,example.com,DIRECT | example.com | www.example.com |
DOMAIN-SUFFIX,example.com,PROXY | example.com、api.example.com | notexample.com |
DOMAIN-KEYWORD,example,PROXY | Domains with example in the hostname | Requests where example appears only in the webpage path |
DOMAIN: Exact match for a single host
Use DOMAIN to change how a single host is handled—for example, route login.example.com directly while keeping other subdomains on the proxy. It does not include subdomains automatically. Put exact-match exceptions before broader rules that could match them.
DOMAIN-SUFFIX: A root domain and its subdomains
Use DOMAIN-SUFFIX to manage a group of hosts by domain boundary. Enter example.com; there is no need to add *.. It matches both the root domain and its subdomains, but not notexample.com.
DOMAIN-KEYWORD: A substring in the hostname
DOMAIN-KEYWORD has a broader reach and can match unexpected domains. Unless substring matching is specifically needed, prefer DOMAIN or DOMAIN-SUFFIX. A keyword rule placed earlier also takes precedence over exact-match rules that follow it.
4. GEOIP and IP-CIDR: Match by Destination IP
IP rules use the destination address, not text in the URL. When connecting to a domain, DNS resolution may be needed before an IP rule can be evaluated. Changes in DNS results, differences between IP databases, and CDN routing can all affect which rule matches.
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
IP-CIDR,192.0.2.0/24,REJECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXYGEOIP,CN,DIRECT means use DIRECT when the destination IP is classified as CN in the database being used. It does not identify a website's language or where its operator is located. A Chinese-language site may use addresses in other regions, and one domain may resolve to multiple addresses.
- IP-CIDR:
192.168.0.0/16covers a private IPv4 address range and is often used when local network traffic needs to connect directly. Specify a range that matches your actual network. - Prefix length: For IPv4,
/32matches one address, while/24covers 256 addresses. Smaller numbers generally cover larger ranges, so do not shorten the prefix without a reason. - no-resolve: This parameter prevents a domain from being resolved solely to check this IP rule. It does not disable DNS globally or guarantee that a domain request will match the rule.
- Example address:
192.0.2.0/24is a documentation-only example range. It illustrates the syntax and does not mean you should block a real service in your configuration.
If the destination uses IPv6, an IPv4-only IP-CIDR rule will not cover that connection. Check the relevant IPv6 rules and network settings separately. A correct IPv4 example does not mean every address family is covered.
5. Using PROXY, DIRECT, REJECT, and FINAL
Match type and action are two separate things. DOMAIN-SUFFIX determines which domains match; PROXY determines what happens to matching traffic. Changing the last field of a rule from DIRECT to PROXY changes the outbound route, not the domains it matches.
| Action | What it does | What to check |
|---|---|---|
PROXY | Sends traffic through a proxy. | Make sure the selected server or relevant policy is available. |
DIRECT | Connects directly to the destination. | Make sure the destination is reachable on your current network. |
REJECT | Blocks connections that match the rule. | Make sure the blocked range does not include required services. |
FINAL is a catch-all rule with no domain or IP match value. Its syntax is FINAL,action. Put it at the end of the rules section. If FINAL appears earlier, rules below it cannot handle connections it has already caught.
[Rule]
DOMAIN,ads.example.com,REJECT
DOMAIN,login.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXYThis example handles specific exceptions first, broader matches next, and everything else last. ads.example.com is blocked; login.example.com connects directly; other domains under example.com go through the proxy. Even if they resolve to CN addresses, the earlier domain rule has already determined the action, so GEOIP is not evaluated.
6. Save, Enable, and Test Rules in Config
Keep a copy of the current working configuration before making changes. Updating a server subscription and updating a rules file are separate operations: a successful server list refresh in Home does not mean the rules in Config have changed. Remotely managed configurations may overwrite local edits when updated, so check where the file came from before editing it.
- Check the baseline. Select a server in Home, turn on the connection, and run Connectivity Test. A successful test only confirms that the tested route is working; it does not mean every website is reachable.
- Find the active configuration. Open Config and check which file is enabled. Use that file's edit option to inspect the
[Rule]section. Keep the other configuration sections; do not replace the entire file with the snippets in this guide. - Change one variable at a time. Add the DOMAIN or DOMAIN-SUFFIX rule you need, place it before relevant broader rules and FINAL, then save.
- Check that the change is active. Enable the edited configuration, then select Config under Home → Global Routing. Reconnect if needed.
- Make a new request. Close the existing page or app connection before testing again. Existing long-lived connections may keep the outbound route selected when they were established, so they do not reflect how new rules behave.
- Check the evidence. Review connection records or logs to verify the destination hostname, destination IP, and action used. If the issue persists, restore the last working configuration and check DNS or the outbound route.
When testing, distinguish the port from the rule's scope. HTTPS commonly uses destination port 443, but DOMAIN,example.com,DIRECT is not limited to port 443. If a webpage works but another service on a different port fails, check the service listener and network reachability rather than assuming the domain rule failed.
7. When a Connection Fails, Separate Errors from Rule Matching
An error message describes one part of a failed connection; it does not prove that a rule is wrong. The following errors may appear during network troubleshooting and are not Shadowrocket-specific rule syntax messages. Consider the failed destination and the actual outbound route when diagnosing the cause.
Error: Connection refused
Cause: The destination or an intermediate device actively refused the connection, possibly because nothing is listening on that port.
What to do: First determine whether the failed destination is the proxy server or the website, then check the relevant address and port. After confirming which rule matched, check the service status for that outbound route.
Error: Operation timed out
Cause: The connection did not complete before the timeout. The network path, filtering, or an unreachable destination may be involved.
What to do: Run Connectivity Test in Home, then check the DIRECT and PROXY routes separately. Change one rule for the destination at a time; avoid changing DNS and the server simultaneously.
REJECT is supposed to block the connection. If it blocks a required resource, narrow the rule's scope or put a specific allow exception before it. Repeated retries will not turn a matched REJECT rule into PROXY.
8. Common Questions About Rules
Why didn't adding a DOMAIN rule affect subdomains?
DOMAIN matches only the hostname you specify. To cover a root domain and its subdomains, use DOMAIN-SUFFIX and make sure the rule comes before other rules that could match. If only one subdomain needs an exception, add a separate DOMAIN rule for it.
Why doesn't a rule on the last line take effect?
First check whether it comes after FINAL. Move the specific rule above FINAL, then check whether an earlier DOMAIN-SUFFIX or DOMAIN-KEYWORD rule already matches. Rules do not override earlier ones just because they appear later.
Why is traffic still using PROXY when GEOIP is set to CN?
Check first whether an earlier domain rule selects PROXY, then check the destination's actual resolved address and its classification in the IP database. GEOIP does not use a website's language to determine its location. To set a fixed route for a known domain, add a specific DOMAIN rule earlier and test it.
Why are the rules still old after a successful subscription refresh?
Check the server subscription and Config file separately. In Config, confirm which file is enabled and review its rules before deciding whether to update the corresponding remote configuration. Save local edits first; refreshing a subscription does not necessarily update rules.
What should I do if images still won't load in an app, even though the browser works?
Check the actual hostname used for the image request rather than testing only the main site. Make a new request and review the connection records for another resource domain, a different destination IP, or an interface blocked by REJECT. Then add the narrowest exception needed for that destination.