Shadowrocket
Rules and Configuration Guide

01 Configuration file structure and scope

A configuration must first be read correctly; only then can you assess whether its rules behave as expected. Shadowrocket configuration files are usually divided into sections: names in square brackets identify each section, and the lines below are interpreted according to that section’s syntax. The same line can mean different things in different sections. When reviewing or copying an example, check the section name, line content, and target policy together—not just a few keywords in isolation.

What General, Rule, and Host do

[General] contains general settings, such as options related to DNS resolution and bypassing traffic. [Rule] contains rules that determine where connections go. [Host] contains static mappings for specified hostnames. Each answers a different question: “What baseline conditions apply to connections?”, “Which policy should this destination use?”, and “Which address maps to this name?” Since they serve different purposes, changing one section does not necessarily change the outcome of another.

Learn the syntax from a minimal file

The snippets below illustrate the structure; they are not complete configurations for every network. Example domains and documentation addresses do not represent usable services. In practice, keep settings that are still needed in your current configuration and confirm that your existing server works. PROXY is a policy; adding it to a file does not create a server. Likewise, adding a domain rule does not fix that domain’s resolution or service status.

[General]
dns-server = system

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

[Host]
test.example.com = 192.0.2.10

Section headers use English square brackets, rule fields are separated by English commas, and ordinary options connect names and values with an equals sign. Full-width commas, curly quotation marks, and invisible spaces inserted by an input method can prevent otherwise similar text from parsing as expected. After copying, check each line in an editor, especially for explanatory text accidentally appended at the end. Put explanations in the surrounding text or on separate comment lines; don’t append them to policy fields.

A file existing doesn’t mean it’s in use

In Config, first check which configuration is currently selected, then open it for editing. Saving a file that isn’t selected won’t switch the active configuration. Similarly, updating an existing subscription usually changes the server list; it doesn’t mean the rules file was updated too. Check server source, configuration source, and current selection separately to avoid repeatedly editing the wrong item.

Before you start, keep a local copy and note the name of the file currently in use. If the configuration comes from an updateable URL, distinguish the remote original from your local edits: after fetching it again, you may need to review those changes. Don’t treat “saved” as “verified.” Saving only writes the text; whether it takes effect depends on Global Routing, connection status, and the rule that actually matched.

If the file fails to load, check the sections you edited most recently, then look for duplicate section headers or rules placed in the wrong section. If the file opens but connections behave unexpectedly, check the mode, policies, and match order instead. Treat syntax errors and runtime behavior as separate problems. That way, you won’t change DNS, servers, and the entire rule set to fix a comma—and then lose track of the real cause.

03 DOMAIN domain rules

When you know the destination domain, start with a domain rule. A domain rule describes a hostname, not the full URL in a browser’s address bar. For api.example.com, don’t include the protocol, path, query parameters, or page title. In a URL, the slash and everything after it belong to a different part of the address and can’t be used directly as a DOMAIN match field.

Exact and suffix matches

DOMAIN matches an exact domain. Adding example.com does not also add www.example.com. DOMAIN-SUFFIX is suitable for covering a domain and its subdomains: with example.com as the condition, it can match the domain itself and its subdomains. This distinction determines whether a rule affects just one hostname or a group of services under the same domain.

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

Before using a suffix rule, check the domain boundary. It isn’t an arbitrary string-ending comparison, and matching text that merely looks similar doesn’t mean a domain is included. A similar-looking name may belong to a different domain. When troubleshooting, compare the full hostname in the log with the rule field, paying attention to extra subdomains, different top-level domains, and other service domains used after an app redirects.

DOMAIN-KEYWORD has a wider scope

DOMAIN-KEYWORD matches a keyword in the domain. Use it when you genuinely need a string-based match. It doesn’t understand brands, service ownership, or business purpose, so the same text can appear in unrelated domains. The shorter the keyword, the harder it is to predict unintended matches. When you can list full domains, exact rules are usually easier to explain and maintain than broad keyword matches.

[Rule]
DOMAIN,ads.example.com,REJECT
DOMAIN-SUFFIX,example.com,PROXY
DOMAIN-KEYWORD,tracking,REJECT
FINAL,PROXY

