Shadowrocket
Rules & Configuration Reference

01 · Configuration Structure and Editing Safely

Open Config and check which configuration is currently selected; do not rely only on the most recently imported file in the list. Open that file in the editor and confirm you can see its sections and existing rules before making changes. After saving, return to the list and make sure the selected indicator still points to that file. Editing a different copy will not affect the active connection, even if the text is correct. Config manages traffic-routing configurations, while the server list in Home has a separate purpose; they are not the same data.

What Each Configuration Section Does

Shadowrocket text configurations are organized into sections marked by bracketed names on their own lines. The following lines belong to that section until the next section begins. General contains basic behavior settings; Rule contains conditions evaluated in order; Host maps specified hostnames to addresses; and URL Rewrite contains rules for changing or redirecting request URLs. Do not put a line in Host just because it looks like a domain. First determine whether it controls routing, specifies a resolution result, or changes the request URL.

This minimal snippet illustrates the configuration structure. It shows basic parameters and Rule only; it does not define a server or replace your complete configuration. Check in Home whether PROXY has an available destination. The example domains are for illustration; when testing, use a target you are authorized to access and whose expected behavior you understand. Do not repeatedly open an example address to determine whether a server is working.

[General]
dns-server = system

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

Keep the Original; Make a Working Copy

Before editing, export or copy the currently working configuration and give the copy a name that makes its purpose clear. Keep a backup that can restore the original General, Rule, and custom Host content, and separately confirm whether the server list is saved. Exports may contain subscription URLs or authentication details, so do not post the entire file in a public forum. When asking for help, share only the relevant rules, redact target details, and describe the actual error.

Whether a field is accepted depends on the save result, the editor's in-app guidance, and request logs. Keep English half-width commas, equals signs, and section names. Chinese punctuation, invisible spaces, or typographic quotation marks copied from a formatted document can prevent a line from parsing as expected. If an error appears immediately after saving, undo the last change and restore the file line by line. Do not edit several sections at once and hope for the best.

Treat Subscription Updates and Configuration Updates Separately

An existing subscription usually updates server entries; a remote configuration may update routing rules or basic parameters. They are not interchangeable. Updating servers does not necessarily change Rule, while fetching a remote configuration may require you to review local edits. Before proceeding, check where the update option appears, what kind of remote content it updates, and where it will be saved. Get your subscription URL from your own provider. This page does not provide URLs or assess providers.

If the in-app editor differs from the examples here, follow the current field guidance and preserve settings that already work. Check the App Store listing for system requirements. App updates are installed through the App Store; replacing your entire configuration is not an app update. Configurations control network behavior, while the store handles app acquisition and updates. Check these maintenance paths separately.

02 · Global Routing and Match Order

Before checking rules, open Global Routing in Home and confirm the current mode. Config applies the configuration, Proxy routes through the proxy, and Direct uses a direct connection. To test Rule-based routing, select Config, make a new request, and inspect its log. Editing rules in Config while leaving Global Routing set to Proxy, then seeing all requests use the proxy, does not prove that Rule syntax is wrong. The selected routing mode determines whether those rules are used.

First match wins; the longest rule does not

Read Rule from top to bottom. The first matching rule determines the policy for that request. A more specific rule farther down will not override an earlier match. Placing an exact domain rule before a broad suffix rule is a manually set priority; Shadowrocket does not sort rules for you. When editing, review the whole section rather than checking only that the rule you want appears somewhere in the file.

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

In this snippet, api.example.com matches the first line. Other subdomains of example.com continue to the second line. If you swap the first two lines, api.example.com matches the suffix condition first, leaving the exact-domain rule no chance to affect the decision. To troubleshoot, note the target hostname, the first matching condition, and the resulting policy, then work upward through rules with broader coverage.

FINAL Handles Requests That Have Not Matched

FINAL does not require a domain or address parameter. It handles requests that have not matched an earlier rule, so it belongs at the end of Rule. It is not an instruction to switch automatically after a failure, and it does not test whether a proxy can connect. FINAL,PROXY sends remaining requests to PROXY; if the server selected for PROXY is unavailable, requests may still fail. FINAL cannot automatically repair a broken route.

