Shadowrocket
Rules and Configuration Reference

02 / General settings

General, Global Routing, and DNS

Routing mode determines whether rules are used to select a policy

Check Global Routing before troubleshooting rules. Config uses the selected configuration file to choose a policy; Proxy sends requests handled by the client through the current proxy selection; Direct uses a direct connection. These are different routing modes, not three priority levels in the same rule file. If a request connects in Proxy but fails in Config, check which rule it matches instead of immediately assuming the server is down. Likewise, successful access in Direct does not prove the proxy route works.

The phrase “requests handled by the client” sets an important boundary: system behavior outside the app, existing connections, and special configuration conditions can all affect what you observe. After switching modes, test the same target using the same type of request. Don't compare a webpage visit with a background connection from an app. For details on switching modes, see Config, Proxy, and Direct in Global Routing, then use the rule sections on this page to understand the match.

General sets shared conditions; it is not a rule-priority switch

Common fields in General use the key = value format. Check the in-app configuration editor and documentation for supported options. Don't copy fields with the same names from a different syntax system or assume similar field names mean the same thing. The minimal DNS example below uses system to rely on system-provided resolution settings; it does not specify a fixed DNS server address. Before changing DNS, determine whether the issue occurs during name resolution or connection setup.

[General]
dns-server = system

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

DNS resolves names to addresses; policies determine how requests are handled. They work together, but they're not the same thing. A domain can match DIRECT and still fail to resolve. A domain can resolve successfully and still fail because of proxy authentication, the destination port, or a remote connection issue. When troubleshooting, first check whether the domain resolved to an address, then check the matched rule and connection error. A temporary improvement after changing DNS doesn't prove that all the existing rules are correct.

Address rules may require DNS resolution

When a request starts with a domain name but a later rule needs to check the destination IP or GEOIP, matching may require resolving the domain first. This can add latency and may cause related DNS entries to appear in the logs. If you put many address rules before domain rules, requests that could have been handled by domain alone may also trigger extra address checks. Placing specific domain exceptions first, followed by rules that need address information, usually makes the configuration easier to understand.

no-resolve in an address rule can prevent that rule from actively resolving a domain, but it does not turn off all DNS. A request that already has a destination IP can still match an address rule; a request with only a domain and no available address may continue to later rules. After enabling it, test requests made by domain and by IP separately. See the address section for syntax. Don't add this parameter to every IP rule just to reduce a log entry.

Also distinguish the actual IPv4 and IPv6 connection destinations. A domain may return multiple addresses, and the address selected by the app may differ from the first result in a manual lookup. A rule that covers IPv4 private ranges does not automatically cover every IPv6 case. If the same domain sometimes takes different routes, first check the actual destination address, DNS cache, and connection reuse. Then decide whether rules for the other address family are needed. Record these conditions to make the result reproducible.

04 / Addresses and request attributes

IP-CIDR, GEOIP, USER-AGENT, and FINAL

IP-CIDR and IP-CIDR6: match destination address ranges

IP-CIDR uses an address and prefix length to specify an IPv4 network range. 192.168.0.0/16 covers the corresponding private address range, while 192.168.1.20/32 represents a single IPv4 address. A longer prefix means a smaller range, but “more specific” here describes the address set, not rule order. IP-CIDR6 is for IPv6; for example, fd00::/8 represents the corresponding local address range. An incorrect prefix can extend an exception far beyond its intended scope.

[Rule]
IP-CIDR,192.168.1.20/32,DIRECT,no-resolve
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
IP-CIDR6,fd00::/8,DIRECT,no-resolve
FINAL,PROXY

These snippets show only a few address ranges; they are not a complete list of local network rules. DIRECT means the request is sent without a proxy server. It does not guarantee that the destination device is online, a route exists, or access is permitted. If a printer or local service is still unreachable, check whether its address has changed, whether the current network allows device-to-device communication, and whether the required system permissions are available. A matching rule alone doesn't mean every subsequent error is caused by the app.

no-resolve is an optional matching modifier that prevents actively resolving a domain just to evaluate that address rule. A request that already has a destination address may still match. A request with only a domain and no applicable address information may continue to later entries. If you access a local service by domain, a private address rule with this parameter may not be enough. You can handle known hosts explicitly with DOMAIN, then keep the address range rule if needed.

GEOIP: classify by location using an IP database

