Shadowrocket Config File Syntax: An Advanced .conf Guide

How a .conf file is organized

A .conf file is a plain-text configuration divided into named sections. A section begins with a line in square brackets, such as [General] or [Rule]. Settings beneath a header belong to that section until the next header. A line that looks valid in one section may have a different meaning, or be invalid, in another, so preserve section boundaries when editing.

Common sections include [General] for general behavior, [Proxy] for proxy definitions, [Proxy Group] for policies made from proxy entries, [Rule] for traffic matching, and optional sections such as [URL Rewrite], [Script], and [MITM]. A configuration does not need every possible section. Keep only the settings required by your own setup, and check the configuration’s existing structure before adding anything.

The following is a structural example, not a ready-to-use configuration. Replace the proxy details and policy names with values that exist in your own file. The example domain uses example.test so it is not mistaken for a real service destination.

[General]
dns-server = system

[Proxy]
MyProxy = ss, server.example.test, 443, password=REPLACE_WITH_YOUR_VALUE, encrypt-method=aes-128-gcm

[Proxy Group]
Main = select, MyProxy, DIRECT

[Rule]
DOMAIN-SUFFIX,example.test,Main
FINAL,DIRECT

The proxy line illustrates the general idea of a named entry followed by a type and parameters; the exact fields depend on the protocol and the details supplied for your own server. Do not paste a sample password into a live file, and do not assume that a sample cipher, port, DNS option, or policy name matches your service. A configuration that imports successfully may still contain an unusable server entry or rules that send traffic somewhere other than you intended.

Edit and import a working copy

Start from a copy of the configuration you already use, rather than replacing it with a generic sample. A remote subscription, a local configuration file, and a manually entered server are different sources of information. A .conf file can organize rules and related settings, but it does not create a server account or supply service details. Make sure the file’s proxy entries and policies correspond to your own setup.

1. Find the active file

   In Shadowrocket, open Config and identify the configuration currently in use. Note its name and preserve an unchanged copy before editing. If the configuration is maintained by a subscription, check whether a later update could replace your local edits.

2. Change one item

   Edit one section or a small related group of lines at a time. Use plain text, retain the square-bracket headers, and check commas, spelling, and policy names. Avoid placing a rule under [Proxy] or a proxy definition under [Rule].

3. Import the copy

   Use the import or file-management options available in Config to add the edited file. Interface labels and import choices can vary by app version and device. Keep the previous configuration available so you can switch back if the new file is incomplete.

4. Test a new request

   Select the intended configuration, connect using your own server details, and test a new request to a destination affected by your change. Review Data or the available connection records, then compare the matched rule and outcome with what you expected.

Do not use a successful import as the only test. Importing checks whether Shadowrocket can read the file, not whether a remote rule source is reachable, a proxy entry is valid, a destination resolves, or a website accepts the resulting connection. Test a small, predictable case and record the active configuration, network type, destination hostname, and time. If a result changes, you can then relate it to the single edit you made.

Rule order and remote RULE-SET sources

In Config routing, Shadowrocket evaluates applicable rules in order. A more specific rule placed after a broader matching rule may never determine the result, because an earlier rule can already match the request. Put exceptions before broader rules, keep related entries together, and use FINAL as the fallback at the end of the intended rule list. The fallback might be DIRECT, PROXY, or a named policy, depending on your goal.

Rule keywords are identifiers, not explanatory labels. Common examples include DOMAIN, DOMAIN-SUFFIX, DOMAIN-KEYWORD, IP-CIDR, GEOIP, RULE-SET, and FINAL. Check that the number and order of fields are appropriate for the keyword. A policy such as PROXY or DIRECT must be supported by the routing mode and configuration you are using.

A remote RULE-SET points to a list of rules and associates matching entries with a policy. The address above is illustrative, not a recommended source. Use a source you have independently chosen and trust; check its maintainer, update behavior, format, and access requirements. A remote list can change after you import the main configuration, so a previously reviewed rule set is not necessarily identical to the version fetched later.