Do not put FINAL in the middle of Rule and then add exception rules after it. The catch-all will take the remaining requests first, so later entries cannot provide the exceptions you intended, even if they save successfully. Avoid using multiple conflicting FINAL rules as a fallback scheme. Decide where unmatched requests should go, then express that choice with one clear rule at the end.

The Address in a Log May Differ from the Original Hostname

A page visit can create multiple connections for the main page, images, API calls, and other resources. Seeing one IP request use PROXY does not mean the main domain's rule failed. In Data, find the request or connection entry that corresponds to the test time and target hostname, then inspect its match details. If the log shows only a destination IP, check whether the request included hostname information and whether it reused an existing connection.

Connections established before you saved a rule may continue using their previous route. To verify a change, save the configuration, confirm it is selected, establish a new connection, and trigger the target request. If needed, close and reopen the relevant app. Repeatedly refreshing the same page is not enough: caching may make the page appear updated without creating the new connection you need to inspect. Base your conclusion on an identifiable new request.

03 · Writing DOMAIN Rules

Copy the actual hostname from the request log, then choose a matching method. A domain rule's condition should not contain a full URL, https://, a path, query parameters, or a port. For example, for https://api.example.com/status, the DOMAIN condition should be api.example.com, not the entire URL. Path-based matching is a separate requirement; appending a path to DOMAIN will not achieve it.

DOMAIN: Match One Specific Hostname

Use DOMAIN to handle one specific hostname. DOMAIN,example.com,DIRECT does not automatically include api.example.com just because the names look similar, nor does it match unrelated domains containing the word example. For an exception involving a login API, update endpoint, or internal service, first confirm its actual hostname, then use an exact match. If a service uses multiple hostnames, record each one instead of assuming a single address covers every request.

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

This snippet lists two specific hostnames, then sets a default action for the remaining suffix. The exact rule for login.example.com and the suffix rule both point to PROXY. That may look redundant, but can help document an endpoint that needs separate attention. If there is no maintenance reason to keep it, removing a duplicate with the same policy makes the configuration easier to read. Before simplifying, check for other exceptions that rely on rule order.

DOMAIN-SUFFIX: Match a Domain and Its Subdomains

DOMAIN-SUFFIX,example.com,PROXY matches example.com and its subdomains. Matching follows domain boundaries, not arbitrary text: api.example.com is included, but notexample.com is not. Usually, enter example.com as the condition; do not add a wildcard or treat it as a regular expression. For a narrower scope, use api.example.com as the suffix and decide explicitly whether its subdomains should also match.

Suffix rules can cover multiple endpoints under a service domain, but a page's resources may use other domains. If login works but images fail, check the actual hostname used by the image requests instead of repeatedly broadening the main domain rule. Combining every observed domain into one overly broad keyword can affect unrelated requests. First collect the failed entries, then decide whether to add an exact rule or another specific suffix.

DOMAIN-KEYWORD: The Match Can Be Broader Than Expected

DOMAIN-KEYWORD matches text in a hostname; the keyword does not have to occupy a complete domain label. DOMAIN-KEYWORD,example,PROXY may match multiple unrelated domains containing that text. Use it only when you need that broad scope; it is not a substitute for every DOMAIN-SUFFIX rule. When troubleshooting, narrow broad keywords to hostnames you actually observed to reduce interference from unintended matches.

Do not add Chinese comments, trailing commas, or sentence-ending punctuation copied from a browser to rule conditions. Put the policy in the required final position, and keep explanatory notes on a separate line so they are not mistaken for fields. If the editor lets you enter the type, condition, and policy separately, filling in each field is often easier to validate than pasting a long line. After saving, check the text view as well.

Test Match Scope and Policy Separately

When testing a domain rule, keep the policy unchanged at first and check only whether the target matches. Once the condition is correct, change PROXY or DIRECT if needed. This separates “no match” from “matched, but the route failed.” Changing the condition, server, and DNS at the same time makes it impossible to identify what caused the result and leaves no clear basis for rolling back.

04 · IP, GEOIP, and USER-AGENT