GEOIP,CN,DIRECT means use DIRECT when the target address is classified as CN by the database in use. It does not match a domain suffix or identify a webpage's language, account region, or service owner. A Chinese-language page may use infrastructure in another region, and the same domain may resolve to different addresses under different conditions. GEOIP is better suited to broad address classification than to replacing domain exceptions for specific services.

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

An address database's location classification and the reachability of the actual route are separate questions. Matching a region doesn't guarantee a fast direct connection or a successful one; the target address may also vary across networks. When troubleshooting, record the actual destination IP, matched entry, and error type. If a known service needs a fixed policy, add a domain rule that clearly describes its scope instead of replacing all GEOIP rules because of one unexpected result.

USER-AGENT: useful only when the request attribute is visible

USER-AGENT matches an available User-Agent attribute. For example, USER-AGENT,ExampleApp*,DIRECT uses an asterisk as a wildcard. This does not identify traffic by app name or process, and you can't assume that every encrypted connection exposes this request header. In ordinary HTTPS connections, the header is inside encrypted content and may not be available to the client. Use this rule only as a supplement when the required attribute is available; it cannot guarantee consistent routing for every request from an app.

FINAL: handle requests with no earlier match

FINAL takes no domain or address parameter. Its format is FINAL,PROXY or FINAL,DIRECT. Put it at the end of the matching list to specify how to handle requests that match none of the preceding conditions. If it appears in the middle, later ordinary rules usually won't get a chance to match. Choose a fallback based on your configuration: PROXY requires a working proxy, while DIRECT relies on direct access through the local network. Neither guarantees a successful connection.

When combining these rules, start by asking what reliable information is available for the request. If the domain is known, express the intended behavior with domain rules. Use CIDR only for address ranges, place broader location classification later, and use FINAL to handle anything left over. For rules such as USER-AGENT that depend on visible request attributes, plan what happens when that information isn't available. A good configuration explains both what happens on a match and where unmatched requests go.

06 / Rule priority

Rules are checked top to bottom; the first match wins

There is no automatic “more specific rules first” behavior

Rule entries are checked in the order they appear in the file. When a target matches an entry, that entry's policy applies, and later ordinary entries are not checked to select a different policy. DOMAIN does not automatically take precedence over DOMAIN-SUFFIX, a single-address rule does not automatically take precedence over a larger network range, and REJECT doesn't get priority just because of its meaning. Priority starts with position in the configuration. This explains many cases where a rule appears to have no effect: an earlier entry matched first.

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

For api.example.com, the first line specifies DIRECT. For www.example.com, the first line doesn't match, so the second line specifies PROXY. Other domains continue to GEOIP and finally fall through to FINAL. This is a decision chain with a clear stopping point, not a scoring system for every matching rule. Even if www.example.com resolves to an address that matches the later GEOIP rule, it still uses the earlier suffix rule's policy.

Use a counterexample to explain rule order conflicts

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

In this counterexample, the suffix rule matches api.example.com first, so the exact rule below it can't create the intended exception. Move the exact exception above the broader rule instead of copying it to the end of the file. When multiple entries have the same condition, the first one usually determines the result. Duplicate entries make a configuration harder to read and may lead someone to assume a later change overrides an earlier setting. When reviewing rules, check for duplicates and overlapping scopes.

Put local exceptions first, then service-wide rules, then broad classifications

One maintainable approach is to put explicit allow or reject exceptions first, followed by service domain rules, then address and location rules, and finally FINAL. The app doesn't require this exact template; it simply makes the intent easier to follow. You can use a different order when your needs call for it, but be ready to explain why each rule must come before the one above it. Don't alphabetize the entire Rule section just to make it look tidy; that could change the existing match order.

Exceptions may overlap too. If you want a main domain to use PROXY, one API host to use DIRECT, and another specific host to use REJECT, put both exact-host entries before the main domain suffix rule. If you also add a DOMAIN-KEYWORD that includes the same string, confirm that it won't take over those exceptions first. When reviewing a rule, don't just ask whether it works on its own. Check which broader conditions above it may match first, and which rules below it may no longer be reached.

Review the actual rule list after configuration updates