Remote sources also create a dependency. If a list cannot be fetched, is moved, or changes format, rules that rely on it may not behave as expected. Check the update result and inspect the relevant connection record rather than assuming that a successful connection means the remote list loaded. When testing, temporarily add a narrow rule for a hostname you control or recognize, then verify the selected policy before restoring the intended final order.

[Rule]
DOMAIN,api.example.test,PROXY
DOMAIN-SUFFIX,example.test,DIRECT
RULE-SET,https://rules.example.net/sample.list,PROXY
FINAL,DIRECT

This snippet demonstrates ordering only; the broad DOMAIN-SUFFIX line would match names under example.test before the later remote set gets a chance to decide them. In a real file, place the remote set or specific exception earlier if it must take precedence. Avoid using placeholder policies or URLs as though they were active settings.

URL Rewrite, MITM, and script boundaries

[URL Rewrite] contains rules that transform matching URLs. A typical line has a matching expression, a replacement, and a response code such as 302 or 307, subject to Shadowrocket’s supported syntax. For example, the following is only a pattern illustration; it does not claim that a particular website should be rewritten.

[URL Rewrite]
^https?://old\.example\.test/(.*) https://new.example.test/$1 302

When a rewrite appears not to work, inspect the exact URL scheme, hostname, path, and regular-expression escaping. Test with a request that actually matches the expression and check whether another redirect or cached response is involved. A rewrite rule does not guarantee that the replacement host is reachable or that the destination accepts the request. Keep the expression as narrow as possible so unrelated addresses are not changed.

[MITM] is relevant when a feature needs to inspect or modify HTTPS traffic. HTTPS inspection requires trusting a certificate authority on the device and enabling the relevant certificate option in Shadowrocket. Certificate installation and trust are consequential security choices: an authorized inspection certificate can allow decrypted traffic to be examined by the app or configured features. Enable it only when you understand the purpose, scope the hostname list narrowly, and remove or disable the certificate when it is no longer needed.

[MITM]
hostname = %APPEND% api.example.test

%APPEND% is used in some configuration patterns to add hostnames while preserving existing entries; verify support and behavior in the file you are editing. Do not replace an existing hostname list blindly. Certificate trust does not mean every connection can be decrypted: certificate pinning, application behavior, and other protections may prevent inspection. Do not attempt to bypass protections or inspect traffic you are not authorized to access.

Some configurations use a [Script] section to run code in response to matching requests or responses. Treat any script as executable code, not as a passive rule. Review its source, requested permissions, remote dependencies, update mechanism, and the data it can read or change. A script hosted remotely may be modified after your initial review. Avoid adding scripts from unknown sources, and do not include private tokens, passwords, or account data in a script URL or its logs.

Decrypted traffic can contain session cookies, authorization headers, search terms, and personal information. Use test accounts and non-sensitive destinations where possible, limit the inspection window, and clear diagnostic records when they are no longer needed. A rule that works technically can still expose more information than the task requires; narrow the hostname and data scope before enabling it.

Validate changes with logs and connection records

After editing, test from the smallest useful case to the broader behavior. Keep the selected server, network, and destination constant while checking a rule change. In Home, confirm that the intended configuration and connection state are active. Then open Data or the available connection records and locate the new request by destination and time. Check the matched rule or policy where available, whether the request used the expected route, and whether the connection completed.

If a test fails, compare the result with the untouched backup. An error opening a destination may be caused by a rule, a DNS issue, an unavailable server, a remote list, or the destination itself. Use the connection record to narrow the stage that failed. Remove any debug rule after testing and restore the intended fallback and hostname scope.

Before keeping a modified file, review it for secrets and unintended exposure. Remove real subscription URLs, server passwords, certificate material, tokens, and personal hostnames before sharing a configuration for help. Check that FINAL is present where intended, that sensitive inspection is disabled when not needed, and that the active configuration is the one you actually reviewed.