Domain conditions cannot cover every request. Some apps connect directly to IP addresses, and some connection logs do not provide a hostname that rules can use. In those cases, consider IP-CIDR, IP-CIDR6, or GEOIP. First confirm the destination address and address family, then choose a condition. Do not assume that text in a browser address bar proves the underlying connection includes a hostname, or that an address rule permanently identifies an entire website.

IP-CIDR: Addresses and Prefix Lengths

An IP-CIDR condition consists of a network address and a prefix length after the slash. 192.168.0.0/16 represents a range of addresses, while 192.168.1.20/32 covers a single IPv4 address. A larger prefix number usually means a smaller range. The rule applies to the connection's destination address, not your iPhone's local address. To connect directly to an internal device, enter the destination range containing that device rather than copying your own device's address at random.

[Rule]
IP-CIDR,192.168.1.20/32,DIRECT
IP-CIDR,192.168.0.0/16,DIRECT
IP-CIDR6,fd00::/8,DIRECT
GEOIP,CN,DIRECT
FINAL,PROXY

The example lists one internal address first, then a larger private range, making it easier to add exceptions later. Your network may use different internal subnets; follow its settings and the information provided by your administrator. Sending a private address through DIRECT selects a direct route but does not grant access. Your device still needs to be on a network that can reach that subnet, and the destination service must be listening on the relevant port and allow the connection.

IP-CIDR6 and IPv6 Troubleshooting

IP-CIDR6 matches IPv6 address ranges. The fd00::/8 example illustrates one local address range; it does not mean all IPv6 addresses should use a direct connection. If a hostname returns both IPv4 and IPv6 addresses, an IPv4-only rule may not cover the IPv6 connection actually used. Check the log to see which address family the connection selected, then decide whether to add a rule. Disabling an entire address family is not a routine fix.

Some IP-based rules support the no-resolve parameter to avoid resolving a domain solely to evaluate that rule. It limits resolution triggered by the matching process; it does not disable every DNS operation required by a request. If a request has only a hostname and no destination IP available, the rule may not match as expected. Before using this parameter, confirm that the current editor supports it, then test the behavior with and without it.

IP-CIDR,192.168.0.0/16,DIRECT,no-resolve

GEOIP Uses an Address Database, Not Language

GEOIP,CN,DIRECT selects DIRECT based on the geographic classification of the destination IP. It does not classify requests by page language, domain suffix, or user location. A domain may use distributed addresses, and database classifications can differ, so this does not identify where a service operates or guarantee connection speed. For exceptions involving a few known services, verified DOMAIN rules placed earlier in the list are usually easier to maintain than broad GEOIP conditions.

Order still matters when domain rules and GEOIP are both present. If an earlier domain condition matches, a later address classification will not automatically select a different policy. If the log shows a GEOIP match, check whether the earlier domain conditions cover the actual hostname and whether the current connection retained hostname information. Updating the address database alone may not fix the issue if you have not checked what request is being matched.

USER-AGENT Does Not Identify Apps

USER-AGENT matches an available request-header field. For example, USER-AGENT,ExampleClient*,PROXY shows a condition with a wildcard pattern. This does not route traffic by app name, and the field is not visible for every connection. Headers in many encrypted requests cannot be inspected directly; do not enable decryption indiscriminately for this type of rule. If the log does not expose a matchable field, look for a specific domain condition and keep FINAL to handle remaining requests.

05 · PROXY, DIRECT, REJECT, and Protocol Parameters

The first part of a rule answers “which requests?” The final policy answers “how should they be handled?” PROXY, DIRECT, and REJECT are common policy keywords; use the correct spelling and capitalization. Do not confuse policy names with server protocols: Shadowsocks, VMess, and Hysteria2 describe protocols used for server connections; they are not general actions that replace PROXY in Rule. Confirm the condition matches first, then follow the policy to check the actual connection destination.

The Difference Between PROXY and DIRECT

PROXY generally sends a request through the currently selected proxy. The actual destination also depends on the selection in Home and whether the configuration contains a policy group. DIRECT uses a direct route, but does not bypass the network environment, system permissions, or resolution process. A successful direct connection does not prove the proxy settings are correct, and a working proxy does not mean every internal address should use it. Choose based on where the service is hosted and what you need to do.

