Shadowrocket
Rules and Configuration Reference

One file, distinct sections

A Shadowrocket configuration can include connection-handling options, routing conditions, domain mappings, and request rewrites. Section names in square brackets separate these functions: [General] contains general processing options, [Rule] contains rules checked in order, [Host] contains explicit domain mappings, and [URL Rewrite] contains URL handling rules. These names are functional, not decorative headings; content in the wrong section may not be parsed as expected. When reviewing an unfamiliar file, find these sections first and then inspect their settings line by line, rather than searching for a domain and pasting in a snippet.

Server details and routing rules serve different purposes. A server entry specifies where to connect, which protocol to use, and the authentication parameters; a rule specifies the policy for a request. DOMAIN-SUFFIX,example.com,PROXY alone does not create a working server, and successfully importing a subscription does not mean a particular rule file is enabled. This guide assumes you already have your own subscription or server details. Example domains and addresses illustrate match scope only; they are not connection resources.

Save a copy before making one change at a time

In Config, check which file is selected, note its name, and keep the original content in a separate copy. Before editing, check whether the file comes from a remote URL and whether updates download the entire file again. A remote configuration and a server subscription may both appear as links, yet update different items; identify them by their import method and contents. Don’t treat a remote file as permanent local notes until you understand how it updates: a later update may overwrite rules you added manually.

Keep existing section names and add content only to the intended section. Start with one narrowly scoped DOMAIN rule, then save, enable the configuration, and establish a new test connection. Expand to DOMAIN-SUFFIX only after confirming the result. A successful save means the text was written; it doesn’t confirm that every keyword, parameter, or policy is valid. Address any parsing warnings first instead of adding more rules to obscure the original error.

[General]
dns-server = system

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

[Host]
lab.example.com = 192.168.10.20

This snippet shows a configuration skeleton, not a complete connection setup. It uses system DNS, sends one exact domain to DIRECT, sends example.com and its subdomains to PROXY, sends all other requests to DIRECT, and assigns a fixed address to a lab domain. Actual access still depends on the selected server, network reachability, whether the address belongs to your environment, and whether the relevant service is running. Don’t use the example address mapping in production as-is.

Separate valid syntax from the right behavior

A line can be syntactically valid but still conflict with your networking goals. For example, FINAL,DIRECT and FINAL,PROXY are both valid fallback policies, but they send unmatched requests in entirely different directions. Reviewing a configuration means more than checking for errors: ask which requests reach the line, whether the target policy is available, and whether the connection can recover from failure. Record the expected input and result for each change, and keep a before-and-after diff.

If a file contains duplicate sections or conflicting settings, organize it into a clear structure before troubleshooting further. Don’t assume without verification that “the last duplicate always takes effect.” Keep rules for the same purpose in readable locations, avoid redundant mappings, and preserve enough notes to explain why a setting exists. This is usually easier to maintain than piling on more conditions.

DOMAIN: match one exact domain

The match value for DOMAIN is a domain name, not a full URL. DOMAIN,api.example.com,PROXY applies to api.example.com; a matching string in a page path won’t make it match another site, and it doesn’t automatically cover www.example.com. Don’t include https://, a path, query parameters, or a trailing port. If you need to distinguish paths under the same domain, domain rules aren’t the right tool. First confirm that the app exposes the relevant request information.

An exact-domain rule is useful for a narrowly scoped exception. For example, if the main site and other subdomains use the proxy path but an internal API should connect directly, put the API’s DOMAIN rule before the broader suffix rule. This makes the exception-first intent clear in the file. Exact-domain rules don’t get automatic priority; this one is checked first because it appears first. If you swap the lines, the later exception may never run.

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

DOMAIN-SUFFIX: domain suffixes and subdomains

DOMAIN-SUFFIX,example.com,PROXY covers example.com itself and subdomains such as api.example.com and img.cdn.example.com. It matches the domain boundary, not an arbitrary string: notexample.com is not a subdomain of example.com. Usually, enter the base domain directly; there’s no need to write *.example.com. Adding wildcard syntax to a suffix value can make it more ambiguous.

