Shadowrocket .conf File Structure: General, Rule, Host, and URL Rewrite Explained

At a glance

When reading a .conf file, first distinguish general settings, routing rules, host mappings, and URL rewrites. Then check which file is enabled and review Global Routing. This guide is for users who already have a provider and subscription and want to edit a local configuration. Examples explain syntax only and do not include usable connection details. After making changes, check the app’s connection logs to see which rules actually matched.

1. .conf Sections: Each Section Has a Specific Role

Shadowrocket’s .conf files are plain-text configuration files. Section names appear in square brackets, and each section continues until the next section name. [General] commonly contains key-value settings, while [Rule] contains one matching rule per line. Putting the right content in the wrong section won’t produce the intended result.

Home is where you manage connections and select servers, Config is for managing configuration files, and Settings contains app preferences. Server details provided with a subscription are separate from the rules in a .conf file that determine how traffic is routed. Importing or updating a server list does not automatically switch the active configuration file.

4 sections

A breakdown of General, Rule, Host, and URL Rewrite

3 app sections

Home, Config, and Settings each have a distinct role

1 fallback rule

The example places FINAL at the end of Rule

The snippets below illustrate the file structure; they are not complete connection configurations and contain no server details. example.com is a sample domain, and 192.0.2.10 is a documentation-only address. Don’t use either as a real-world setting in your everyday configuration.

[General]
dns-server = system

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

[Host]
example.com = 192.0.2.10

[URL Rewrite]
^http://example\.com/ https://example.com/ 302

Having these sections in one file doesn’t mean every request processes them in the order they appear. Sections organize the configuration; parsing, routing, and rewriting each follow their own processing rules. In particular, don’t read the order above as a fixed request pipeline of “Rule first, then Host, then URL Rewrite.”

2. General: Basic Behavior and DNS Settings

[General] contains basic settings. When reviewing this section, check each key, the value after the equals sign, and the separators used in lists. Don’t paste in fields from other configuration formats just because they look similar. Use settings that Shadowrocket’s editor recognizes, can save, and can actually apply.

[General]
dns-server = system

Here, dns-server = system means to use the system DNS. It doesn’t mean every request must use DIRECT, nor does it specify that a particular website should use PROXY. DNS resolves domain names; routing rules select a policy. The two can affect troubleshooting, but they serve different purposes.

Domain won’t load, but the IP responds: Check the DNS settings and resolution results first. Don’t immediately replace the entire Rule section.
Domain resolves, but traffic uses the wrong policy: Check Global Routing and the matching Rule, rather than changing DNS alone.
Results change after switching networks: System DNS may vary with the network. Note whether you’re testing over Wi-Fi or cellular.
Editing an existing file: Prefer changing the existing setting with the same key. Avoid adding duplicate keys and relying on unclear override behavior.

Test DNS changes separately from routing changes. If you change several General settings, Host mappings, and Rules at once, a site may start working again without revealing which change fixed it. That also makes it harder to restore the original configuration later.

3. Rule: Match from Top to Bottom; Put FINAL Last

[Rule] determines which policy a request uses. Rules are matched in order, and the first match determines how the request is handled. Put more specific rules before broader ones. FINAL has no domain or address condition; it catches traffic that hasn’t matched any earlier rule, so it belongs at the end of this section.

Keyword	Example syntax	What to check
`DOMAIN-SUFFIX`	`DOMAIN-SUFFIX,example.com,PROXY`	Matches the domain and its subdomains, not any string that happens to contain it.
`IP-CIDR`	`IP-CIDR,192.0.2.0/24,DIRECT,no-resolve`	Matches an IPv4 range; no-resolve prevents a DNS lookup from being initiated for this rule.
`GEOIP`	`GEOIP,CN,DIRECT`	Uses an IP geolocation database, not the language of a webpage.
`FINAL`	`FINAL,PROXY`	Has no additional match conditions and serves as the final fallback.

PROXY and DIRECT are policies, not protocol names. Check connection-type settings such as Shadowsocks, VMess, VLESS, Trojan, Hysteria2, and WireGuard in the relevant server configuration. Don’t use FINAL,Trojan as a substitute for a policy. If you use a custom policy name, make sure it exists and is available.

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

With this order, api.example.com matches DOMAIN first and uses DIRECT, while www.example.com can match the later DOMAIN-SUFFIX rule and use PROXY. If DOMAIN-SUFFIX is moved above it, the exact exception won’t get a chance to apply. Test with the full target hostname; another subdomain on the same site is not an equivalent test.

Bottom line: Find the matching rule before changing the fallback

If traffic matches an earlier DOMAIN or DOMAIN-SUFFIX rule, changing FINAL won’t change its policy. Find the matching result in the connection log first, then adjust the relevant rule or its position.

4. Host and URL Rewrite: Address Mapping Isn’t Request Rewriting

[Host] maps a specified domain to an address. [URL Rewrite] rewrites or redirects requests based on URL matching expressions. The former determines “which address this name points to”; the latter determines “how a matching URL changes.” Neither replaces routing policies in Rule.