If the current configuration includes named policy groups, a rule may reference a group name at the end. Check that the group exists, its name matches exactly, and it has an available member. Pasting a group name from another file does not create that group automatically. The snippets here use basic policies for clarity. If your full configuration uses groups, preserve its structure when adding exceptions.

REJECT Actively Blocks a Request

REJECT explicitly blocks a matching request; it does not mean “try another server if the test fails.” Use it only when you are sure the target should be blocked. If you mistakenly apply REJECT to a domain needed for login, the app may appear to hang, ignore a button, or fail to load some resources without showing a clear rejection message. To troubleshoot, find the rejected entry, check whether the condition is too broad, then remove it or narrow its scope.

[Rule]
DOMAIN,blocked.example.com,REJECT
DOMAIN,internal.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,PROXY

These rules demonstrate actions for three different hostname scopes; they are not a recommendation to add real login domains to a blocklist. blocked.example.com is rejected, internal.example.com uses a direct connection, and other example.com subdomains go through the proxy. Changing the order can change the result. Keep a brief note on why each exception exists; that is more useful over time than accumulating unexplained rejection rules.

Check Parameters for Protocols You Already Use

After importing a server, confirm its protocol type first, then check the address, port, and authentication fields. The encryption method and password for Shadowsocks, identity fields for VMess and VLESS, and password and TLS settings for Trojan all mean different things. Do not swap values just because fields appear in similar positions. Complete parameters from your own provider take precedence over scattered online examples. Ask the provider for missing details instead of guessing.

For TLS failures, check the server name, certificate requirements, and system time. Do not treat skipping certificate verification as a default troubleshooting step. Hysteria2 also requires checking whether UDP is actually reachable; a response in one test does not mean every transport is working. Verify each protocol on its own. A successful result with one server does not prove another server is configured correctly.

If a PROXY request fails but DIRECT works, note the selected server, protocol, and failure stage, then check the corresponding entry in Home. If all destinations fail through the same server, investigate the server and network before adding rules for each website. If only one destination fails, check for additional domains, a nonstandard port, or access restrictions on the service.

06 · General, DNS, and Host Mappings

DNS resolves hostnames to addresses that can be reached; Rule determines how requests are handled. They are related, but not the same feature. If a page will not open, first check whether an address was resolved, then where the connection went, and finally which policy it used. Changing DNS will not fix a wrong password, and changing PROXY will not guarantee that a nonexistent domain resolves. Recording each stage of the failure helps avoid repeatedly changing unrelated fields.

dns-server and System Resolution

In General, dns-server = system means to use the resolution settings provided by the system. It is a basic example to illustrate the field, not a universal recommendation for every network. System resolution can change with Wi-Fi, cellular service, and network management settings. Record the current network and DNS settings before changing resolution options in the configuration. That gives you a baseline to compare when results differ after switching networks.

[General]
dns-server = system

[Host]
lab.example.com = 192.168.1.20

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

This snippet maps lab.example.com to an internal device and routes that domain directly. Use it only in a test environment where you control both the hostname and the device. Host maps addresses; DOMAIN selects a policy. Without the latter, the request may still follow another Rule. Conversely, setting DIRECT without resolving the hostname correctly may not send the request to the intended device.

Host Does Not Change Certificate or Service Identity

After mapping a hostname to an IP, the original hostname is generally still used for the request. An HTTPS service needs a certificate that matches that name, and the server may select a site based on the hostname. The fact that an IP address opens a page does not mean any Host mapping will work. Reachability, certificate matching, and server configuration are separate requirements; all must be satisfied.

Host is not suitable for permanently pinning a public service to an address that changes. If the service moves, an old mapping may keep sending requests to an invalid destination, causing the service to work on other devices but fail on yours. Check for leftover mappings during troubleshooting; temporarily remove one, establish a new connection, and compare. For internal devices, also check whether the device's address changed after the network reassigned it.

Distinguish DNS Caching from Connection Reuse