Suffix conditions are useful for managing one domain tree, but a single service may use several unrelated domain trees. A page may also contact separate domains for sign-in, static assets, and APIs. So even if the main site matches a rule, images or sign-in may take a different route. Inspect actual requests and identify the purpose of each necessary domain instead of broadening the rule to a whole public suffix. This is especially important for shared hosting domains, where an overly broad match can affect unrelated services.

DOMAIN-KEYWORD: a broader contains match

DOMAIN-KEYWORD checks whether a domain contains a specified keyword. DOMAIN-KEYWORD,example,PROXY has a wider scope than the example.com suffix and may also match other domains containing example. It doesn’t determine whether those domains belong to the same organization, and it doesn’t search only the registrable domain. Use a keyword condition only when you explicitly need a broad contains match and are prepared for incidental matches.

If you only need api.example.com and download.example.com, prefer exact-domain or suffix conditions. Don’t use a short keyword just to save a line. A single letter or common abbreviation is hard to audit and can unexpectedly include new sites without any configuration changes. Keep keyword rules easy to find and test them against examples that should and should not match.

Domain visibility and input cleanup

Domain conditions require the processing flow to associate a request with a domain. If an app connects directly to an IP, or the request doesn’t retain a name that can be matched, a domain rule may not work as intended. Check the target address and logs instead of putting an IP in DOMAIN. For internationalized domain names, use the form that matches the name actually recognized in processing. When copying rules, watch for full-width commas, invisible spaces, and URL-encoded characters.

When organizing rules in bulk, remove duplicates first, then check whether an earlier broad condition shadows a later, more specific one. Keeping duplicate domains with different policies doesn’t enable automatic selection; position still determines the result. For basic examples of rule scope, see Getting Started with DOMAIN, GEOIP, and FINAL. Then review both the rule scope and its position in the complete configuration.

PROXY, DIRECT, and REJECT explained

PROXY sends a request through the proxy path, but the connection still depends on the selected server and a valid server reference in the configuration. DIRECT accesses the target directly; it doesn’t mean “try the proxy, then fall back if it fails.” REJECT blocks matching requests; it isn’t a performance switch. These policies serve different purposes, so don’t rotate them randomly when a request fails. Decide which path the target should use, then check name resolution, connectivity, and the service response along that path.

If a configuration uses custom policy names, confirm that each one exists and that references match definitions exactly. Don’t assume a server remark name is a usable policy, or copy references from another file without their corresponding definitions. This guide uses built-in policy directions to explain the basics and doesn’t include complete custom policy group definitions. If a name isn’t recognized, fix the reference instead of adding more rules with the same name.

Top to bottom, not automatic “most specific first”

Read Rule from top to bottom. When a request satisfies a condition, that rule’s policy applies; later rules are not checked to assign a different policy to the same match. Rule types have no universal ranking that overrides their order in the file. For example, if a suffix rule for example.com appears before an exact-domain exception for api.example.com, the earlier rule will usually match first and shadow the exception. This is one of the most common hidden mistakes in long rule lists.

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

For api.example.com, the first exact-domain condition matches and selects DIRECT, so the suffix rule isn’t checked. For www.example.com, the first condition doesn’t match, but the second does, selecting PROXY. Another domain containing example but not under that suffix may match the keyword condition. IP rules get a chance only if an earlier condition hasn’t already matched; they are not an independent layer that forcibly overrides other rules.

FINAL belongs at the end

FINAL has no separate match value. Common forms are FINAL,PROXY and FINAL,DIRECT. It handles requests that didn’t match earlier rules, so put it last. If FINAL is in the middle, later rules won’t get their normal chance to match. When adding a rule, appending it to the end may accidentally place it after an existing FINAL. Check the bottom of the list after every edit instead of only confirming that the new line exists.

Choose the fallback direction for your network needs and make sure it matches your test expectations. FINAL is not a backup server that takes over when a connection fails, and it won’t run after an earlier PROXY connection fails. Once a rule selects a policy, any connection failure is a separate issue along that policy path. Mistaking FINAL for failure recovery can lead to repeated edits to irrelevant end-of-list rules while the actual problem remains untouched.