This example puts the specific exception before the broader rule. A request to ads.example.com matches the exact reject rule first; other hosts under the same domain then use the suffix rule and go through the proxy. The keyword rule later in the list won’t reprocess connections that already matched. This example demonstrates ordering; it isn’t a general-purpose blocklist. Base the actual reject scope on your own targets and logs.

A webpage often uses more than one domain

The main page, images, scripts, sign-in endpoints, and media may come from different hosts. Setting a policy only for the domain in the address bar doesn’t guarantee that every resource uses the same route. If the page opens but images don’t load, check the actual hostnames of the failed resources instead of immediately applying the same policy to an entire suffix. Widening the scope gradually helps avoid disrupting other services that work normally.

Domain rules also depend on having a hostname available when a connection is handled. If an app connects directly to a numeric address, or the name-to-address association isn’t available at that point, knowing that the address belongs to a website doesn’t mean a domain rule will match. Check the target type shown in the connection record, then decide whether an address rule is needed. Don’t change all unmatched connections to direct just to fix a single request.

After changing a domain condition, send a new request. Browsers and apps may reuse existing connections, so the updated rule might not get a chance to handle the same session. Close and reopen the relevant page, and reconnect if necessary, then check the new records. Judge the result by the new request’s destination and match—not by whether previously loaded content is still visible. A cached page can’t show which rule handled a network request.

When maintaining rules, add a brief note about the purpose of each group, such as “exact-domain exception” or “entire service domain.” If a domain stops working, first check whether the service has switched to another host before deleting the rule. Without notes, accumulated rules can end up assigning different policies to the same domain. Order determines which one wins; the rules aren’t automatically combined into a better result.

05 Rule order, USER-AGENT, and FINAL

In a standard [Rule] list, rules are checked in configuration order, and the matching rule supplies the policy. The process does not automatically pick “the most specific rule.” A specific condition can only match if it appears in a position where it gets a chance to run. If an earlier, broader condition already covers the destination, a later exact rule won’t change the result. Rule order matters as much as the conditions themselves.

Put exceptions before broader matches

[Rule]
DOMAIN,login.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
DOMAIN-KEYWORD,example,REJECT
GEOIP,CN,DIRECT
FINAL,PROXY

In this example, the login domain uses a direct connection first. Other hosts under the same domain go through the proxy under the suffix rule. The keyword rule handles only destinations not already covered that contain the specified text. If you move the suffix rule to the first line, the login domain will match the proxy rule too. The file doesn’t give a longer or more precise-looking line higher priority automatically.

Understand duplicate rules in terms of order. If the same domain has DIRECT first and PROXY later, those aren’t two selectable routes; the first matching rule supplies the result. When checking for conflicts, search not only for identical lines but also for suffix, keyword, and other broad conditions that could include the domain. Different-looking text can still overlap on the same request.

USER-AGENT depends on available request data

USER-AGENT sets a condition based on the request’s User-Agent information. It doesn’t identify an app by name, and including an app name in a rule doesn’t guarantee that every connection from that app will be recognized. The rule can only evaluate information available when the request is handled. For encrypted connections, don’t assume all request headers are automatically visible, and don’t rely on this rule as the sole condition for covering every connection.

[Rule]
USER-AGENT,ExampleClient*,PROXY
DOMAIN,api.example.com,PROXY
FINAL,DIRECT

The client identifier in this example only demonstrates the matching format; it doesn’t refer to a real app. In practice, verify the actual field using request information you can inspect, then check whether the rule matches. Different components of the same app may use different identifiers, and system services may initiate requests on its behalf. If you can describe a destination by domain, keeping a domain condition is usually easier to explain than relying on a guessed request-header value.

FINAL is only the last-resort rule

FINAL selects a policy when none of the preceding rules match and is usually placed at the end of the list. It doesn’t raise priority or fix faulty rules. If you put it earlier in the list, later rules may never get a chance to match. Choose FINAL,PROXY or FINAL,DIRECT based on the route you want for unclassified connections—not simply because another file uses one.