After changing a mapping, an old resolution record or connection may still affect what you see. Save the file, confirm the configuration is selected, reconnect, and make a new request. If necessary, clear the relevant cache using an option provided by the app. Do not assume that Host failed just because the page still shows old content: page caching, server caching, and connection reuse can all preserve an earlier result. Use the destination address in a new log entry as your primary evidence.

If the log does not show an address for a hostname, first check whether that name resolves on the current network. Then look for typos, reliance on internal resolution, or resolution handled by the app itself. Some apps make requests in ways that limit what standard hostname logging can show; this does not prove that all DNS bypasses the configuration. Testing one reproducible target at a time makes the boundaries easier to identify than testing several pages at once.

Review General Parameters One at a Time

General may also contain parameters for system traffic handling, exceptions, or address families. Do not paste them all in as a set of “optimization” switches. Use the existing file as your baseline, look up each field, and check how it relates to Rule. If a parameter changes which traffic is captured, adding a Rule alone may not override its effects. Change one setting at a time, record its previous value and the behavior observed, then move on after verification.

With encrypted DNS or other resolution methods, consider how the resolution request reaches its destination and whether that creates a connection dependency. If the proxy server address also needs resolution, but the resolver can only be reached through that proxy, the setup may wait on itself during startup. In that case, restore a known working baseline and establish resolution and connectivity in order. Adding more resolver addresses will not fix the underlying dependency.

07 · What URL Rewrite Does and Its Limits

First identify whether you need to change the route or the request URL. Sending example.com through PROXY is a Rule task; redirecting an old entry point to another URL may call for URL Rewrite. These are separate configuration sections, and placing URL Rewrite before Rule does not give it higher routing priority. Each handles a different problem. When testing, check the route result and the URL change separately.

Start with an HTTP Endpoint You Control

URL Rewrite generally consists of a matching expression, a target URL, and an action. The HTTP-to-HTTPS redirect below illustrates the structure. Before testing, confirm you control the relevant destination and check which actions and syntax the current editor supports. The backslashes in the expression treat periods as literal dots; the parentheses capture the path; and $1 in the target refers to the first capture group.

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

This line matches http://example.com/ from the start of the URL, carries the remaining part into the target, and uses 302 for a temporary redirect. It does not make the destination server support HTTPS or fix its certificate. If the target URL is unreachable, the redirect only sends the request to another failure. First verify the target URL directly, then test whether the source URL redirects to it.

Keep Regular Expressions Within Clear Boundaries

In a regular expression, a period matches other characters by default; leaving it unescaped can broaden the match. A start anchor prevents a match at an arbitrary position. A short keyword alone rarely makes it clear which URLs you intend to affect. Start with the full scheme, a specific hostname, and only the necessary path. After verifying the result, consider expanding the match. Do not begin with a broad condition and try to exclude unintended matches one by one.

URLs may contain query parameters, encoded characters, and different path formats. The capture group in the example preserves content after the slash, but that does not mean every complex URL can be safely rebuilt by simple concatenation. Changing any part of a login callback, signed request, or API that depends on exact parameter ordering can break validation. For these targets, first confirm the protocol requirements; do not apply an expression that works on a regular page to an authentication flow.

Avoid Redirect Loops and Changes to Request Semantics

After adding a rule, check whether the target URL also matches the same rule or another rule that sends it back to the original URL. If a page keeps redirecting, the URL keeps changing, or the number of requests continues to grow, disable the new rule first and preserve the logs. Bidirectional rewrites between multiple endpoints can easily create a loop. Document the source condition, target URL, and expected final destination rather than judging correctness from the rule text alone.

Redirects can also affect how request methods, request bodies, or authentication headers are handled, depending on the action and the app making the request. A successful GET in a browser does not prove that an API POST will behave the same way. For form submissions, payments, or authentication requests, preserve the original request unless you understand the service protocol. Do not rewrite these requests in bulk with a general-purpose rule.

HTTPS Visibility and Certificate Boundaries

