At a glance

This guide is for users who already have service details and want to read or edit a Shadowrocket config file. Start by identifying the boundaries of the four sections, then follow the matching process with rules and mapping examples you can verify. Finally, back up, edit, enable, and test your changes. The examples explain syntax; they are not a complete config to replace your existing settings.

Check your platform first, then distinguish service details from config files

For Shadowrocket download options, see the downloads for all platforms: the iPhone and iPad app costs $2.99 as a one-time purchase on the App Store. The developer is Shadow Launch Technology Limited; check the App Store listing for system requirements. The Mac (Apple silicon and Intel), Windows, Android, and Linux versions are free. The steps below refer to interface labels such as Home, Config, and Settings; control locations vary by platform.

Service details tell you which server to connect to and which protocol and authentication parameters to use. A config file determines how traffic is handled. A server entry in an existing subscription is not the same thing as the .conf enabled in Config. Updating a subscription does not switch configs, and selecting a config does not add a working server. This guide assumes you already have your own service provider and subscription. It does not provide, sell, or recommend nodes or subscriptions.

4 sections
Covers General, Rule, Host, and URL Rewrite
6 rule types
Common matching keywords and FINAL, explained below
2 ways to get it
Paid on iPhone / iPad; free on Mac / Windows / Android / Linux

.conf basics: sections, key-value pairs, and rules

A .conf file is a text config. A name in square brackets declares a section; the lines that follow belong to it until the next section name. Each section uses its own syntax: [General] and [Host] commonly use key-value pairs, [Rule] uses comma-separated fields, and [URL Rewrite] organizes entries around a match expression, target, and action. Do not move statements from one section directly into another.

[General]
dns-server = system

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

[Host]
example.com = 192.0.2.10

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

When reading a file, find the section name first, then check the delimiter used for each line's parameters. Use standard ASCII commas in rules; make sure your editor does not replace backslashes in regular expressions. While troubleshooting, record the reason for each change on a separate comment line rather than assuming comments can be appended to any line. The same file extension does not mean configs in other formats can be imported as-is.

[General]: global options are not per-site routing rules

[General] holds options that affect overall behavior, such as DNS resolution settings. In this example, dns-server = system explicitly selects system DNS. It does not describe the app's current default behavior, nor does it guarantee compatibility with every network. If the system network cannot resolve names, selecting system DNS alone will not fix the upstream problem.

Runtime options in Settings need to be checked separately. For example, Settings → On Demand controls connections triggered by conditions; it does not define which Rule should match example.com. If the connection comes back after you manually disconnect, check whether On Demand is enabled and review its conditions before removing the Rule section.

[Rule]: match in order, then apply the target policy

The core of [Rule] is a match condition and a handling target. Rules are normally checked from top to bottom; when one matches, its target is used. Put more specific exceptions before broader rules. DIRECT means connect directly, REJECT denies the request, and PROXY selects the proxy policy. If you use a custom policy name, make sure it is actually defined in the current config; do not enter an arbitrary label.

KeywordExampleWhat it matches
DOMAINDOMAIN,example.com,DIRECTMatches the exact domain example.com, not its subdomains.
DOMAIN-SUFFIXDOMAIN-SUFFIX,example.com,PROXYMatches example.com and its subdomains, not any string that happens to end with it.
DOMAIN-KEYWORDDOMAIN-KEYWORD,example,REJECTMatches requests whose domain contains example; the scope may be broader than expected.
IP-CIDRIP-CIDR,192.0.2.0/24,DIRECTMatches by destination IPv4 address range; the range shown is for documentation only.
GEOIPGEOIP,CN,DIRECTMatches a region based on an IP geolocation database, regardless of webpage content.
FINALFINAL,PROXYCatches traffic not matched by earlier rules; usually placed at the end.

For example, to send example.com direct while proxying its other subdomains, write DOMAIN,example.com,DIRECT first, followed by DOMAIN-SUFFIX,example.com,PROXY. If you reverse the order, the suffix rule matches the root domain first, so the later exact-match rule never handles that request.

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

Domain rules and IP rules match on different criteria. IP rules may involve DNS resolution, depending on related options. Do not interpret an IP address being assigned to a region as meaning the domain is registered there, and do not move FINAL above rules you are still testing. To check the result, inspect the actual match details rather than inferring them from whether a webpage loads.

Global Routing: check whether Config routing is active

If the file syntax is valid but the rules do not behave as expected, first check Home → Global Routing. Selecting Config is the direct way to test the Rule routing in that config. Proxy and Direct switch the handling direction for all traffic; they do not replace testing individual rules.

Config

Recommended

Routes traffic using the rules in the currently enabled config. A matched rule may target PROXY, DIRECT, REJECT, or a defined policy.

Use this to test the Rule examples and rule order in this guide.

Proxy

Handles traffic through a proxy instead of choosing proxy or direct based on the same set of domain rules. A working proxy connection is still required.

Use this to check whether the issue is related to routing in Config.

Direct

