Configuration Referenceconfig.yaml

mihomo Configuration Reference

Start by importing a config, enabling traffic capture, and verifying your connection with the Getting Started guide. Already connected and looking for where a specific key belongs, or trying to restore your rules after updating a subscription? Use this reference. The examples begin with a standalone, direct-connection baseline; replace or add each later section as you go. Don't append duplicate top-level keys.

YAML Structure and a Minimal Config

Understand mappings, sequences, and scalars

The top level of a config file is a mapping of keys to values. After the colon, a key can have a single value or a nested structure. Port numbers, mode names, and Boolean switches are scalars; dns is a nested mapping; proxies, proxy-groups, and rules are ordered sequences. Each proxy entry is itself a mapping, while each rule is usually a single string. Don't treat proxy properties as separate list items just because both proxies and rules use hyphens: the YAML may still parse, but it won't have the structure the core expects.

Indent with spaces, preferably two per level; never use tabs. Distinguish the space after a colon from colons inside quoted strings. If a value contains a colon followed by a space, quote the whole value so the parser doesn't mistake it for another key-value pair. A hash starts a comment when it isn't inside quotes and is preceded by separating whitespace. Quote values if a name contains a hash or starts with a zero. Keep ports as integers and switches as true or false; don't turn every value into a string.

A Standalone Direct-Connection Baseline

config.yaml
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

proxies: []
proxy-groups:
  - name: LOCAL
    type: select
    proxies:
      - DIRECT
rules:
  - MATCH,LOCAL

This baseline needs no subscription, geodata, or remote rules. Requests enter through the local mixed port, and the final rule sends them to LOCAL. Its only outbound is DIRECT. Direct connections still pass through the local core; they simply don't use a remote proxy. This lets you rule out remote services, credentials, and health-check URLs. If this config won't start, check the working directory, file permissions, and port availability first. A longer subscription will only make the fault harder to isolate.

The order of top-level keys doesn't determine startup order. Moving rules to the first line won't make rules initialize before proxies. Order matters within sequences: rules are matched from top to bottom, for example, and a manual selection group displays members in list order. References are resolved by name, not position, so LOCAL must match exactly wherever it appears in the rules and group definitions. Search for the name in your editor before renaming it. Changing only the displayed name without updating rules that reference it will break those references.

Empty Values, Duplicate Keys, and Error Line Numbers

proxies: [] explicitly defines an empty list. A bare proxies: with no entries is usually parsed as a null value. Null, an empty list, and an omitted key are not equivalent, especially when applying overrides. Don't add another rules: at the end of the file to append entries: some parsers reject duplicate keys, while some implementations may keep only one value. Add items under the existing key, or use the client's list-merge feature to append them explicitly.

Start troubleshooting with the first error. If a line reports a missing colon, the actual cause may be an unclosed quote on the previous line or incorrect indentation in an earlier block. Check a few lines on either side. Once the syntax parses, the core still validates proxy types, target names, and field values. Syntax highlighting doesn't guarantee the core can load the file, and a successful load doesn't mean traffic is being proxied. Keep a working baseline and change one field block at a time to tell structural mistakes apart from network-path problems.

If what you downloaded is a subscription URL, encoded text, or a client-specific share link, identify the appropriate import method before using it; changing the file extension won't make it a core config. Another common file contains only payload or a proxy list. That's a resource for other fields to reference, not a complete config. Check the file's top-level structure, then decide whether to add it as a client config, replace a subsection, or use it as a provider source. A config name shown in the UI isn't necessarily its path on disk, so make sure you're editing the file the client actually uses.

General Settings: Listener Ports and Mode

Set the entry point first, then choose the outbound path

Listener ports determine where applications send requests; mode determines how the core routes them. These are separate settings. The commonly used mixed-port accepts both HTTP proxy and SOCKS connections, making it a convenient single entry point for local apps. port provides an HTTP proxy listener, while socks-port provides a SOCKS listener. Enable them separately only when you need distinct entry points; assigning the same port to two listeners doesn't make them share it. If the client assigns ports for the core, trust the actual values shown in the UI and startup logs.