Host mapping

Section: [Host]
Left side: example.com
Right side: 192.0.2.10
Syntax: example.com = 192.0.2.10

The sample address illustrates the syntax only; users must verify the correct address for an actual mapping.

URL Rewrite redirect

Section: [URL Rewrite]
Matching expression: ^http://example\.com/
Target URL: https://example.com/
Action: 302, temporary redirect

Separate the expression, target URL, and action with spaces.

Host doesn’t change the domain in the browser’s address bar to an IP address, nor does it make the destination server automatically accept that domain. For HTTPS, the certificate name must still match the hostname you visit. Mapping a domain to a server that doesn’t match it can cause certificate errors or an unexpected site response. Correct the mapping rather than routinely disabling certificate verification.

In the URL Rewrite example, ^ matches from the beginning, \. represents a literal dot in a domain name, and 302 tells the client to redirect to the target URL. This example demonstrates redirecting an HTTP URL to an HTTPS address; it doesn’t guarantee that arbitrary paths and query parameters are preserved. To keep them, you need to define capture groups and a replacement expression explicitly.

Test the expression with a single URL first. Don’t start with a broad pattern that matches every domain.
The HTTP example doesn’t require decrypting HTTPS traffic. If a rule needs to inspect HTTPS paths or content, it usually also requires separate HTTPS decryption conditions and trust settings.
If access breaks after adding a Host mapping, remove that mapping first. If a URL Rewrite causes repeated redirects, check whether the target URL triggers the same rule again.

5. Editing in Config: Back Up, Save, Enable, and Verify

Before editing a file in Config, confirm which configuration is currently active. A file appearing in the list, its text being saved, and the file being selected and enabled are three different states. Editing a file that isn’t enabled won’t immediately change the rules used by the current connection.

Keep the originalEdit a copySave and enableCheck the modeStart a new requestReview the log

Keep the original: In Config, confirm the original filename and use the file actions to keep a copy or export the original. If the file comes from a remote configuration URL, keep a recoverable local version first so a later update won’t overwrite your manual edits.
Open the editor: Use the file actions for the target configuration to open the text editor. Keep the section names and change only what you need. Depending on the app’s current layout, the editor may be in the file actions menu; follow what’s shown on screen.
Check the syntax and save: Separate Rule fields with English commas, use equals signs for key-value pairs in General and Host, and separate URL Rewrite fields with spaces. Don’t use Chinese commas, full-width square brackets, or explanatory text as configuration values.
Select the configuration: Return to the Config list and confirm the edited file is enabled. Then check the current server and connection status in Home.
Check Global Routing: Use Config when testing Rule. Proxy and Direct are overall routing modes, so their results alone can’t confirm whether a specific Rule matched. If you’re using Scene, also check which configuration and policy the scene uses.
Start a new connection: After saving, send a new test request and disconnect and reconnect if needed. Existing connections and cached data may retain their previous state. Compare the target domain, matching rule, and final policy in a new connection log.

Settings → On Demand controls automatic connection conditions; it doesn’t determine the order of Rules. If the app reconnects automatically after you make a change, check this section. If a domain uses the wrong policy, check Global Routing and the active configuration. Troubleshoot automatic connections separately from traffic routing to pinpoint what needs to change.

6. Common Issues: Inactive Configurations, Update Overwrites, and Rollback

For each issue, cross-check the active file, current mode, and logs for a new request. A page loading in your browser only confirms that one visit succeeded; it doesn’t prove that a specific rule ran or that the expected server was used.

I saved the Rule, so why is traffic still using the old policy?

First, confirm in Config that the edited file is selected. Then check that Home → Global Routing is set to Config. Review the connection log for a new request. If an earlier rule already matched, edit that rule or change its position instead of adding more rules after FINAL.

Will updating my subscription also update my manually edited .conf file?

Updating a server subscription and updating a remote configuration are separate actions. First, confirm whether you’re updating the server list in Home or a remote file in Config. Fetching a remote configuration again may replace local content, so keep a copy of important changes and compare the file after updating.

I added a Host mapping and now get a certificate error. What should I change?

Remove the new mapping first, then test again with a new connection. Confirm that the mapped address serves the original hostname and check the server certificate. Don’t disable certificate verification to keep an incorrect mapping. Host can change the address a name resolves to, but it can’t change the names covered by a certificate.

How can I recover from a bad edit without affecting existing subscriptions?

In Config, select the backup file again, restore the Global Routing mode you used before testing, and establish a new connection to verify the result. Don’t start by deleting existing servers or subscriptions in Home. Once the original configuration works again, add one change at a time to a copy to identify the problematic line.

The recommended check order is: confirm the file is enabled, check the routing mode, review the matching result, then investigate DNS, Host, or rewrite conditions. A configuration file is useful because its behavior can be checked and its changes rolled back—not because it lets you pack as many fields as possible into one file.