Handles traffic by connecting directly. A website loading directly does not prove your proxy settings are correct or that a Rule matched.

Use this to check how your local network reaches the destination directly.

Scene

Applies settings based on scene conditions. Before judging the result, check which scene and config are active; the file you edited alone is not enough.

Use this when you have configured scene conditions and need settings to change with the environment.

[Host]: set an address for a domain, not a port or credentials

[Host] is for local domain-to-address mappings. example.com = 192.0.2.10 maps the name to the specified address; it does not route the website through a proxy or change the service port. The example address is not a real service address. Use a mapping only when it comes from a service you are authorized to use or a managed network.

Host mappings vs. Rule routing

Host handles names and addresses
  • Specifies which address a domain resolves to.
  • Mappings do not include URL paths or login credentials.
  • If an address changes, check whether the old mapping is still valid.
Rule handles traffic policies
  • Specifies whether a request goes direct, through a proxy, or is rejected.
  • DOMAIN-SUFFIX can match a range of subdomains.
  • Rule order determines which matching condition is handled first.

If you need to change both the address and the traffic policy, check Host and Rule separately. Adding a Host mapping does not replace a routing rule.

HTTPS also verifies that the certificate matches the domain. Mapping a domain to an arbitrary address does not make the certificate at that address valid. If a mapping causes a certificate name mismatch, the wrong site to load, or repeated timeouts, remove it and verify the service address first rather than hiding the problem by ignoring certificate errors. Apps that use their own resolution mechanism may not follow this mapping.

[URL Rewrite]: match request URLs and apply rewrite actions

[URL Rewrite] deals with URLs, not server protocol selection. The line below uses a regular expression to match URLs beginning with http://example.com/, keeps the path in the HTTPS target, and uses the 302 redirect action. In the expression, \. matches a literal period, (.*) captures the remaining path, and $1 refers to the first capture group.

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

Edit and test one variable at a time

Before your first edit, keep a restorable copy. A complete config may contain other sections or remote references; do not delete everything else just because this guide covers only four sections. The steps below start with a config that already connects and aim to limit the scope of changes, not rebuild an entire service.

  1. Back up the config

    Open Config, find the currently enabled config, and use that entry's export or share action to save a copy. Note the file name and the current Global Routing mode.

  2. Edit one item

    In Config, open the editor for the relevant config and change one item in one section. To test a Rule, start by adding one exact DOMAIN rule; do not change DNS and Host at the same time.

  3. Confirm the active config

    After saving, return to Config and make sure the edited file is selected. Then go to Home → Global Routing and select Config, so you do not judge rule behavior in Proxy or Direct mode.

  4. Send a new request

    Close the target app's existing connection, then send a new request. Check the destination domain and actual policy in the available connection logs. Existing long-lived connections may retain their previous handling.

  5. Record and restore

    Record the changed line, match result, and any error. If the result is unexpected, restore the backup and repeat the same test; do not keep layering on unverified settings.

If you also need to update an existing subscription, treat that as a separate operation: confirm the update succeeded and the server selected in Home is still working before testing the config. Connection parameters for Shadowsocks, VMess, VLESS, Trojan, Hysteria2, and WireGuard depend on their respective protocols and server settings. Adding FINAL,PROXY will not fix an incorrect password, port, or authentication details.

Common symptoms and what to check

Why is example.com still not handled by the new rule after I saved the config?

Check in order: which file is enabled in Config, whether Home → Global Routing is set to Config, whether a broader rule comes before the target rule, and whether the request is reusing an existing connection. If the actual request is for a subdomain, DOMAIN,example.com,DIRECT alone will not match it; choose an exact domain or DOMAIN-SUFFIX rule as needed.

I added a Host mapping and latency looks normal, but the website won't load. What should I check?

Remove the new mapping first, then send a fresh request to the same destination. A server latency test and resolving the target website are different tests: normal latency does not prove the Host address is correct, the destination service is listening, or the certificate matches. The 192.0.2.10 in this guide is for illustration only; leaving it in place directs the corresponding requests to an example address.

Why did my local changes disappear after updating a remote config?

A remote update may replace the local file, depending on how it was imported and maintained. To preserve changes, save a separate copy and note the differences first, then review each item after the update. Do not assume locally added Rule entries will merge automatically with remote content, and do not share a complete config or subscription link that contains authentication details.

Do all four sections have to be included?

There is no need to add empty sections or unrelated settings just to make the file look complete. If you do not need a fixed mapping, you do not need to copy Host. If you do not need URL rewriting, do not add URL Rewrite. Keep only what you need for the specific goal and check the behavior of the active config; the snippets in this guide are not universal defaults.

Get Shadowrocket and follow the setup guide

The iPhone and iPad app is a $2.99 one-time App Store purchase. The Mac (Apple silicon and Intel), Windows, Android, and Linux versions are free. Choose your device on the downloads page, then follow the guide to add your existing service details. Config files organize settings and traffic routing; they do not include a service plan.