SettingPurposeFirst thing to check
mixed-portShared HTTP and SOCKS listenerMake sure the port is available and apps use the actual listener address
allow-lanWhether other devices on the local network can use the proxyLeave disabled for local use
modeChoose rule, global, or direct modeSwitch back to rule when troubleshooting rules
log-levelSet the log verbosityUse info day to day; increase verbosity briefly for troubleshooting
external-controllerControl API, not an application proxy listenerEnable only when needed and restrict access to trusted clients

For local apps, use the loopback address 127.0.0.1 and the mixed port. Don't enter the control API address as the system proxy: both may listen on local ports, but they serve different purposes. The control API can read runtime status and change settings, so don't expose it publicly. If only local access is needed, bind it to loopback and manage credentials as your client recommends. To let other devices use your proxy, check allow-lan, the listener address, firewall rules, and access controls. A connection from the local machine doesn't guarantee other devices on the network can connect.

Three Modes and Client State

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

rule routes traffic according to the rules in order. global uses the outbound selected by the global policy without applying custom routing rules one by one. direct sends requests handled by the core straight out. Switching to direct mode doesn't quit the client; the system proxy or virtual interface may still be capturing traffic. Before troubleshooting in global or direct mode, note the original mode and selection so you can restore them afterward. For a closer look at the differences, see the scenarios in Rule, Global, and Direct Modes Explained.

The mode in the config file may not match the current mode shown in the UI. A client may restore your previous selection at startup or generate an intermediate config for the core. If traffic still goes through global mode after editing the file, first check that the client loaded the file you changed, then check the mode selected in the UI. A temporary mode change in the UI may not be written back to the original file. To keep a setting across subscription updates and restarts, use the client's supported persistence mechanism rather than changing runtime state alone.

A Listening Port Doesn't Mean the System Is Capturing Traffic

The system proxy relies on apps honoring the system settings and usually works well for browsers and other proxy-aware programs. A virtual interface captures matching traffic through system routes; it also involves permissions, routing conflicts, and name resolution. Enabling both doesn't necessarily capture more traffic. If an app can't connect, start with one method at a time and record the entry point, destination, and result before testing the other. For more on how they differ, see TUN vs. System Proxy.

Setup and permissions vary by device, so don't assume the desktop system-proxy steps apply to a phone. For a first install, choose a platform package on the download page. If you'd like a graphical client, start with the recommended Clash Plus and check the options against what your client actually supports. If a port is occupied, don't terminate an unknown process; first check whether another client or an old core is running. When you change the port for a new config, also update any browser, terminal, or system settings still pointing to the old one.

To test a single app, point it at the mixed port manually before changing system-wide settings; it's easier to undo. This checks the full path through the core listener, rules, and outbound. Once it works, enable system-wide capture. If the results differ, narrow the issue to the app settings or system routing. When you temporarily increase log verbosity, retry one specific request and look for the inbound connection, destination, and outbound. Then restore the usual log level; a flood of parallel requests can bury the useful entries.

DNS: Upstream Resolvers, Domain Policies, and Enhanced Modes

Separate DNS lookups from connection routing

DNS resolution answers “what address does this name point to?” Connection rules answer “which outbound should this request use?” They affect each other, but they're not the same table. dns.enable enables the core's DNS module; by itself, it doesn't take over all DNS lookups on the system. Browser encrypted DNS, the system cache, and client-configured DNS hijacking can all change the request path. Before troubleshooting, find out which component makes the lookup, where it sends it, and whether the core sees a domain name or an already-resolved address.

dns:
  enable: true
  enhanced-mode: redir-host
  default-nameserver:
    - 1.1.1.1
  nameserver:
    - https://dns.google/dns-query
  nameserver-policy:
    '+.example.org':
      - 1.1.1.1

This example uses an encrypted upstream for general domains and sends example.org and its subdomains to a separate resolver. default-nameserver is used to resolve the hostnames of DNS upstreams themselves, so it typically contains IP-address resolvers. It's not a general-purpose fallback list for failed domain lookups. If the example's public resolvers aren't reachable from your network, substitute an accessible upstream and test again. To check whether a policy is taking effect, compare two requests: one within its scope and one outside it.

