Official Manual / CONFIG
Shadowrocket Rules Guide
Use this page to review config sections, rule types, and match results. If you haven’t imported your own server details or completed your first connection, start with the Getting Started Guide, then return here to adjust routing. For installation, App Store account, or device migration questions, see Get the App and FAQs.
Get Shadowrocket for iPhone and iPad from the App Store. The US price is a one-time $2.99 purchase; check the App Store listing for system requirements. The Mac (Apple silicon and Intel), Windows, Android, and Linux versions are free, with installers available from /dl/shadowrocket/ on this site. The one-time app purchase is not a service subscription. This guide assumes you already have your own server or subscription. This site does not provide, sell, or recommend connection services.
Config File Structure: General, Rule, Host, and URL Rewrite
Keep three layers distinct: the active config determines which file the client uses, each section determines what its lines do, and the order in [Rule] determines which rule is checked first. A file listed in Config is available to select; that alone does not mean it is active. Open Home and make sure Global Routing is set to Config, then check the active file in Config. Keep a copy you can restore before making changes, especially when working with a remotely managed config rather than a local working copy.
General: Establish a Baseline for DNS Resolution
[General]
bypass-system = true
dns-server = system
[Rule]
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT
Use key-value syntax in [General]. Here, dns-server = system establishes a test baseline using system DNS, without changing the resolver and routing rules at the same time. bypass-system controls system traffic bypass behavior; it is not a substitute for a DIRECT rule for a specific domain. Nor does a single routing match prove that all system traffic passes through the client. When comparing custom DNS or DoH, keep the active config, test target, and network unchanged. See DNS Settings Explained.
Rule: Put the Condition, Target, and Action on One Line
The three fields in DOMAIN-SUFFIX,example.com,PROXY are the rule type, match target, and policy. FINAL,DIRECT has no target field. Don’t paste a URL, protocol prefix, or explanatory text into a domain field. When editing by hand, use standard commas, brackets, and equals signs; rich-text copying can introduce full-width punctuation. The example does not include server details. To test PROXY, first select one of your own working servers on Home. The example domain illustrates rule scope; it is not guaranteed to be reachable in your environment.
Host and URL Rewrite: Address Mapping and Request Rewriting Have Different Limits
[Host]
dev.example.com = 192.0.2.10
[URL Rewrite]
^http://old\.example\.com/guide$ http://new.example.com/guide 302
The [Host] example maps a specified name to a documentation address. Before adapting it for your environment, confirm that the address is reachable, the service is available there, and the original hostname matches the server’s certificate and virtual host configuration. Address mapping does not change the request hostname or set a connection to DIRECT. If adding the mapping causes a failure, remove it and test again; there’s no need to change DNS and policy at the same time.
The [URL Rewrite] example matches only the specified HTTP path and redirects it to another address with 302. It does not route every connection to the old domain through a proxy. The dot in the regular expression must be escaped, and the trailing $ limits the match to the end of the string, so requests with additional query parameters won’t match this example. Paths in encrypted connections are not automatically visible; don’t treat this as a promise to rewrite arbitrary HTTPS requests. Test on a service you control, and check both the original and redirected addresses.
If importing fails, check for a missing closing bracket in a section header, rules placed in the wrong section, or code fences accidentally copied from chat. If the config imports but behaves unexpectedly, check which file is active and what the rule actually matches. Separating syntax checks from behavior checks avoids repeatedly changing rule order when the file isn’t participating in routing at all.
Domain Rules: Exact, Suffix, and Keyword Matches
When you know the hostname used by a request, start with the domain rule that has the clearest scope. Choose rules based on the connection target, not the page title, app name, or button text on screen. For example, a browser page may connect to different hosts for the main document, images, APIs, and login callbacks. A rule applies only to connections that meet its conditions; it won’t automatically route every request from the same app under one policy.
| Rule | Match target | Typical scope |
|---|---|---|
DOMAIN | Exact hostname | A single API, gateway, or exception host |
DOMAIN-SUFFIX | A specified domain and its subdomains | A group of hosts that can share one policy |
DOMAIN-KEYWORD | A keyword in the hostname | A naming pattern with an assessed risk of false matches |
DOMAIN: Add an Exception for a Known Host
[Rule]
DOMAIN,auth.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT
The first rule matches only auth.example.com. If the service also uses api.auth.example.com, that host won’t become DIRECT automatically; it will be checked against the next rule. This pattern can exempt a login gateway from a broader proxy rule for the same domain, but the presence of auth in a hostname does not prove that all authentication requests are covered. Test the login page, form submission, and return to the app after login separately. If only one step fails, record the actual connection target for that step rather than changing the policy for the entire domain.
DOMAIN-SUFFIX: Match a Domain and Its Subdomains
DOMAIN-SUFFIX,example.com,PROXY matches example.com and img.example.com, but not notexample.com or example.com.example.net. To limit the scope to an API domain, use DOMAIN-SUFFIX,api.example.com,PROXY instead of routing the entire parent domain and patching it with numerous exceptions. Enter the domain itself in the field—not https://, a wildcard prefix, port, slash, or path. A domain rule identifies the connection’s hostname, not a page on that host.
When tracing an app issue back to a rule, first determine whether the target is the full hostname or the address seen before a redirect. The URL visible to the user may not be the hostname the connection ultimately uses. Alias resolution alone doesn’t prove that a rule will match another name in the resolution chain; use the target the client actually identifies and any available match details. If a request uses an IP address directly, or the connection provides no usable hostname to the client, domain rules may not apply. Check address rules instead of guessing with keywords.
DOMAIN-KEYWORD: Test False Positives Too
[Rule]
DOMAIN,media-admin.example.com,DIRECT
DOMAIN-KEYWORD,media,PROXY
FINAL,DIRECT
A keyword does not identify organizational boundaries. Besides possibly matching media.example.com, the example could also match multimedia.example.net. It does not search for media in a URL path or classify page content. If the target is under a known domain, a suffix rule is easier to review than a broad keyword. If a keyword is necessary, list expected matches, expected non-matches, and hosts that must be exempted first, then test against all three groups.
During troubleshooting, temporarily changing the policy for a keyword rule is often a poor first test: its broad scope can change several requests at once, making it hard to tell what restored the page. In a copy of the config, add a DOMAIN rule for a single target and confirm how its routing differs before expanding to a suffix or keyword. Remove the temporary rule and test again to make sure the final config doesn’t depend on that debugging exception.
Address and Request Rules: IP-CIDR, IP-CIDR6, GEOIP, and USER-AGENT
Domain rules classify by name; address rules classify by target address, and the results may differ. The same hostname can resolve to different addresses depending on the network or resolver, while one address may serve multiple hostnames. For distinguishing targets by service identity, domain rules are usually easier to maintain. For a known local subnet or fixed address, prefix rules are more direct. If a domain is routed unexpectedly, first check whether the connection used the original hostname, an IPv4 address, or an IPv6 address, then review rule order.
IP-CIDR and IP-CIDR6: Prefix Length Sets the Scope
[Rule]
IP-CIDR,192.168.50.0/24,DIRECT
IP-CIDR,192.168.0.0/16,PROXY
IP-CIDR6,2001:db8:20::/48,DIRECT
FINAL,DIRECT
/24 fixes the first 24 bits of an IPv4 address; /16 fixes the first 16. The example places the narrower subnet before the broader one to show how an exception works when ranges overlap; it is not a recommendation to proxy every other private subnet. If the second line comes first, 192.168.50.8 matches the broader range and won’t be reassigned when the more specific /24 is checked later. Use /32 to match one IPv4 address and /128 to match one IPv6 address.
IP-CIDR6 handles IPv6 prefixes. The example uses a documentation prefix, not a real service address to copy. On a dual-stack network, one test may use IPv4 and the next IPv6, so an IPv4 match alone doesn’t show that both paths use the same policy. For a LAN device, check its subnet in the device’s admin page or network settings, then test whether the address is reachable on the same network. DIRECT means the connection is not forwarded through a proxy; it does not add a route to the target subnet on your network.
If you need to check an IP condition for a named target, matching may involve DNS resolution. For an address rule confirmed to support this option, IP-CIDR,192.168.50.0/24,DIRECT,no-resolve avoids actively resolving a hostname for that rule. It is not a global DNS switch and does not prevent other parts of the client from resolving names. If entering an IP address matches but entering a hostname does not, don’t assume the rule is broken. First compare whether the target details available in each case are sufficient to evaluate the condition.
GEOIP: An IP Database Category Does Not Prove Service Ownership
[Rule]
DOMAIN,api.example.com,PROXY
GEOIP,CN,DIRECT
FINAL,PROXY
GEOIP,CN,DIRECT checks the target IP’s database classification. It does not classify by language, top-level domain, device location, or account storefront. Services using shared infrastructure or regional points of presence may resolve to different addresses on different networks, resulting in different policies. For a service you control that needs a consistent route, place a domain exception before the regional rule instead of relying on a region condition to define the service. When troubleshooting, record the target address used at the time; “this domain worked directly yesterday” is not enough.
USER-AGENT: Match Only When the Request Identifier Is Available
[Rule]
USER-AGENT,ExampleDesktop*,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT
USER-AGENT matches an available request identifier; it does not identify a process, system permission, or the app that opened the connection. Two requests may send the same identifier, and one app may send different identifiers for different features. Don’t expect this rule to match if the request has no such field, the field is unavailable, or the connection doesn’t use HTTP. The example is suitable only for testing a known identifier in an environment you control. To keep a service on a consistent policy, prefer a domain or address you can verify independently.
Policies and Routing: How PROXY, DIRECT, and REJECT Work
Global Routing and a policy in a rule operate at different levels. Global Routing selects how the client handles incoming connections; a rule’s policy is the result for a matching connection in Config mode. If you’re testing a config file but Global Routing on Home is set to Proxy or Direct, the resulting traffic cannot confirm that file’s rule order. Before troubleshooting, record the selected mode and compare results using the same repeatable request.
| Mode | How it handles connections | What it can help verify |
|---|---|---|
| Config | Routes according to the active config | Rule conditions, order, and default policy |
| Proxy | Uses the proxy route for applicable connections | Whether the selected server can reach the same target |
| Direct | Uses a direct route for applicable connections | Whether the current network can reach the same target directly |
PROXY: Check Rule Matching and Server Connectivity Separately
[Rule]
DOMAIN,blocked.example.com,REJECT
DOMAIN,local.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT
PROXY sends matching connections through the proxy route; it does not create a server or check whether your subscription is still usable. A connection matching PROXY may still fail because the server is unreachable, credentials don’t match, the destination service has an issue, or the app times out. Test with a server you already have: check the selection on Home, then use Connectivity Test as an additional check. A successful test means there was a response under those test conditions; it does not guarantee every service will work. When comparing Config and Proxy, use the same server, network, and target in both tests. Otherwise, you can’t attribute the difference to the rules.
DIRECT: The Client Is Still Running
DIRECT means the target connection is not forwarded through a proxy server. The current network must still be able to resolve and reach the target. If local.example.com matches DIRECT but won’t open, check that the device is on a network that can access the service, that the name resolves to the expected address, and that the service is listening. Switching to Direct can help with comparison, but don’t treat the result after turning off the client as equivalent to a DIRECT rule. When the client is off, the active config no longer handles the connection, and conditions such as DNS settings may also change.
A page’s main request and its supporting requests can use different direct and proxy routes. Don’t check only whether the page title appears. Test the affected action, such as login, refreshing a list, or loading an attachment. If any dependency fails, the app may show a generic connection error. Checking the domain for that dependency makes it easier to determine the necessary rule scope than switching the entire workflow to a different mode.
REJECT: A Match Stops the Request; It Does Not Try the Next Rule
REJECT blocks a matching request. The example blocks blocked.example.com, so its exact match comes before the suffix proxy rule. If the app then makes another request, such as to a backup host, that request is matched independently; it does not mean the original request fell through from REJECT to the next line. The app may show a loading failure, an immediate error, or a retry. The symptom alone does not prove whether the block took effect.
A domain rule that blocks a host also affects normal requests to that host when they meet the rule’s conditions. If blocked and normal content share a host, domain rules alone can’t distinguish their paths. Test one exact rule in a copy of the config, and check both the request that should be blocked and the one that should remain available. If they can’t be distinguished, don’t expand the rule to the entire parent domain. See How to Write REJECT Rules for more examples and limitations.
Rule Order: First Match, Exceptions, and FINAL
To understand ordinary rules in Config mode, start with one principle: rules are checked from top to bottom, and the first match determines the policy. Rule type does not reorder priority for you. An exact domain does not automatically take precedence over an earlier suffix rule, and a longer address prefix does not automatically take precedence over an earlier wider subnet. Two configs on the same device can contain the same rules and still produce different results if their order differs.
Put Exceptions Before the General Rule That Would Match Them
[Rule]
DOMAIN,login.example.com,DIRECT
DOMAIN,unused.example.com,REJECT
DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
FINAL,PROXY
For a target of login.example.com, evaluation ends at the first rule. unused.example.com matches the second, and files.example.com matches the third. A domain captured by the third rule won’t be reassigned by a later rule, even if its address matches GEOIP,CN. Conversely, moving the regional rule earlier may classify connections before they reach a domain rule. To check rule order, don’t test only a target whose result happens to be the same under both rules; choose a sample where overlapping rules select different policies.
To test rule order, copy the config and swap only the two relevant rules. Don’t change DNS, the server, or the final policy. After saving, confirm the copy is active, then test the exception host, a general suffix host, and an unrelated host. Testing only the exception may show that it works again while missing a general rule that has been preempted. Testing only a general host may miss an exception that never matched. Negative samples are useful too: they reveal whether a broad rule affects unrelated traffic.
Use FINAL to Set the Default for Requests That Don’t Match
[Rule]
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT
This config routes the specified domain and its subdomains through the proxy, with all other traffic going direct. Changing FINAL,DIRECT to FINAL,PROXY affects every applicable request that did not match an earlier rule, not just one host that won’t open. Before writing a config, state where traffic outside the list should go, then choose the fallback policy. When merging configs, keep one explicit FINAL at the end; don’t append additional rules after an existing FINAL.
When a request matches FINAL, first decide whether it should have been handled by the default policy. If not, check whether the target is another subdomain, uses an IP address directly, was reached after a redirect, or depends on a request attribute the client didn’t obtain. Adding a specific rule for a missed target corrects match scope; changing FINAL changes the default policy for the entire config. These are not interchangeable fixes.
Check for Duplicate and Shadowed Rules Before Merging
In the merged text, check each specific exception against broader rules above it, including duplicate lines for the same target. For example, two DOMAIN,api.example.com rules with different policies don’t make the later one take priority; the earlier rule is the one to test. Overlapping scopes aren’t always a problem: when a narrower rule has a different policy and comes first, the overlap is intentional. Conversely, a broader rule above a specific rule with the same policy may make the latter redundant. Before removing it, check whether it documents maintenance intent or a planned exception.
Group rules into clear sections by intent: single-host exceptions, domain suffixes, address or regional rules, and the default policy. This isn’t a required template. If a private subnet should take precedence over a group of domains, order rules to reflect that and document any condition that relies on name resolution. Priority is not a memorization exercise. For any target, you should be able to explain which rules don’t match, which one does, and which rules are no longer checked.
Common Patterns: List-Based Routing, LAN Exceptions, and Exact Blocks
Each block below is an independent reference; don’t concatenate them into a single config. Each one states its default action, exceptions, and how to test it. Replace example domains and subnets only with ones you’ve verified for your own devices; use a server you already have for proxy tests. If your config also contains [Host] or [URL Rewrite], leave those sections unchanged while testing routing patterns so you don’t mistake address mapping or request redirects for rule behavior.
Pattern 1: Proxy Only Explicitly Listed Services
[Rule]
DOMAIN,login.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
DOMAIN,assets.example.net,PROXY
FINAL,DIRECT
Suitable for configs that default to direct routing and proxy only a small number of service targets. First test the login host using Direct, then test a subdomain of the service domain using the proxy, and check how a separate resource on another domain is handled. Don’t use the homepage loading as the only acceptance test: it may display cached content while authentication or static resources use different connections. Start with a clean or separate session if possible and repeat a complete action, such as logging in and opening a page that hasn’t loaded before. Record the results for the main request and its resource requests separately.
When adding a resource domain, start with DOMAIN so other uses of that domain don’t get routed through the proxy too. Upgrade to DOMAIN-SUFFIX only after testing confirms that its subdomains serve the same purpose. If a browser and an app behave differently when accessing the same service, compare their actual targets and where the failure occurs. One working connection doesn’t prove that the other selected the same rule.
Pattern 2: Keep Known LAN Addresses Direct
[Rule]
DOMAIN,printer.example.com,DIRECT
IP-CIDR,192.168.50.0/24,DIRECT
FINAL,PROXY
This pattern defaults to the proxy but adds direct rules for known hostnames and the private subnet actually in use. Accessing the same device by hostname and by address can help distinguish a name resolution issue from a routing issue. If the address works but the hostname doesn’t, check whether the name resolves to the expected address. If the name works but an address doesn’t, confirm you’re using the device’s current address, not an old one or another interface address shown in its admin page.
After switching from home Wi-Fi to mobile data, the target may no longer be reachable. Even on two Wi-Fi networks, the same private address could point to a different device. Don’t add all private addresses as exceptions or blame FINAL when access is lost. If the app relies on local device discovery, check the app’s local network permission and the network the device is on. A direct rule alone does not guarantee that broadcast, discovery, and the connection will all work.
Pattern 3: Block a Confirmed Host Without Blocking the Rest of Its Domain
[Rule]
DOMAIN,telemetry.example.com,REJECT
DOMAIN,updates.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT
This example blocks only the specified host, leaving updates and service requests under the same suffix unaffected. Before testing, decide which actions may fail and which must still work: confirm the specified host is rejected as expected, then verify the update host and an ordinary service host still work. If the client shows a rejection but the app still completes the same action, it may be using cached content, a backup host, or another transport. Check the actual target rather than automatically blocking the whole group of domains.
If a block causes repeated retries, additional errors, or degraded features, revert that line in a copy of the config and compare results. If reverting restores normal behavior, that shows the rule is related to the symptom, but you still need to find out whether it blocked the target itself or a dependency on the same host. If domain rules can’t separate the two, preserve normal functionality rather than adding more ambiguous DOMAIN-KEYWORD rules. Validate combined rules against actual access targets and expected outcomes, not by how many rules they contain.
Testing and Troubleshooting: Separate Config, Resolution, Policy, and Connection Issues
When something fails, record a repeatable action: the device’s current network, active config name, Global Routing mode, server selected on Home, the app action that triggers the issue, and the known target. Don’t record subscription URLs, passwords, or server credentials. A clear report such as “after reopening the app, submitting a login request to a service I control fails” is more useful than “the app won’t open.” If connection or diagnostic details are available, prioritize the target, policy, and result; there’s no need to collect unrelated data.
Step 1: Confirm the Config Is Handling Routing
Check the connection status, then verify Global Routing on Home and the active file in Config. Editing a backup with the same name, saving only a draft, or importing a file without selecting it can all leave the expected rules inactive. If the issue started after a network switch, confirm the connection has recovered before testing; a connection that just dropped is not evidence of a rule rejection. Start a new request for each test. Reused connections, browser cache, and existing app sessions are poor ways to assess a newly changed rule.
For initial setup and your first connection, see the Getting Started Guide. If Home doesn’t list a working server, first check that your own Subscribe details or individual server information were imported correctly. If the list is empty, follow How to Troubleshoot a Failed Subscription Import and Empty Server List; changing FINAL at random won’t fix a problem with the source of the data. A rule can select the proxy route, but it can’t supply missing server details.
Step 2: Create a Minimal Comparison with One Target
[General]
dns-server = system
[Rule]
DOMAIN,check.example.com,PROXY
FINAL,DIRECT
In a copy of the config, replace check.example.com with a test hostname you control and keep the currently selected server. Predict that the target will match the exact domain rule and all other connections will use Direct by default. If the result differs, first check whether the connection used that hostname; a redirect may send it to another host. Then compare the same target in Direct and Proxy modes. A single speed test is not the same as testing the service. Where possible, compare the same request, network, and time period.
If the same target is unreachable in Proxy mode, the issue may not be rule order. Check that your server is online, its imported details match the parameters provided by its operator, and whether other known reachable targets work through that server. If only Config mode fails while Proxy and Direct work, check the Config match conditions, whether REJECT catches the request first, and whether the config includes Host or URL Rewrite settings. Switch modes for diagnosis, then return to the mode you need to verify.
Step 3: Narrow the Checks Based on the Symptoms
If you don’t get the expected address, check resolution and [Host] first. If you have an address but can’t establish a connection, check routing, subnet reachability, and service status. If the connection is established but you see a certificate warning, redirect loop, or service error, don’t immediately conclude that the server is unavailable. DNS cache, app cache, and connection reuse are separate factors; clearing one won’t necessarily clear the others. Change one thing at a time and make a distinct new request so you can compare results.
If the log or interface doesn’t show the match details you need, don’t treat missing information as proof that no rule matched. Compare with a controlled config: isolate the target with one exact rule and a different fallback policy, then restore the old config in the same environment. If the results differ, reintroduce the old config’s rules and other sections a few at a time. Don’t reset every rule and setting before reproducing the issue; even if service returns, it will be difficult to identify the line that caused the failure.
Maintenance and Rollback: Manage Config Sources, Rule Changes, and Test Cases
Long-term maintainability depends on a clear default policy, traceable exceptions, and changes you can roll back. Keep the file used day to day separate from experimental copies. If a service fails, first switch back to a verified config, then investigate in a copy. Restoring an older config does not restore the previous server state: server selection, subscription updates, and the current network may have changed. After every rollback, confirm the active file and Home selections, then retest with your earlier samples.
Distinguish Config Files from the Server List
Rules in Config describe routing and related settings; the server list imported through Subscribe provides connection targets. Saving a copy of the rules does not save server credentials, and updating the server list does not fix a rule condition. If a remote config you use is maintained by its provider and you need to add a local exception, save a separate working copy and note its source. Treat any newly retrieved remote config as a fresh merge; don’t assume it will preserve local edits.
When comparing two config files, first check whether [General], [Host], or [URL Rewrite] changed, then review rules added, removed, or reordered in [Rule]. The fact that both files import successfully only means their text was accepted; it doesn’t mean they behave the same. Check especially whether broad rules moved ahead of exceptions, the default policy changed, or connections once handled by a domain rule now depend on resolved addresses to determine their route.
Define a Verifiable Expected Result for Every Change
[Rule]
DOMAIN,status.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT
Write expectations concretely—for example, “the status host stays direct, the service subdomain uses the proxy, and an unrelated host stays direct”—not “rules optimized.” That tells you to test at least three targets. For a LAN exception, add an address outside the allowed subnet. For an IPv6 condition, confirm the test actually uses IPv6. For a blocking rule, also verify that same-domain features that must work are still available. Example domains and subnets do not test real-world availability; use targets you control and whose expected behavior you know.
For an important service, keep a repeatable service action as an acceptance test instead of checking only the homepage. After changing a login exception, log in and return to a service page at least once. After changing a file service rule, test an actual resource request. Make sure an old session won’t mask a change in connection behavior. When a sample fails, record the target, selected policy, and whether resolution succeeded. That’s more useful than an unqualified list of successes and failures.
Roll Back One Change at a Time, Not the Entire File
If a merged config copy causes a failure, first restore the previous verified active config and check whether the service recovers. If it does, revert only one group of changes from the problematic config—for example, restore FINAL first, keep the other rules, and see whether the issue remains. If restoring the config doesn’t bring service back, the cause may also involve the current network, a server change, or app state. Return to Testing and Troubleshooting instead of continuing to remove unrelated rules.
Before deploying the config to your other devices, check that their interface features, config source, and network conditions are compatible. Copying an example moves the text, not device permissions, DNS environment, or selected server. Keep policy intent, rule scope, and rollback steps in your documentation; store personal subscription URLs and credentials separately and securely. A maintainable baseline is one where you can reproduce matches with the active file, identify which layer caused a failure, and restore verified behavior.