Shadowrocket Configuration Guide Rules & Match Order

Configuration File Structure: Separate Data from Rules

In Shadowrocket, server details and configuration files serve different purposes. Server details specify where to connect, which protocol to use, and how to authenticate. Configuration files define how requests are handled, which destinations connect directly, and which use a proxy policy. Seeing servers after importing a subscription does not mean the intended rules file is selected. Likewise, saving a file with a complete set of rules does not mean the proxy endpoints it references have usable parameters. When troubleshooting, verify these two parts separately.

Files in Config and the Active File

In Config, first check which file is currently active, then review the file you plan to edit. When the list contains multiple configurations, file names help identify them but do not prove that their contents are the same. Before editing, keep a copy and note the current Global Routing mode and selected server. If a change disrupts access, you can switch back to the original file for comparison. For remote configurations, also check how updates work to avoid having local edits overwritten by the source file.

Configuration files typically use sections, with section names in square brackets and settings or rules on separate lines. General contains common options, Rule defines request routing, Host specifies static hostname mappings, and URL Rewrite handles matching URLs. Each section has a different role; being in the same file does not make them one rule list that runs from top to bottom. In particular, do not paste Host entries into Rule.

[General]
bypass-system = true
dns-server = system

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
FINAL,PROXY

Keep the Context When Reading Snippets

This is a minimal reference snippet: the two entries in General use equals signs for assignment, while Rule entries use English commas as separators. It illustrates the relationship between general options, domain rules, private-address rules, and the fallback rule; it is not a substitute for your server details. PROXY sends a request to the proxy policy, but the final route still depends on the active configuration and selected server. example.com is a reserved example domain. When adapting the snippet, use the actual destination to handle, not your provider's server address.

To read a rule, start with the rule type in the first field, then check the match target, followed by the policy and any optional parameters. For example, an IP-CIDR rule has an extra no-resolve parameter compared with DOMAIN-SUFFIX; it concerns DNS resolution for matching, not the policy name. FINAL has a different structure and no match-target field. When copying, preserve English punctuation and field order. Make sure your keyboard does not turn commas into full-width commas or add extra characters to section names.

Put comments on their own lines and explain why an exception is needed instead of merely repeating the rule. For snippets from other sources, first identify the section they belong to and any prerequisites, then decide where to insert them. Do not assume configurations with similar section names are interchangeable. Check Shadowrocket's in-app documentation for supported settings, optional parameters, and features. If an entry is not recognized, test it on its own.

Local Edits and Subscription Updates

Subscribe is mainly for updating server entries. Updating a Config file may change rules, DNS, or other general behavior. Even when both come from the same provider, they do not necessarily update the same content. Before updating, identify which type of content is involved, then check whether the selected server or rules file changed. Blaming every connection issue on an expired subscription can obscure a file switch or a replaced local exception.

After saving a configuration, return to the screen where you use it and verify that it is active; do not just confirm that the editor closed. Some options only affect new connections, while existing connections may continue using previously established channels. For a comparison, close old requests and start new ones. If you need to reconnect, save any work in progress first. See the setup guide for the full workflow; the remaining sections explain how to assess individual settings.

Domain Rules: Exact Matches, Suffixes, and Keywords

Domain rules are useful for specifying which policy a service should use, and are generally easier to maintain than constantly changing service addresses. Before choosing a type, decide whether you need to match one full hostname, a domain and its subdomains, or any domain containing a particular string. These types cover progressively wider scopes; do not choose the broadest just because it is shorter to write. The wider the scope, the more carefully you should check for unrelated requests it might match.

DOMAIN: Exact Hostname Match

[Rule]
DOMAIN,api.example.com,PROXY
DOMAIN,static.example.com,DIRECT
FINAL,PROXY

DOMAIN matches a complete hostname. The first line applies only to api.example.com; it does not automatically include example.com or deeper subdomains. Use it for a single endpoint or a specific exception ahead of a broader rule. Enter the hostname only—no https://, port, path, or query string. Those URL components are not DOMAIN match fields, and including them changes what the rule is meant to match.

Exact rules are easy to review because each entry corresponds to a specific service. The tradeoff is that when a page requests other domains, you need to check their policies separately. A match on the main domain does not mean login, images, verification, and API requests use the same route. For troubleshooting, get the actual hostname from the failed request record, then decide whether to add a rule. Guessing dependent domains from how a URL looks can miss the actual point of failure.

DOMAIN-SUFFIX: Match a Domain and Its Subdomains

[Rule]
DOMAIN,api.example.com,PROXY
DOMAIN-SUFFIX,example.com,DIRECT
FINAL,PROXY