The client's built-in DNS is not equivalent to the system's “Preferred DNS” setting. To have an app query the core's DNS listener directly, configure dns.listen separately and point the app's queries to that address. Defining a listener alone doesn't redirect system queries to it. Avoid binding the listener to every interface, especially on shared networks. For troubleshooting, query the specified resolver directly first, then reproduce the request in the app. That keeps results from two different entry points from being mistaken for one test.

Choosing Between redir-host and fake-ip

redir-host returns real addresses and is a useful starting point for compatibility troubleshooting. fake-ip assigns synthetic addresses to handled domains. When the core later receives a connection to one of those addresses, it can use its mapping to recover the domain and apply rules. A synthetic address isn't the target server's public IP: don't copy it into a static hosts file or use it to check whether a remote server changed addresses. If an app bypasses the relevant capture path, or sends a synthetic address to another device without the mapping, resolution may succeed while the connection never reaches the target.

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - '+.local'
  nameserver:
    - 1.1.1.1

This block replaces the entire dns mapping above. Filters keep selected domains from receiving synthetic addresses, often because device discovery or a service requires real addresses. Filtering doesn't send a domain through a direct-connection rule, nor does it provide multicast DNS. If a local network service still won't open, check whether its name has a working local resolution method and whether the returned address routes to the correct subnet. When switching to real-address mode for comparison, remember that an app may cache the previous address; restart it and resolve the name again if needed.

Resolve Ordinary Domains and Proxy Hostnames Separately

If an outbound proxy's server is a hostname, the core must resolve it before connecting to the proxy. You can configure proxy-server-nameserver specifically for proxy hostnames. When using a rule-dependent DNS path, make sure proxy resolution has an entry point that doesn't depend on the proxy being connected already. Otherwise, you get a loop: the request needs the proxy, but the proxy needs the request to resolve its address. If all proxies time out while direct IP connections work and hostname-based proxies fail, check this dependency before rebuilding the whole group.

The same hostname returning multiple addresses isn't necessarily a problem; results can vary by region, cache, and record type. A more reliable test holds conditions constant: use the same client, capture method, and hostname, then record the query entry point, returned record types, and address the app ultimately connects to. If only IPv6 results fail, check that both the system and outbound path support IPv6. Disabling a DNS option may change the returned records, but it can't establish whether your network has a route for that address family.

Proxies: Protocols, Remote Addresses, and Providers

A proxy node is an outbound, not a local listener

proxies defines outbounds that other fields can reference. Each node's name is its config reference, type determines how the following fields are interpreted, and server and port specify the remote endpoint to connect to. The node's port is unrelated to the local mixed-port. Copying a client's local port into a node entry will usually fail to connect; pointing it back at itself can create a loop. Confirm the protocol, address, and port with your provider before editing the config. Don't infer field values from a node name's region or label.

proxies:
  - name: LAB-SOCKS
    type: socks5
    server: 127.0.0.1
    port: 1080
    udp: false

proxy-groups:
  - name: LAB
    type: select
    proxies:
      - LAB-SOCKS
      - DIRECT

rules:
  - MATCH,LAB

These fields replace the three matching top-level fields in the direct-connection baseline. They require a separate, controlled SOCKS5 service listening locally on 1080. If you don't have one, use the group's DIRECT outbound for comparison. First confirm that the service isn't another entry point to the current core and won't send traffic back to it. UDP is disabled on this node so the initial test focuses on TCP. If the app needs UDP, the protocol, node settings, server support, and capture method must all support it.

Node names can include non-English text, but short, stable, searchable names make troubleshooting easier. Duplicate node names, or a node and group with the same name, make references ambiguous and may cause the core to reject the config. If you define the same server twice with different protocols or ports, give each entry a distinct name instead of relying on list order. If subscription updates frequently change display names, avoid making lots of rules depend directly on a single node name. Route rules through a stable local group and update its members as needed.

Don't Reuse Fields Across Protocols

Each protocol has its own authentication fields. For example, SOCKS5 may use a username and password from the server settings, while a Shadowsocks node uses the cipher and password specified by its server. Don't copy one protocol's authentication block into another just to fill in fields. For nodes using TLS, also check the server's required name, transport, and related options. The server address and the name TLS uses to identify the peer aren't necessarily the same. If the handshake fails, verify the protocol and server details first; disabling certificate verification is not a long-term fix.