With a proxy fallback, unclassified requests depend on an available proxy route. With a direct fallback, uncovered traffic attempts to use the current network directly. Verify either choice in practice. The key is to understand the result: if a destination matches the final rule, that usually means earlier conditions didn’t cover it—not that the final rule “stole” a connection that should have matched. Check the destination name, address, and rule scope.

When merging configurations, decide which final rule to keep, then place specific conditions before it. Appending two complete files often leaves multiple sections, duplicate rules, and a fallback appearing too early. Start with one working file and move rules over in groups by purpose, checking how each group changes the match results. If something breaks, you can trace it to the most recently added scope instead of guessing across hundreds of lines.

07 URL Rewrite scope and limitations

[URL Rewrite] processes requests based on URL conditions; this is different from the connection routing policies in [Rule]. The former concerns available URL information and how to handle it, while the latter determines the route a connection takes. To send a domain through a proxy, start with a domain rule. Consider rewrite conditions and actions when you need a specific old page URL to redirect to a new one.

Start with the full target, then narrow the regex

A rewrite rule typically includes a matching expression, a target, and a handling method. The example below shows an exact old URL redirected temporarily to a new address. It demonstrates syntax and match boundaries only; you don’t need to visit the example domain. When editing, confirm that the current app accepts the line, then test it with a new request. Don’t rely on whether the file can be saved as proof that the rule works.

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

The opening ^ anchors the start of the expression; the closing $ anchors its end. The dot in a domain is written as \. to match a literal period. Without the escape, a dot in a regex usually matches any single character, which can include addresses you didn’t intend to match. Understand each symbol before editing; that’s easier than changing a few characters in a long expression and hoping the scope stays narrow.

This example does not cover subdomains, extra paths, or query parameters. Adding a query string at the end of a URL may prevent the exact end condition from matching as intended. If you need to handle parameters, first decide whether to preserve, remove, or rearrange them, then design the expression accordingly. Don’t add a broad catch-all pattern: it could also include sign-in callbacks, resource paths, or later pages.

Verify redirects and connection policies separately

A redirect sends the request to a new destination. That destination still needs to resolve and connect under the applicable routing rules. A direct route for the old domain doesn’t mean a different domain after the redirect will also use a direct connection. Record both the original and final URLs when troubleshooting. If you check only the first request, it may look as if the policy failed when the actual issue is the follow-up destination.

Don’t use URL Rewrite to fix server authentication errors, missing protocol fields, or an unreachable DNS service. These problems occur at different layers; changing URL text can’t supply missing connection parameters. If a request times out before the connection is established, start with the server, resolution, and policy. Check the regex and redirect behavior only after confirming that the request has reached a stage where rewriting can apply.

Understand HTTPS visibility separately

HTTPS paths and request headers are inside an encrypted connection. Don’t assume that adding a rewrite line lets you read and change all content. Whether a particular rule can apply depends on the protocol, app behavior, and relevant configuration conditions. Settings involving certificate trust change the security boundary and shouldn’t be treated as a default step for making rules work. Ordinary domain routing doesn’t require access to encrypted content.

If a rewrite doesn’t take effect, first rule out a pattern that doesn’t cover the actual URL, a reused connection, or a cached result. Don’t immediately widen the match or add every domain to a set that needs extra handling. If you can’t verify the purpose of a certificate or setting, stop editing, preserve the last known working state, and confirm its source and necessity before proceeding. Broader rules cost more to verify and can have a wider impact.

Also guard against redirect loops: if the new URL matches the original condition again, the same action may be triggered repeatedly. During testing, check whether the URL keeps changing, the page reports too many redirects, or the log shows repeated destinations. Make the old-URL condition precise and ensure the target no longer matches it. Don’t try to hide a loop by switching proxy servers.

When maintaining a configuration, keep connection rules and URL handling in separate groups. If basic access returns after you remove or disable a rewrite, narrow down the problem in that section instead of immediately changing the entire routing setup. If you only need domain-based routing, leave the rewrite section empty or omit it. A configuration is complete when it meets your needs—not when it includes every available feature.