DOMAIN-SUFFIX,example.com,DIRECT covers example.com and its subdomains. It matches by domain suffix, not by arbitrary string inclusion, so a different domain that merely contains the text example.com is not in the same scope. The example routes api.example.com through PROXY, then sends other requests under that domain through DIRECT. With the exact exception first and the broader rule after it, the relationship between the exception and default behavior is clear.

For a suffix rule, enter example.com rather than copying a full URL from the browser, and do not include a webpage path as part of the domain. Do not assume that *.example.com works here just because it is used in other syntaxes. If you need one hostname, prefer DOMAIN; use DOMAIN-SUFFIX when you need a group of subdomains. Choose the scope based on the service requirements, not on how many rules you want to maintain.

DOMAIN-KEYWORD: A Broader String Match

[Rule]
DOMAIN-KEYWORD,example,PROXY
FINAL,DIRECT

DOMAIN-KEYWORD checks whether a domain contains a specified string. It does not know whether that text is a brand, organization, or domain boundary, so example may appear in multiple unrelated domains. Use keyword rules only when you understand their scope; they can also help with temporary diagnostics, but do not replace a review of the target domains. Short, common, or broad business-related terms are especially likely to cause unexpected matches.

If a keyword rule comes before an exact rule, it can prevent the exact rule from handling those requests. The exact rule does not automatically get higher priority just because it looks more specific. Test three types of target: domains that should match, domains that should not match but contain the same text, and unrelated domains. The rule's scope is suitable for the current configuration only if both matches and exclusions behave as expected.

The Match Target Is Not the Server Name

A domain rule matches the request destination, not the server label shown on Home. Changing a server name does not change the match target for DOMAIN-SUFFIX; changing a rule for the destination domain does not fix server authentication parameters. If the same destination works in Proxy mode but fails in Config mode, first compare the matched policy and route rather than immediately re-entering details in Add Server. Verify changes to these two layers separately.

When reviewing existing domain rules, consider organizing them as exact exceptions, specific suffixes, then necessary keywords, and note the purpose of each group. Before deleting duplicates, compare their policies: the same domain with different policies is not a duplicate you can merge arbitrarily. To block a destination, you can change the policy to REJECT, but the same rules about match scope still apply. See REJECT Rules and How Blocking Works for details.

Connection Policies and the Three Global Routing Modes

Rules tell the client which requests belong to a category; policies tell it how to handle those requests. PROXY, DIRECT, and REJECT are policy keywords used in rules. Config, Proxy, and Direct under Global Routing are modes that apply to overall operation. The two groups are related, but they operate at different levels. Before troubleshooting, note both the current mode and the matched policy; otherwise, you may mistake a change in mode for a fix to a rule.

PROXY, DIRECT, and REJECT

PROXY sends matching requests to the proxy policy. Whether a connection can be established still depends on the selected route, protocol parameters, authentication details, and current network. It does not guarantee access to every destination or create a server automatically. DIRECT connects to the destination directly through the network available to the device. REJECT denies matching requests, and the client may end the connection with a corresponding failure. It does not redirect the request to another server.

[Rule]
DOMAIN,api.example.com,PROXY
DOMAIN,local.example.com,DIRECT
DOMAIN,blocked.example.com,REJECT
FINAL,PROXY

The three examples show proxying, direct connection, and rejection; the domains are for illustration only. If api.example.com fails after matching PROXY, check the route next rather than assuming the client will fall back to DIRECT. If blocked.example.com matches REJECT, a failed connection is the expected policy outcome and is not evidence that the server is unavailable. Before testing, define what success means: access is allowed, a specific route is used, or the request is rejected as intended.

When to Compare Config, Proxy, and Direct

These three modes are described to help structure troubleshooting; they do not mean every type of traffic is necessarily handled in the same way. System traffic, configured bypasses, and specific features may introduce other boundaries. For comparisons, use the same destination and a newly created request, keep the network environment consistent, and check the actual records. A status bar icon or one page loading cannot confirm the route used by every request.

If Proxy works but Config does not, first check whether the destination is handled by DIRECT, REJECT, or another earlier rule, then verify that the correct Config file is active. If both Config and Proxy fail, check the server address, port, protocol, and authentication details. Try another known-working destination to distinguish an overall route issue from a problem with one destination. Direct working shows only that the current network has a viable route; it does not prove that the proxy parameters are correct.

How the Selected Server Relates to Rule Policies

Understand the selected server in Home, the policy groups in the configuration, and the policy names referenced by rules in the same context. A simple configuration can use PROXY to send requests to the current proxy policy. If a more complex configuration references custom policy names, make sure those names exist and point to valid members. Do not copy custom names from someone else's file as if they were universal keywords, or assume that changing a server label keeps every reference valid.