When an outbound can't connect, distinguish three kinds of failure. A proxy hostname resolution error usually appears before the handshake; an unreachable destination port usually results in a refusal or timeout; a protocol or authentication mismatch often fails after the connection is established. A response from the port only confirms that some service is listening, not that it accepts the protocol you're using. For nodes with an additional transport layer, check the relevant path or service identifier too; those options matter only when the server is configured to use them.

Use a Provider for a Replaceable Proxy List

proxy-providers:
  lab:
    type: file
    path: ./providers/lab.yaml

proxy-groups:
  - name: LAB
    type: select
    use:
      - lab
    proxies:
      - DIRECT

rules:
  - MATCH,LAB

A local file provider separates the group definition from the proxy source. First create providers/lab.yaml under the core's working directory; the file only needs the proxies block from the previous example. Keep the general fields in the main config, then use the group and rule block above. Relative paths are resolved from the core's working directory, which may not be the directory containing the YAML file open in the GUI. If you see a path error, check the directory the client actually passes to the core and make sure the user running it can read the file.

Remote provider content must also match the core's expected format. Not every share link can be used as a proxy-list URL. If an update fails, first determine whether fetching the content failed or whether the downloaded content couldn't be parsed; the server may have returned a regular web page. When sharing diagnostics, keep the error type and field structure but remove subscription URLs, credentials, and unrelated personal IP addresses from connection logs. For definitions, see the subscription, proxy, and proxy group entries in the Glossary.

Proxy Groups: Selection, Health Checks, and Failover

Point rules to stable group names

Proxy groups separate “which requests go here” from “which outbound is selected right now.” Rules reference a group name, and the group references proxies, other groups, or built-in outbounds. Change the group's members to switch nodes without rewriting every site rule. A straightforward setup has one group for a type of traffic and one group of candidate outbounds. If you add an automatic-selection layer, keep references one-way. For example, a manual group can reference an automatic group, but the automatic group must not reference the manual group in return, or it won't resolve to a final outbound.

select is a manual selection group, useful for first-time testing, a fixed outbound, and keeping a backup available. The list order makes members easier to browse, but the first item isn't necessarily selected at every startup: the client may restore a previous selection. When troubleshooting, explicitly select a member in the group UI, then confirm in the connection log which one handled the request. Adding DIRECT to the group doesn't make it switch to direct automatically; it just adds another selectable outbound.

proxy-groups:
  - name: WEB
    type: select
    proxies:
      - LAB-SOCKS
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.org,WEB
  - MATCH,DIRECT

This block depends on the LAB-SOCKS node defined in the previous section. It sends only the specified domains to the manual group; all other requests go out directly. After switching members, test with a new connection rather than expecting existing sessions to migrate. Browsers may reuse connections, and apps may keep long-lived ones open. If the UI shows a different node selected but behavior hasn't changed, close the test app's existing sessions and check the rule match and outbound for the new connection. This distinguishes an unsaved selection from a connection that hasn't been recreated.

What an Automatic Group's Health Check Tells You

proxy-groups:
  - name: AUTO
    type: url-test
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 80
    proxies:
      - LAB-SOCKS
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.org,AUTO
  - MATCH,DIRECT

url-test compares candidate outbounds using a probe URL and works well for traffic where automatic selection is acceptable. interval is in seconds and tolerance is in milliseconds; the latter helps avoid switching over small latency differences. The UI shows one or more probes to the specified URL, not latency to your actual service or available bandwidth. This example includes a direct outbound for testing. If the traffic must use a proxy, don't include direct as an automatic candidate; it may be selected simply because the probe is faster.

fallback picks an available member according to priority rather than choosing the one with the lowest latency. To keep a preferred outbound with backups, list the usual choice first, then the alternatives, and configure a probe URL all of them can reach reliably. Both automatic group types depend on the probe target, connection timeout, and scheduling interval. If only the probe URL is unreachable while the real service works, the group's availability checks won't reflect your actual needs. Choose a probe URL that's both reliably reachable on the target network and able to confirm that a connection was established.