A remote configuration update may reorder entries, remove local changes, or add new broad rules. A successful update only confirms that the content was retrieved; it doesn't mean your custom rules were preserved. After updating, check key exceptions, FINAL at the end, and custom group references, then test common targets. If you need to maintain personal exceptions over time, use a configuration approach you can manage consistently and keep notes on your changes. Don't rely on memory to find every difference after each update.

To troubleshoot rule order, first write down the expected decision process for a request: its target name, whether an address is available, the earliest entry it might match, and the expected policy. Compare each step with the logs. If the result differs, first confirm that the correct file is selected, Global Routing is set to Config, and the log shows a new connection. Only after those basics are verified is it useful to examine the exact matching behavior of a keyword.

Balance performance with readability. Placing exact domain rules before address checks that require resolution can often avoid unnecessary lookup dependencies, but don't combine clearly defined targets into a broad keyword just to reduce the number of lines. Prioritize behavior you can explain and reproduce, then remove genuinely redundant entries. A shorter file with unclear boundaries isn't necessarily easier to maintain than a longer file with clearly defined responsibilities.

08 / Validation and maintenance

Use Logs to troubleshoot and a backup copy to restore configuration

Start with observations you can reproduce

Before testing, note the current network, Global Routing mode, selected configuration file, and proxy selection. Then choose one target and one action, such as opening a specific page or requesting an API, rather than saying the entire app doesn't work. Connectivity Test can help assess connection conditions, but a successful test doesn't replace a real request to the service. A proxy connection being established, a domain resolving, and a target API responding are three separate results to verify.

Keep other conditions the same during testing. Don't switch networks, change servers, and modify DNS and rules all at once. Even if things improve, you won't know which change made the difference. After saving a rule, start a new request and account for connection reuse and caching. If needed, re-establish the connection when it's safe to do so. For issues that occur only on certain networks, record the results for each one instead of letting a single success override an earlier failure.

Read the logs in three stages: request, match, connection

The exact fields shown in Logs depend on the app. Start by finding the request target and confirming that it's the host you tested. Then check the policy and any visible rule details, followed by connection errors or the response. If a log shows only an IP address, don't assume domain rules are failing; check whether the request provided a usable hostname. If the request clearly matched REJECT, review the rejected rule's scope before changing server ports.

For a resolution failure, check whether the request obtained an address and review related settings in General and Host. For a connection timeout, determine whether the proxy route failed to connect or the destination service didn't respond. For an authentication failure, check that the existing server details are complete. Different errors don't have one universal fix. If a single log entry isn't enough, correlate nearby resolution and connection entries by time, but don't assume every background request at that moment belongs to your test.

Reduce the configuration to a minimum, then restore entries one at a time

You can isolate issues in a complex configuration by testing a reduced copy, but keep the existing details required to establish a connection. First remove temporary rewrites and mappings unrelated to the target, then use one exact domain rule and FINAL to make the outcome clear. If the minimal copy works as expected, restore the original entries in batches and test the same target after each batch. This helps identify which set of conditions changed the result instead of adding more patches to the full file.

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

This snippet is only for testing rule selection; don't use it to overwrite your full configuration without a backup. The expected result is DIRECT for api.example.org and PROXY for other unmatched requests. If the result still differs, first check that the copy is selected, Global Routing is set to Config, and the log corresponds to a new request. If the result is correct but the target still fails, investigate the connection route instead of expanding the rule keywords.

Keep change notes and protect private information

For each change, keep a short note of the target, affected entries, expected result, actual result, and how to restore the previous configuration. Before exporting, check for server addresses, authentication details, private subscription links, or sensitive Host mappings. Share only a redacted minimum example when discussing an issue. Logs may also include destinations and query details, so retain only what's needed to explain the problem. For common import and connection issues, see the FAQ. For your first setup, return to Getting Started.

Before switching devices, check separately how to restore the app, server details, and configuration files. Getting the app again from the App Store doesn't necessarily restore all personal configuration. Check the App Store listing for system requirements and purchase availability. See configuration backup and device migration for guidance. After restoring, verify the file and credentials, then test key rules again. A matching filename doesn't guarantee matching contents.

Maintenance is complete not when you've stopped making changes, but when key targets match as expected, unmatched requests have a clear fallback, every exception has a clear purpose, and you can restore a working copy if something goes wrong. Verify rule selection separately from connection results, and keep remote content separate from personal changes. This gives you a consistent troubleshooting approach when network conditions change or configuration updates arrive.