On this page
Start with one connection that is actually routed incorrectly
Rules do not match a website's home-page title. They match information in the actual connection, such as the domain, IP, or process. A single page may request the primary domain, a sign-in domain, an image CDN, and an API. Writing one rule from the address bar often fixes only part of the page.
Hold the node constant, stay in Rule mode, and repeat the failing action. In Connections, record the target, the matched rule, and the egress path. The question to fix is “why did this connection match here first?”—not how to paste an entire online rule list into the configuration.
Record these four items before making changes
- The failing connection's full domain or destination IP
- The rule type and rule content currently shown
- The policy group or DIRECT action ultimately used
- The policy this connection should actually use
Mihomo evaluates rules from top to bottom and stops at the first match
More specific rules usually go before broader ones. The example below sends api.example.com to the already defined “Proxy Selector” group while keeping the broader example.com rule on DIRECT; the final MATCH catches connections that did not match earlier rules.
proxy-groups:
- name: 代理选择
type: select
include-all: true
proxies:
- DIRECT
rules:
- DOMAIN,api.example.com,代理选择
- DOMAIN-SUFFIX,example.com,DIRECT
- MATCH,代理选择After saving and reloading the configuration, close the old page connection and make a new request. If Connections shows DOMAIN,api.example.com and “Proxy Selector,” both the rule and its order are working. If it still shows the previous result, the connection may have been reused, or the current Profile may not have loaded the change.
Only long lists from the same source belong in rule-providers
Direct rules are easier to read when you have only a few local domains. Use rule-providers to separate the data source from the main configuration only when a project maintains dozens or hundreds of domains or IP ranges and needs regular updates. Reference the provider from the main rules with RULE-SET, and assign a policy to the entire set.
A provider supplies rule data; it does not choose a node on its own. In the example, “RULE-SET,work-domains,Proxy Selector” sends matches to the already defined “Proxy Selector” group. If you use your own group name, it must match exactly in proxy-groups and rules.
proxy-groups:
- name: 代理选择
type: select
include-all: true
proxies:
- DIRECT
rule-providers:
work-domains:
type: http
behavior: domain
format: yaml
url: https://rules.example.com/work.yaml
path: ./ruleset/work.yaml
interval: 86400
rules:
- RULE-SET,work-domains,代理选择
- MATCH,代理选择behavior must match the file contents
rule-provider behavior
| Value | What the file contains | What does not belong in the file |
|---|---|---|
| domain | Collections of domains, domain suffixes, and similar domain entries | IP ranges and complete classic rule lines |
| ipcidr | IPv4 / IPv6 CIDR | Conditions such as DOMAIN and PROCESS-NAME |
| classical | Complete typed rules, such as DOMAIN-SUFFIX,... | Overly verbose when you only want to maintain plain domains |
format describes how the file is encoded; common values include yaml, text, and mrs. behavior and format are separate: one defines rule semantics, while the other defines how the file is stored. If plain domain text is declared as ipcidr, the download may succeed but loading will still fail.
Read the format documentation published by the rule source instead of guessing from the URL suffix. When a source changes formats, an old cached file may also remain on the client. The provider name and parsing error in the logs can help confirm what happened.
When a rule set fails to update, check url, interval, proxy, and path
- type
- http updates from a remote source, file reads a local file, and inline places content directly in the configuration.
- url
- Remote rule-source address; handle 401, 403, 404, and timeout according to the HTTP response.
- interval
- Update interval in seconds. Setting it too short only adds requests; it does not make the rules more accurate.
- proxy
- Specifies the proxy used to download the rule source; if the origin is reachable locally, the configuration can also connect directly.
- path
- Cache-file path. Mihomo limits it to HomeDir by default; external paths require SAFE_PATHS.
When a provider download fails, the old cache may still be used, so “the website still opens” does not mean today's update succeeded. Check the provider's latest update time and logs. Keep the old cache until the new source recovers instead of deleting every rule file.
Remote subscriptions are overwritten, so custom rules belong in an override
Editing the remote YAML downloaded into the Profiles directory may work for the moment, but the next subscription refresh will replace it. Clients such as Clash Verge Rev provide merge, script, or rule-override features that insert local content as the remote configuration loads. The exact entry point varies by version; use the Profile override page in your current client.
A custom rule that must run first should be inserted through prepend or an equivalent leading merge, ahead of broad subscription rules. If you merely append it after MATCH, it may be visible in the file but will never be reached at runtime.
prepend-rules:
- DOMAIN,api.example.com,DIRECT
- DOMAIN-SUFFIX,intranet.example,DIRECTAfter reloading, inspect the runtime match instead of merely confirming that the line exists in the editor
Verify one override rule
Save and enable the override
Confirm that it is attached to the remote Profile currently in use.
Reload the configuration
The logs should not show parsing errors for a rule, provider, or proxy group.
Close old connections
Prevent the browser from reusing sessions established before the change.
Repeat the target action
Read the new rule and final policy in Connections.
Manually update the subscription
Make another request after the update to confirm that the override remains.
Only when both requests match the same custom rule have you proven both “works now” and “survives an update.” Finding the text in the editor does not mean it has entered Mihomo's runtime configuration.
When rules do not work, check four layers: download, parsing, reference, and order
provider download 401 / 403 / 404
Address the remote address, permissions, or a migrated path; rule syntax is not involved yet.
provider parse error
Compare behavior and format with the source file's actual contents.
RULE-SET not found
The name referenced in rules does not match the key in rule-providers.
proxy group not found
The rule's target group is missing from the current subscription or has been renamed.
The rule loads but an earlier rule always matches
Reorder the rules so that specific ones come before broad rules and MATCH.
Custom entries disappear after a subscription update
Stop editing the remote file directly; use an override attached to the current Profile.
Every new rule should explain the runtime result
The more rules you add, the more opportunities they have to shadow one another. After verifying the target domain, check whether the other connections on the same page still use direct or proxied routing as intended. If you need only three rules, there is no reason to import a list with tens of thousands of entries from an unknown source.
Finish with a one-sentence runtime explanation: which connection matched which condition, which policy group it entered, and whether that remained true after a subscription update. Leave out rules you cannot explain; this also makes maintenance easier when nodes and the Profile are renamed later.