Member Sources and Recovery Behavior

proxies explicitly references defined nodes or other selectable outbounds, while use imports members from a provider. When subscription updates change node names, use is often easier than hard-coding a long list of names into a group. You can combine both sources to keep fixed local backups alongside changing remote candidates. If a group appears by name but has no selectable proxies, check that the provider loaded, that its list contains proxies, and that the client isn't applying additional filters. Simply refreshing the health-check results won't help.

If a fixed outbound is unreliable, decide which fallback paths are allowed before choosing a group type. A manual group is usually preferable to frequent latency comparisons when you need to preserve login sessions or a source IP. Use failover when you want to switch only after the first choice becomes unavailable. Don't let a group silently turn “use the backup proxy” into “connect directly” for unmatched traffic. Keep a manual comparison group for testing new nodes, and add them to automatic selection only after you verify connections, resolution, and app requests. That also gives you a clear choice to revert to if something goes wrong.

Check provider health checks separately from the group's own test settings. A node marked available by its provider may still be unable to reach a particular group's probe URL. Conversely, one temporary error doesn't mean the node should be removed from every group. Retest using the same target and transport path, then decide whether to fix the candidate list, probe settings, or actual outbound. The reasoning behind a decision is more useful than a single latency reading.

Rule Syntax: Match Order, Targets, and Rule Sets

The first matching rule determines the route

In rule mode, the core checks rules from top to bottom and uses the target of the first match. It doesn't keep searching for a more specific rule. Most rules consist of a type, a match value, and a target, separated by English commas. MATCH has no match value; it takes only an outbound target. Put specific exceptions before broad categories and the catch-all last. Don't sort rules alphabetically or append personal rules after the catch-all: they'll be present in the file but will never run.

rules:
  - DOMAIN,api.example.org,DIRECT
  - DOMAIN-SUFFIX,example.org,LOCAL
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - MATCH,DIRECT

Replace the direct-connection baseline's rule list with this block, keeping its LOCAL group. The first rule matches only the exact domain; the second covers the base domain and its subdomains. Even though both targets ultimately connect directly here, connection logs can distinguish the exact match to DIRECT from the suffix match to LOCAL. Swap the two lines and the suffix rule will catch the exact domain first. Using simple targets for this comparison lets you verify rule order without remote network variables.

Domain rules take a hostname, not a full URL. Don't include the protocol, path, port, or query parameters; the rule matches the hostname the core sees, not the entire browser address bar. Redirects may send a request to a different destination, and a page may load other domains asynchronously. The result looks like one page, but the logs show multiple connections. Test one known hostname at a time and check the destination and matched rule in the logs. When copying rules, watch for full-width commas and invisible spaces.

IP Rules May Trigger DNS Resolution

IP-CIDR matches IPv4 address ranges; use IP-CIDR6 for IPv6. GEOIP matches an address against geolocation data and depends on the relevant data being available in the current working environment. None of these are domain-suffix rules. For a domain target, an IP rule may need to resolve the name before it can match. Some IP rules support no-resolve at the end to prevent an additional lookup for that rule; it doesn't discard an address already resolved for the target. If no matchable address is available, don't assume the IP rule will match. Make sure later rules still provide a sensible route.

If the same kind of traffic sometimes hits a domain rule and sometimes an IP rule, check whether the app consistently passes its destination in the same form. Some apps pass a hostname; others connect to a cached IP directly. A domain may resolve to multiple addresses, and geolocation matches can vary with the actual address or data. Don't use geolocation rules as a substitute for a list of business-critical domains. Define explicit exceptions for those services first, then use IP ranges or geolocation categories for the rest. Check logs to see the destination information available when a rule matches.

Declare the Type of External Rule Providers

rule-providers:
  local-domains:
    type: file
    behavior: domain
    format: yaml
    path: ./rules/local-domains.yaml

rules:
  - RULE-SET,local-domains,LOCAL
  - MATCH,DIRECT

Then add a payload list to rules/local-domains.yaml in the core's working directory:

payload:
  - '+.example.net'