Ordinary encrypted connections do not expose the full URL path to standard routing rules. Features that read HTTPS content require additional decryption and trust conditions; writing a URL Rewrite rule does not satisfy those requirements. The example on this page starts with a plain HTTP URL and does not require adding a trusted certificate to verify the rule. For domain-based routing alone, use Rule.

Do not treat certificate trust steps as a universal fix for failed rewrites. First check whether the test request is visible, whether the expression matches, whether the action is supported, and whether the target is reachable. Then decide whether the feature fits your needs. Apps may also perform their own certificate checks or use fixed access logic. If a request fails, stop expanding the rewrite scope instead of repeatedly weakening verification.

After verification, keep only the necessary rules and record the purpose and test endpoint for each. A website may already redirect requests on its own; adding a duplicate local rewrite only adds another layer to maintain. If the result is unchanged after removing a rule, check whether the server or browser handled the redirect. Confirm which component owns the behavior before keeping a rule; this reduces hidden dependencies when moving configurations later.

08 · Configuration Verification, On Demand, and Maintenance

Before testing, write down a specific, verifiable goal, such as “New requests to api.example.com should match DOMAIN and use DIRECT.” Then note the current network, Global Routing mode, selected configuration, and server before making a request. Success is not a switch changing color; the request must match as expected and the destination must return a reasonable result. A correct routing decision followed by a server failure needs a different investigation from a rule that never matched.

Troubleshoot by Failure Stage; Do Not Stack Changes

First check that the system network works. Next, confirm the connection switch and VPN configuration authorization. Then check the server, and finally inspect the rules. If authorization to add a VPN configuration was denied or the configuration was removed, return to the initial connection steps instead of editing Rule first. For details on the system prompt, see VPN Configuration and System Permission Prompts.

Connectivity Test can help you check for a server response, but it does not replace a real request to the service you want to use. If the test fails, check the address, port, protocol, and current network. If it responds but a webpage fails, check DNS, TLS, rules, and the specific destination. Different tests may verify different parts of the connection, so do not treat a single result as proof that the entire route works. For more, see How to Troubleshoot Connection Timeouts.

On Demand Controls When to Connect, Not How Rules Work

In Settings, check the actual On Demand conditions and distinguish “when to connect” from “how to route traffic after connecting.” On Demand triggers a connection under the conditions you set; it cannot fix a wrong password or reorder Rule. While debugging rules, use a manual connection first to establish a stable baseline. Once routing works, enable the On Demand conditions you need. This reduces interference from automatic reconnections during testing.

If the connection returns after you disconnect manually, check On Demand and system triggers before assuming the configuration was not saved. To investigate background battery use, compare similar networks, usage periods, and servers. One change in battery level is not enough to identify a problematic setting. For more on the trade-offs between always-on and on-demand use, see On Demand and Background Battery Use.

Keep a Test Record You Can Roll Back

For each change, record four things: the original rule, the edited rule, the test target, and the actual match. If the result is unexpected, immediately undo that change before deciding what to try next. Adding more exceptions while the problem persists makes it hard to tell which line eventually restored the connection. A few well-documented rules are easier to maintain than many overlapping conditions.

When sharing troubleshooting details, redact subscription links, passwords, identity fields, keys, and internal addresses that should remain private. Usually, the relevant Rule snippet, a redacted target name, the matched policy, and the failure stage are enough; you do not need to share the entire configuration. Check screenshots for authentication details before sharing. This page does not ask you to upload files or provide a complete subscription. Share only what is necessary to explain the issue.

Routine Checks After Updates

After updating the app through the App Store, confirm that the intended configuration is still selected and check the key rules you rely on. After updating a subscription, confirm the selected server still works. After updating a remote configuration, confirm your local exceptions remain in the right positions. When changing devices or reinstalling, restore the app and configuration separately. A purchase record does not necessarily restore all custom data. For details, see Restore a Previous Purchase.

Use this page's contents to return to a configuration section. To start again with adding a server and follow the full process, go to the Shadowrocket setup guide. For separate questions about purchases, import failures, or system permissions, browse FAQ by topic. The goal is to keep every rule's scope clear, make every change reversible, and tie each conclusion to a reproducible new request—not to keep making the configuration longer.