Protocol parameters determine how the proxy connection itself is established. They sit alongside rule policies but form a separate layer. For Trojan, for example, fill in the address, port, password, and TLS-related parameters using your existing server details. Changing a rule from DIRECT to PROXY cannot fix incorrect authentication parameters. See the Trojan parameter guide for guidance on these fields; keep rules and server details as separate troubleshooting tracks.

REJECT also cannot meet every content-filtering need. A domain may serve both essential features and requests you want to block, so rejecting the entire domain could disrupt login, loading, or sync. For encrypted traffic, a domain-level rule generally cannot distinguish different paths on the same host. For finer control, first confirm which information is visible and understand the feature's limits rather than adding increasingly broad keyword rules.

After comparison testing, restore the mode you intend to use and test again. Temporarily switching to Proxy to verify a connection and forgetting to switch back to Config is a common reason rules appear ineffective. The same kind of misdiagnosis can happen if you switch to Direct and forget to restore the original mode. Recording the mode, server, and file together for each test is usually more useful for maintenance than keeping many success screenshots without context.

Host & URL Rewrite: Address Mapping and Request Handling

Host, URL Rewrite, and Rule often appear in the same configuration file, but they do not work in the same way. Host provides static address mappings for specified hostnames. URL Rewrite processes recognizable URLs based on match conditions. Rule selects the connection policy. They address where an address comes from, how a request is handled, and which route a connection uses. When an issue involves multiple layers, verify each one separately.

Host: A Fixed Resolution Result Does Not Choose a Route

[Host]
service.example.com = 192.0.2.10

Here, service.example.com maps to the example address 192.0.2.10. This address is from a documentation-only range and is not a reachable service. Host entries use an equals sign, not the comma-separated format used in Rule, and you cannot append PROXY to specify a policy. If the destination also needs a particular connection method, add a separate Rule entry and use actual connection records to confirm both the destination address and policy are as intended.

Host is suitable when a destination address is known and can be maintained; it is not suitable for arbitrarily pinning addresses for public services that change often. A domain may use regional routing, failover, or address rotation. Fixing a single address bypasses those changes and may stop working later. When adding a mapping, note its purpose, the conditions under which it is expected to remain valid, and how to remove it. Do not treat an address from one lookup as a permanent fix.

The domain in an HTTPS request is also used for certificate verification and service selection. Even if the mapped address accepts a TCP connection, the service may reject the request because of its certificate, SNI, or virtual-host configuration. A Host mapping does not give an arbitrary address a valid certificate for that domain or change server authentication parameters. If you see a certificate error, check the destination service configuration; do not disable verification instead of confirming the address is correct.

URL Rewrite: Understand the Match Scope First

[URL Rewrite]
^http://example\.com/old$ http://example.com/new 302

This example demonstrates a redirect for one exact path over plain HTTP: a regular expression matches the old address, the target URL points to the new address, and 302 indicates a temporary redirect. This is not a domain-routing rule and does not belong in the Rule section. The dot is escaped as a backslash followed by a dot to match the literal separator in the domain. Start and end anchors restrict the scope so the example does not also match longer paths or extra characters.

Query parameters in a URL also affect matching. The dollar sign at the end of the example means that a URL with an additional query string is outside its exact match scope. If query strings should be allowed, redesign the expression to match the actual requirement. Do not remove boundaries or add broad wildcards just to “make everything match.” Before editing, list examples that should and should not match, then test each one to reveal differences in paths, parameters, and escaping.

HTTPS Visibility and Redirect Loops

Being able to route by domain does not mean the full path and headers of an encrypted request are automatically visible. In HTTPS, the path is encrypted, so a domain rule alone cannot establish that URL Rewrite can process it. Further handling of encrypted content requires separate consideration of certificate trust, applicable domains, and privacy. The example uses HTTP so these extra prerequisites are not hidden in a seemingly simple rewrite snippet.

Rewrite rules can also create loops: the old address redirects to the new one, then another rule sends the new address back to the old one, causing repeated attempts or a too-many-redirects error. A target address may also still match the original expression, causing the same rule to apply repeatedly. During testing, inspect the redirect chain rather than only the final page. If you cannot explain each step, narrow the expression and temporarily remove overlapping rules.

To validate Host, leave Rule unchanged and compare only the source of the destination address. To validate URL Rewrite, start with a clear HTTP test URL, confirm the redirect, then check how the destination is routed. If you change all three sections at once, it will be difficult to identify dependencies even if the result works. For normal service requests, keep a copy of the original configuration so test rules do not affect login redirects, form submissions, or other stateful requests.

After updating the source configuration, review Host and URL Rewrite as well as Rule. An address mapping may be out of date, a service path may have changed, or a previously needed rewrite may now conflict with the new behavior. At minimum, maintenance notes should record the target, purpose, and conditions for removal. For entries with no clear source or purpose, disable them in a copy and test before deciding whether to delete them. This is easier to control than keeping unexplained rules indefinitely.