domain rule providers contain domain expressions; ipcidr is for IP ranges; classical supports classic rules with match types. Make sure the declared behavior matches the file contents. Don’t assign an outbound to each entry in the provider file; the main config’s RULE-SET rule determines where matching traffic goes. The position of RULE-SET in the rules list still affects priority. To make a custom exception take precedence over a rule set, place it before the provider reference rather than changing the order in the resource file.

If updating a rule resource causes widespread routing changes, compare its type, the match scope before and after the update, and its priority in the main rules. Temporarily test a local copy in the working directory to distinguish a failed download, invalid format, and a genuinely broader match. To add a custom routing rule, insert the narrowest effective condition near the top, then test one request that should match and one that shouldn't. Only when both behave as expected have you verified the boundary, rather than merely confirming that one request worked.

Overrides and Merging: From Subscription Files to the Effective Config

Find the right layer to change

GUI clients often keep remote subscriptions, personal overrides, UI selections, and the final config passed to the core in separate places. Editing a subscription cache may work for now, but the next update can overwrite it. Changes to a temporary output may disappear on reload. To preserve personal rules across updates, check whether the client supports an override, extension config, or script hook, and confirm the order in which they're applied. The core reads the processed result; it won't merge files just because one of them contains the word “override.”

Choose a merge strategy based on the value type. Ports and modes are scalars, so usually only one final value remains. DNS is a mapping: a tool may change one nested key or replace the whole block. Rules and proxy groups are sequences that a tool may replace entirely or support prepending, appending, or name-based handling. YAML itself doesn't specify how a client combines sequences from two configs. Test the tool with two rules and inspect their order in the final file before using it. Don't assume override fields work the same way across different clients.

Document each override alongside its purpose. If you only need to route one domain to a local group, don't also copy ports, logging settings, and the entire proxy list; unrelated fields can block upstream changes later. Conversely, if you're replacing the entire DNS block, list the upstream resolvers and policies you need to keep so you don't accidentally remove the dedicated resolver used for proxy hostnames. Shorter overrides are easier to review, but don't omit fields required for a complete feature.

Verify Merge Behavior with Inputs and Outputs

# Existing rules in the remote config
rules:
  - DOMAIN-SUFFIX,example.org,LOCAL
  - MATCH,DIRECT
# Effective rules after adding a prepended exception
rules:
  - DOMAIN,api.example.org,DIRECT
  - DOMAIN-SUFFIX,example.org,LOCAL
  - MATCH,DIRECT

These are the input and expected output, not two configs to enable at the same time. The key is that the exception comes before the suffix rule and the original catch-all stays at the end. If the client only supports replacing the rule list, use the complete output list. If it supports prepended entries, add only the first exception through the appropriate hook. Cross-check the resulting rules against connection logs, and confirm that the output still includes a definition for LOCAL. If you change a group name, also check that the override replaces the original group instead of appending a second group with the same name.

Inline JSON-style lists and multiline lists can express the same values, but expanded lists make it easier to compare where new items were added. Don't let a tool sort rules for readability: sorting mapping keys usually affects only presentation, but sorting a sequence changes its meaning. Before removing a field, distinguish inheriting the original value from explicitly clearing it. Omitting a key often means it isn't part of the override; an empty list may replace the original with zero items, depending on the tool. A blank value after a colon may leave the core with an unintended null.

Reusing Anchors and Regression Testing After Updates

YAML anchors and aliases let you reuse structures within one file; they're not a way to import content across configs. Whether a mapping merge works depends on the client's preprocessor and parser. In particular, don't assume that sequences will be merged item by item. If you plan to use the file in another client, prefer a fully expanded version that can be read on its own. If logs say an alias can't be found, check whether preprocessing moved or removed its anchor before changing the rules themselves.

Before updating a subscription, keep a local copy of the last known working config and save personal overrides separately. After the update, check that node names and target groups are still resolvable, that lists haven't become empty, and that the catch-all rule, DNS, and mode are as expected. If regression testing fails, disable the override and try the original subscription, then enable the override separately for comparison. If both fail, merging may not be the cause. If only the override fails, restore it one block at a time to find the first one that changes behavior.