Organize rule order into reviewable layers

A common layout puts explicit service exceptions first, followed by appropriately scoped domain groups, then local address and geographic conditions, and finally FINAL. This makes the list easier to review; it isn’t a fixed order for every environment. If your goal requires an IP range to take precedence over all domain conditions, put it earlier and account for the need for address information and the effect on later domain checks.

To review rule order, list one input that should match each important rule and another that should continue down the list. Testing only positive matches can miss shadowing caused by broad conditions. Use the same approach when removing old rules: an exception that seems inactive for a long time may only matter on a particular network, address family, or sign-in flow. Clear notes about each rule’s purpose are a more reliable measure of configuration quality than the number of rules.

What USER-AGENT matches

USER-AGENT uses identifiable User-Agent information in a request; it is not a general index of app names on the device. It can’t identify every connection from an app icon, and it shouldn’t be described as app-based routing for all traffic. Different apps may use the same system networking component, and one app may send different identifiers—or none of the information required for this match—in different requests. Confirm which fields are actually present before using this condition.

[Rule]
USER-AGENT,ExampleApp*,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT

This example uses an identifier beginning with ExampleApp to show the condition’s format; it doesn’t mean a real app will necessarily match. The condition can only be evaluated when the processing flow can access the relevant request information. For connections that don’t expose that field, analyze observable details such as the domain or destination address. Don’t try to compensate for missing input by adding increasingly broad wildcards.

HTTPS does not automatically expose request paths and headers

The domain or address information available to ordinary routing rules is different from the ability to read the full contents of an encrypted request. Being able to match a domain with DOMAIN-SUFFIX doesn’t mean you can read HTTPS paths, query parameters, or User-Agent. Design rules around fields that are actually visible. Don’t change certificate trust or broaden processing just to test a request-header rule that may not apply; understand the security impact and requirements separately.

If you simply need to route a site in a particular direction, a domain rule is often more direct. Consider USER-AGENT and similar conditions only when the task genuinely depends on request-level details and you’ve confirmed that the processing flow can identify them. For testing, use a request you control and compare its input identifier with the expected policy; don’t infer that a field was read just because one visit succeeded.

URL Rewrite: changes the request URL, not the proxy policy

URL Rewrite handles URLs that match an expression. Its role differs from Rule: Rule selects a policy, while a rewrite changes the matching request URL or triggers the corresponding redirect behavior. The example below targets a cleartext HTTP URL and redirects requests for example.com to the corresponding HTTPS URL. The dots in the expression are escaped, the leading anchor restricts the match to the start, and a capture group preserves the original path.

[URL Rewrite]
^http://example\.com/(.*)$ https://example.com/$1 302

Here, 302 indicates a temporary redirect. Whether the client makes the next request as expected also depends on the request method and app behavior. Don’t assume a redirect always preserves every method and request body, or that a changed browser address bar means every background API followed the same rule. Start with a simple, observable request and confirm the response and redirect chain before expanding the scope.

Limit regex scope and prevent loops

When writing an expression, define the scheme, domain boundaries, and path scope before adding capture groups. If the dots in a domain aren’t escaped, a regex may treat them as any character and match unintended addresses. A broad keyword alone may also affect query parameters or other sites. If the replacement still matches the original expression, it can cause repeated redirects. Check the entire chain: original URL → new URL → whether the new URL matches again.

Don’t put account credentials, subscription tokens, or service keys in rewrite snippets that may be shared. Remove sensitive parameters from requests used for examples or notes while keeping enough structure to reproduce the rule’s behavior. Manage any sensitive information in a real configuration privately; don’t post it as a troubleshooting attachment. Before copying someone else’s expression, read both the target domain and replacement URL so the destination isn’t missed.

Review URL Rewrite as a separate checklist item rather than checking Rule alone. Even when domain routing works as expected, a bad rewrite can send a request down another path. Conversely, having a rewrite rule doesn’t mean it handles every connection; applicability depends on the request protocol, visible information, and active configuration.