Clash config.yaml: A section-by-section guide to ports, DNS, and writing proxies and rules
A section-by-section guide to mixed-port, dns, proxies, proxy-groups, rule-providers, and rules in a complete Clash config.yaml.
Complete example: See how the configuration sections work together
This example is for mihomo (formerly Clash Meta) builds that support inline rule sets. It uses domain rules and explicit proxy requests to verify traffic routing, without relying on subscription updates or TUN. The original Clash may recognize some of the same fields, but don't assume this file works across all cores. In particular, check that your core supports the rule-set type before using it.
mixed-port: 7890
allow-lan: false
mode: rule
dns:
enable: true
enhanced-mode: fake-ip
fake-ip-range: 198.18.0.1/16
nameserver:
- 223.5.5.5
proxies:
- name: "Local SOCKS5"
type: socks5
server: 127.0.0.1
port: 1080
proxy-groups:
- name: "Office Egress"
type: select
proxies:
- DIRECT
- "Local SOCKS5"
rule-providers:
office-domains:
type: inline
behavior: domain
payload:
- "+.example.org"
rules:
- DOMAIN-SUFFIX,example.com,DIRECT
- RULE-SET,office-domains,Office Egress
- MATCH,DIRECT
A request enters through mixed-port, then the core checks the destination against rules in order when rule mode is enabled. A match for office-domains routes it to "Office Egress," which then uses the egress currently selected for that group. The rule can match the policy group even when DIRECT is selected. To verify routing, check both the matched rule and the actual egress.
mixed-port: Local listening port vs. upstream port
mixed-port: 7890 lets the core accept both HTTP proxy and SOCKS5 connections on the same local port. Applications connect to 127.0.0.1:7890; the 1080 in proxies is the upstream port the core connects to after selecting the example proxy. One port connects an application to the core, the other connects the core to an upstream server. They aren't interchangeable.
allow-lan: false is suitable for local use. Defining a listening port does not enable the system proxy setting. To test a specific application, configure it to connect to the port explicitly. If you need to handle apps that ignore the system proxy, evaluate TUN separately. TUN uses a virtual network interface to capture traffic covered by its routing settings; this is a different traffic entry point from an application connecting directly to 7890.
What to change when a port is already in use
If the log reports address already in use, first check whether a second core instance is running. If you switch to 7891, update any manually configured browser proxy settings, terminal arguments, and other references to use 7891 too. Desktop clients may override the configured port, so use the actual listening port shown in the startup log when troubleshooting.
dns: Upstream resolution vs. fake-ip
dns.enable: true enables the core's DNS module, and nameserver specifies the upstream server it uses for regular queries. This example uses a traditional DNS server at 223.5.5.5. Before using it, confirm that the server is reachable on your network and meets your local DNS requirements. Changing this section alone won't route all system or browser DNS queries through the core. Browser Secure DNS, apps using an explicit proxy, and DNS handling through TUN need to be assessed separately.
With enhanced-mode: fake-ip, the core can return a temporary mapped address for eligible domain A queries. An address in the 198.18.0.0/16 range doesn't mean the website is hosted on that network. The subsequent connection must pass through the same core so it can map the address back to the domain. When accessing HTTPS through an HTTP proxy, an app can usually provide the destination hostname in the CONNECT request, so it doesn't need to receive a fake IP first for a domain rule to match.
Can't access a local network service with fake-ip enabled
First check whether the domain is resolved by the core, then check whether the same app's connection also passes through it. If the app receives a mapped address but bypasses the core when connecting, changing nameserver alone usually won't help. If the service needs its real address, add fake-ip-filter to the existing dns section and exclude the exact domain, such as printer.home.arpa. Also make sure the upstream DNS server can resolve that private name. The filter changes how the address is returned; it doesn't add local network records to public DNS.
proxies and proxy-groups: Manage proxies and policy groups separately
Top-level proxies entries define the settings needed to connect upstream. Each proxy has a name, protocol, server, and port, with other fields depending on the protocol. This example uses type: socks5. When switching protocols, don't just change type and keep the old fields. For subscription proxies, first check whether the subscription generates a complete config or the client loads the proxy list through proxy-providers.
proxy-groups define the egress options available to routing rules. The group's proxies list contains proxy names, not server addresses; DIRECT is a built-in policy. "Office Egress" uses select, so you choose the proxy manually rather than having the client switch automatically based on latency tests. If proxies come from a named proxy-providers entry, a group can reference that provider with use. Don't confuse the provider name with a proxy name.
When renaming, check references in the direction they point: after renaming the "Local SOCKS5" proxy, update the group member list; after renaming the "Office Egress" group, update the rule target. Even an extra space makes it a different name. For subscriptions that refresh periodically, use the client's override or merge feature to preserve local changes. Edits to a cached subscription file may be overwritten on the next refresh.
rule-providers and rules: Define rule sets, then choose an egress
rule-providers define rule sets but don't specify where traffic goes. The example's office-domains uses behavior: domain and +.example.org to match the root domain and its subdomains. The policy is assigned by RULE-SET,office-domains,Office Egress. Defining a rule set without referencing it in a rule won't route requests through that rule set.
| behavior | Example entry | Purpose |
|---|---|---|
domain | +.example.org | Matches the specified domain and its subdomains. |
ipcidr | 192.0.2.0/24 | Matches destination IP ranges; this uses a documentation-only example range. |
classical | DOMAIN-SUFFIX,example.org | Keeps the rule type; don't append a policy group name to the entry. |
To move a rule set into a local file, change type to file, set format: yaml and path: ./rules/office.yaml, and move the entire payload section into that YAML file. Relative paths are resolved from the core's working directory; don't assume it's the same directory shown for the subscription file in the client. For remote updates, use type: http, set url and an interval in seconds, and make sure the content format matches behavior.
Rule priority follows list order
In rule mode, the core checks rules from top to bottom and applies the policy from the first matching rule. To always connect to status.example.org directly, place DOMAIN,status.example.org,DIRECT before the relevant RULE-SET. If it's lower in the list, a broader rule set may match first and the exception won't take effect. MATCH is an unconditional fallback and must come last. Changing its policy to a group affects every request that didn't match an earlier rule.
Validate the config: Check loading, traffic entry, and rule matches in order
- Check that the file loads. Use spaces for indentation and align keys at the same level. When changing an existing section such as
dns, merge the changes into that section instead of adding a second top-level key with the same name. If you have the mihomo CLI installed, runmihomo -t -f ./config.yamlfrom the directory containing the example. Passing validation confirms that the config can be read and checked; it doesn't mean the upstream server is reachable. - Confirm the request reaches the right core. Load the config and confirm the mode is set to rule. Select
DIRECTfor "Office Egress." Run the command below with7890explicitly specified so the system proxy setting or browser extensions don't affect the test. If the local port refuses the connection immediately, check whether it's listening before changing DNS. - Compare the match records for two destinations. Check the client's connection log and search for the domain in the core log if needed.
example.orgshould matchoffice-domainsand go direct through the "Office Egress" selection.example.comshould match the first domain-suffix rule directly. Both sites loading successfully doesn't prove the rules are correct: the finalMATCH,DIRECTrule can also send requests directly.
curl --noproxy "" --proxy http://127.0.0.1:7890 --max-time 10 -I https://example.org/
curl --noproxy "" --proxy http://127.0.0.1:7890 --max-time 10 -I https://example.com/
The commands above work in common Unix shells. In Windows PowerShell, call curl.exe and make sure the empty-string argument is passed to the program. Here, --noproxy "" clears any bypass list that may be set in environment variables, and --max-time 10 sets a 10-second total timeout for each request.
If the policy group matches correctly but the request fails only after switching to "Local SOCKS5," check whether a service is listening on 1080 and verify the upstream protocol and authentication settings. If the request still hits the fallback, check which config is active, whether the destination entered the core as a domain, and whether an earlier rule matched it. Change one thing at a time and retest the same domain to see whether the change worked.