When saving a working config for comparison, don't post the whole file with credentials to a public discussion. Focus on changed paths, ordering, and references. Share only the necessary snippets, replacing names consistently in both definitions and references. That preserves the structure so others can tell whether the problem is an ordering issue, a duplicate name, or a config that was never reloaded after generation.

Validation and Troubleshooting: From Config Loading to Connection Logs

Validate the config before checking the listener

You can test a config with the command-line core before replacing the one that's running. Switch to a test directory, save the effective config as config.yaml, and create any required local provider or rule-resource directories there. The commands below assume mihomo is on your executable search path and curl is available directly. Run the first command on its own. Once it succeeds, start the second command in one terminal and make a request from another.

mihomo -t -d . -f ./config.yaml
mihomo -d . -f ./config.yaml
curl --noproxy "" --proxy http://127.0.0.1:7890 https://example.org/

Don't let the GUI client and this test core compete for the same port. Close the process using it before starting, or configure a different available port and update the number in the command. In some environments, curl is a terminal alias; use the platform's actual executable if needed. The explicit proxy option ensures this request uses the specified entry point, reducing interference from system proxy settings and proxy environment variables. A successful test confirms that this entry point accepted one request, not that every app uses the same settings.

If config testing fails, check whether the file was found, whether it has syntax errors, and whether its dependencies are readable. If the test passes but startup fails, look at the runtime environment: port conflicts, insufficient permissions, or a working directory that differs from the test setup. Troubleshoot the connection path only after the core starts. One complete error is enough at this stage. Repeated errors of the same type often come from an app retrying; they don't mean a dozen separate parts of the config are broken.

Narrow Down the Problem with Connection Evidence

SymptomCheck firstNext step
Connection to the proxy port is refusedWhether the core is listening on the expected address and portCompare startup logs with app settings
The app sends requests, but the core logs nothingWhether the app is actually using the proxy entry pointTest explicit proxy settings and system capture separately
A connection is logged, but it matches the wrong targetMode, rule order, and actual destinationCheck the group's current selection and effective config
The request times out after matching a proxyProxy hostname resolution, connection, and remote handshakeSwitch to one member at a time, retry, and note where it fails

If there are no connection logs, don't start by editing DNS policies or adding proxy parameters. First compare with a request that explicitly uses the proxy entry point. If that request is logged, the app may not be honoring system proxy settings, or the capture mechanism may not be receiving traffic from that process. Check browsers and terminals separately: a browser may use a proxy extension, while a terminal may read environment variables or its own tool settings. For detailed steps, see Troubleshooting System Proxy Issues in Browsers and Terminals.

When a request is logged but routed incorrectly, note four things: the mode, target name, matched rule, and final outbound. A rule pointing to an automatic group doesn't guarantee that it selects the proxy you expect; it may choose a direct outbound that's allowed as a candidate. If only an old session behaves unexpectedly, close it and reconnect. If a new session reproduces the issue, check whether runtime settings override the file. Use the log for that connection, not a screenshot from an earlier test.

Keep Validation Repeatable

After each change, test at least three cases: a target that should go direct, one that should match a custom rule, and one that should fall through to the catch-all. Start with a working minimal config, then restore proxies, groups, DNS, and external resources one at a time. If something fails, you'll know which block introduced the problem. For intermittent issues, record the network environment and entry point. System capture and upstream DNS may change when switching from wired to Wi-Fi or desktop to phone, so the results aren't directly comparable under different conditions.

If the config fails on first import, return to the Getting Started guide and recheck import, mode, and connection in that order. If you've isolated a field, record expected behavior, actual behavior, and the smallest config snippet that reproduces it. Before returning to your regular setup, restore any temporary verbose logging, test ports, and capture settings. Then the next time a change breaks connectivity, you can start from the last known working config and a repeatable request instead of guessing from scratch.

Finally, compare behavior after a reload and after a restart. A reload confirms the core accepted the file changes; a restart can reveal whether the client restores an old selection, regenerates the config, or fetches the subscription at startup. If the results differ, note which stage changed and revisit Overrides & Merging. Long-term maintenance benefits less from more debug output than from knowing which file you can roll back to, which request you can reproduce, and which rule should match.