REFERENCE / CONFIG.YAML / MIHOMO
Clash YAML Configuration Guide
Ports, DNS, proxy options, proxy groups, rules, and config merging—organized in the order runtime configuration is built.
This guide is for users who have already installed the client and want to understand or edit its configuration. For your first subscription import, system proxy setup, and connection test, follow the quick start guide first, then return here to review individual fields. Find installers on the Clash download page. Use its list to choose a desktop or mobile client; start with Clash Plus, or follow the options and interface for the core actually used by Clash Nyanpasu.
SECTION 01 / DOCUMENT MODEL
YAML Structure and Configuration Sources
Mappings, Lists, and Indentation
A Clash configuration is not a line-by-line script. It is a structured document describing listeners, name resolution, and routing decisions. Top-level fields control global behavior, nested mappings hold related options, and lists define ordered members. Start by checking indentation, then read the field names. A scalar after a colon belongs to that field; indented fields on the next lines belong to its parent mapping. Items beginning with a hyphen belong to a list and cannot be arbitrarily rewritten as sibling mappings.
Use two spaces for indentation and never tabs. Fields at the same level must line up, but indentation depth does not indicate priority. For example, dns.enable has the intended effect only under dns. Move enable to the top level and the file may still parse, but it will no longer configure DNS. Troubleshooting should go beyond syntax checks: confirm each field is in a location the core recognizes.
mixed-port: 7890
mode: rule
dns:
enable: true
enhanced-mode: fake-ip
nameserver:
- https://dns.alidns.com/dns-query
proxies: []
proxy-groups:
- name: PROXY
type: select
proxies:
- DIRECT
rules:
- MATCH,PROXY
This example illustrates the structure only; its proxy group contains direct connections and provides no remote proxy access. proxies: [] is an empty list, not a string or a missing field. Use true and false for booleans, and integers for ports. Quote strings containing a hash, a colon followed by a space, an asterisk, or other special characters. Save passwords as strings even when they look numeric, to prevent the parser from converting their type.
Profiles, Subscriptions, and Runtime Configuration
In the client, a Profile is a configuration entry linked to a local file or remote subscription. A downloaded subscription YAML usually includes proxy entries, proxy groups, and rules, but the client may also add listener ports, system integration options, or overrides. The core reads the runtime configuration produced after these inputs are processed. Editing a subscription cache, the original file, or override content can have very different effects.
Changes made directly to a subscription cache may be replaced when the remote subscription updates. Keep subscription-managed content separate from settings you want to retain. General ports and log levels are often best managed by the client; personal rules belong in an override layer that can be reapplied. Merge behavior depends on the client, so a filename alone does not tell you where content came from. To compare changes, save both the original subscription and the final output instead of relying only on the tab currently open in an editor.
File Editing Basics
Do not define the same key more than once in a mapping. Two dns sections will not reliably merge automatically; parsers may report an error or keep only one. To add resolvers, update the existing list instead of adding another field with the same name at the end of the file. Keep the rules list to one clear source as well, so subscriptions and local edits do not create separate top-level rules sections.
Save files as UTF-8 and use standard ASCII colons and hyphens. Chinese punctuation may be fine in explanatory text, but it cannot replace YAML syntax characters. Comments start with a hash and are not runtime fields; a hash inside quotes is part of the string. After copying an example, check whitespace first, then review the referenced content. Visual alignment on a web page is no substitute for the actual spaces in your editor.
The configuration file path depends on the operating system, installation method, and client settings, so this guide does not prescribe a universal user directory. Find the location through the client's configuration directory shortcut or logs. If you use multiple configurations, give each Profile a descriptive name and note which one is active. For more on local files, remote subscriptions, and switching configurations, see Profiles and multi-configuration management.
SECTION 02 / LISTENERS AND MODE
Listener Ports and Operating Modes
Proxy Protocols and Listener Addresses
Proxy ports accept connections from applications and pass them to the core. port provides an HTTP proxy, socks-port provides a SOCKS proxy, and mixed-port accepts both HTTP and SOCKS requests on the same port. A mixed port is usually a straightforward choice on desktop, but check which field the client actually writes. Putting a web server address in a proxy port field, or treating the control interface as a proxy listener, will cause a protocol mismatch.
| Field | Purpose | What to check |
|---|---|---|
mixed-port | Shared HTTP and SOCKS listener | Check for conflicts with other listening services |
allow-lan | Control LAN access to the proxy listener | Check the bind address and firewall too |
bind-address | Set the proxy listener address | For local use, prefer limiting it to the loopback address |
mode | Choose rule, global, or direct mode | Use the runtime configuration and current interface value |
log-level | Set the log verbosity | Restore the normal level after troubleshooting |
external-controller | Provide the core control interface | Not an application proxy port |
mixed-port: 7890
allow-lan: false
bind-address: 127.0.0.1
mode: rule
log-level: info
external-controller: 127.0.0.1:9090
This configuration restricts the proxy and control listeners to the local machine. To let other devices connect, consider the bind address, allow-lan, the system firewall, and access controls together; changing one switch is not enough. Listening on all network interfaces makes the service reachable through more of them. Never expose the control interface directly to the public internet. If remote administration is necessary, configure authentication and restrict network access.
Rule, Global, and Direct Modes
mode: rule selects an egress route from the rules list, making it suitable for routing by domain, address, or rule set. mode: global applies a global policy to connections that enter the core; it does not mean every application on the system is being intercepted. mode: direct sends connections entering the core directly to their destinations. They still pass through the proxy listener, so this does not shut down the client.
Mode and system proxy settings operate at different layers. Mode determines how connections are routed after they enter the core; the system proxy setting determines whether apps that honor system settings send requests to that listener. Some programs use their own proxy settings, while others ignore the system proxy. If an app behaves differently, first check whether its traffic reaches the listener, then inspect the rules. A working browser does not prove other programs follow the same route.
Port Changes and Process Boundaries
When you change the mixed port, update the proxy address in applications too. The client can manage system proxy settings, but browser extensions, terminal environment variables, and developer tools with fixed ports may not follow suit. A common symptom is a client that runs normally while the terminal still connects to the old port. Check the actual values of HTTP_PROXY, HTTPS_PROXY, and ALL_PROXY, along with any proxy settings saved separately in individual apps.
A port conflict means the specified local address and port are already in use, or an old core process has not exited. Stop duplicate clients first and identify what holds the port; do not change every listener to a random value. If the logs point to a permissions error, check the process permissions or whether the system has reserved the port. Port numbers do not determine connection quality—the choice should reflect app consistency and local availability.
For everyday use, keep the log level at info. Switch briefly to debug when you need to trace rule matching. Detailed logs may include destinations, so remove subscription URLs, credentials, and personal browsing records before sharing them. For initial port and system proxy checks, see First Install and Initial Setup; there is no need to replace an entire subscription to fix a local listener issue.
SECTION 03 / NAME RESOLUTION
DNS Resolution and Fake-IP
What DNS Fields Do
DNS configuration converts domain names into information used for connections and rule matching. dns.enable enables the core's DNS feature, listen sets the local address that receives queries, and nameserver lists regular upstream resolvers. Enabling DNS does not automatically route every system query through the core. System DNS settings, an app's built-in encrypted resolver, and TUN hijacking settings can all affect whether queries follow this path.
default-nameserver is commonly used to resolve the hostnames of DNS upstreams so the dependency chain can start. For example, an upstream specified by an HTTPS hostname must be resolved first. This is not a universal field that forces all queries to use a preferred resolver. Another easily confused field, proxy-server-nameserver, resolves proxy server hostnames and can separate the resolution path needed to establish a proxy connection.
dns:
enable: true
listen: 127.0.0.1:1053
enhanced-mode: fake-ip
fake-ip-range: 198.18.0.1/16
default-nameserver:
- 223.5.5.5
nameserver:
- https://dns.alidns.com/dns-query
fake-ip-filter:
- "*.lan"
- localhost
This snippet shows a local DNS service without system-wide traffic interception. Choose upstream addresses based on what is reachable from your network; encrypted transport does not guarantee an address will work on every network. If you change the local listener port, the operating system or forwarding service must also be able to send queries to that port. Standard system DNS settings often accept only an address, not a custom port.
Fake-IP and Real Address Resolution
Fake-IP mode assigns a domain a mapped address that the core can recognize, preserving the domain name through that mapping. The address range in the example is for internal mapping; it is not a real website egress address or a value to use for a remote server. This mode can associate requests with domain names more reliably as they enter the core, but only if the app and system query paths pass through the same core instance.
redir-host mode returns actual DNS results and uses a different processing path from Fake-IP. Some local services that rely on real addresses may work better with it, but switching modes is not a universal fix for DNS problems. First determine whether queries are failing, mappings are invalid, or the app is bypassing the core. After switching, account for existing DNS caches in the system and apps; cached results may continue to affect new connections.
fake-ip-filter excludes specified domains from virtual mapping, which can help with local domains or service discovery when compatibility requires it. Overly broad filters weaken domain mapping, so start with the specific domains causing problems rather than adding every common suffix. Check the current core documentation for the exact matching semantics; do not assume a regular domain list accepts arbitrary rule formats.
Resolution Paths and Routing Loops
If DNS requests themselves need to follow routing rules, check how upstream connections leave the core. respect-rules makes DNS connections follow routing rules, but the resolution path for proxy server hostnames must also be clear. Otherwise, you can create a circular dependency: the proxy needs DNS to connect, while DNS needs the proxy to resolve. Before adding this field, map out the order of upstream resolution, proxy handshake, and destination access.
nameserver-policy assigns resolvers based on domain conditions. It controls which DNS path is used; it does not automatically create access rules for the corresponding sites. DNS routing and connection routing happen in separate stages: the first selects a resolver, the second selects an egress route. A domain using a particular resolver does not mean its connection uses the same route. Check both configurations when you need consistent behavior.
When troubleshooting, keep one reachable upstream and confirm basic queries before adding policies and filters one at a time. If LAN names fail to resolve, check whether the router or local DNS server should handle them instead of sending all queries to a public resolver. If browser and command-line results differ, clear their caches separately and check for app-specific resolver settings. Change DNS separately from ports and modes so log and behavior differences have a clear cause.
SECTION 04 / OUTBOUND DEFINITIONS
Proxy Fields and Remote Providers
Separate Common Fields from Protocol-Specific Fields
proxies describes selectable outbound proxies. A complete entry usually needs a name, protocol type, server address, and port, plus protocol-specific options such as a password, user ID, or transport settings. The name is an internal reference and must match the member referenced by a proxy group; it cannot be substituted for the server address. To avoid mistaking instructional data for a working service, this section shows protocol field snippets only, not complete connection entries.
type determines how the core interprets the parameters that follow. Different protocols may share server and port, but their authentication fields are not interchangeable. Some types need a password, others a user ID, and some also require an encryption method. Leaving fields from another protocol in place may cause them to be ignored or make the configuration fail to load.
# Shadowsocks fields only; not a complete proxy entry
type: ss
server: proxy.example.com
port: 443
cipher: aes-128-gcm
password: "your-password"
udp: true
The example domain and password are for instructional use only. For real use, the service provider must supply matching protocol parameters; do not infer the protocol from the port. 443 is one commonly used service port, but it does not automatically mean TLS is enabled. udp: true enables the relevant capability, subject to the protocol, server implementation, and full network path; it does not guarantee that every kind of UDP traffic from an app will work.
TLS and Transport Options
For protocols that support TLS, the server address and certificate verification name can differ. servername generally specifies the server name used in the handshake and should match the service configuration and certificate. skip-cert-verify controls certificate verification and should not be a routine fix for connection failures. Certificate errors may stem from a wrong hostname, an incorrect system clock, or an incomplete server certificate chain; bypassing verification hides these problems.
WebSocket, HTTP, and other transport settings usually belong in nested fields supported by the protocol. Paths, request headers, and handshake names each serve a different purpose; do not swap them just because they look like domains. If the service provider supplies raw YAML, preserve the protocol block's structure first, then check whether the core supports its options. Subscription converters may omit extended fields, so compare the structures if the original link works but the converted result does not.
| Layer | Common fields | Key question |
|---|---|---|
| Connection address | server、port | Are the hostname, address, and port correct? |
| Protocol authentication | type、password | Do the protocol and server use matching authentication settings? |
| Secure transport | tls、servername | Do the handshake name and certificate match? |
| Application transport | network、ws-opts | Does the protocol support it, and do the path and headers match? |
What proxy-providers Are For
proxy-providers manages remote proxy entries as a separate resource, and proxy groups reference a provider with use. This is not the same as a full Profile subscription: a full configuration may also include DNS, rules, and groups, while a proxy provider's payload must follow its own format. Putting a full subscription URL in a provider field does not guarantee the core can read it as a proxy collection.
proxy-providers:
REMOTE:
type: http
url: "https://example.com/proxies.yaml"
path: ./providers/remote.yaml
interval: 86400
proxy-groups:
- name: PROXY
type: select
use:
- REMOTE
REMOTE here is a provider identifier, not a single proxy entry. The example URL does not provide a working configuration; replace it with a resource you are authorized to access and that uses a compatible format. interval is measured in seconds and sets how often the resource is updated; it differs from a proxy group's health-check interval. path is the cache location, subject to the core's working directory and path security restrictions. Desktop clients may manage these files separately.
If a provider download fails, first check whether the URL is unreachable, authentication has expired, the response is a web page, or the YAML payload has the wrong structure. Cached data may remain in use, so seeing members in the interface does not mean the update succeeded. Remote subscription URLs often contain access credentials; never include them in screenshots or public logs. For import format differences and the full process, see Importing Subscription Links and Understanding Formats.
SECTION 05 / POLICY GRAPH
Proxy Group Fields and References
Proxy Groups Are Not Traffic Interception
proxy-groups organizes available egress options into decision units that other fields can reference. A rule can target a proxy group, which can then point to proxies, built-in actions, or other groups where references are allowed. Groups determine how to choose the next hop for a connection that reaches them; they do not make an app start using a proxy. If an app's requests never enter the core, even a well-designed group has no effect.
Give each group a unique, stable name and set its selection method with type. select offers manual selection for cases where you need explicit control over the current route. url-test selects members based on probe results, fallback favors keeping an available route according to member order, and load-balance distributes connections according to its strategy. Do not infer the selection logic from the order shown in the interface.
proxy-groups:
- name: PROXY
type: select
proxies:
- DIRECT
- REJECT
rules:
- DOMAIN-SUFFIX,example.com,PROXY
- MATCH,DIRECT
This snippet illustrates references. DIRECT means direct access; REJECT means reject. Selecting the latter rejects requests routed to that group. Both are built-in core targets and do not need to be defined again under proxies. You can add valid existing egress options to a real configuration, but listing an undefined name will not make the core create it automatically.
Member Sources and Health Checks
proxies defines an explicit member list, while use references a proxy provider. Explicit lists suit a fixed configuration; providers suit resource collections that update independently. When combining them, check how the current core handles group members and confirm that the provider has loaded. A group appearing in the interface does not guarantee it has selectable members: an empty provider, overly restrictive filters, or a resource loading failure can leave it empty.
Automatic selection types usually need probe parameters such as url and interval. Choose a stable, lightweight HTTP endpoint that is reachable through the route being tested. Probe results reflect requests to that endpoint only; they do not prove that every website, authentication flow, or app protocol will work. If network policies block the test endpoint, otherwise usable members may be marked unavailable.
Options such as tolerance help reduce frequent switching; whether they apply depends on the group type and core version. Do not shorten probe intervals just to make the interface change faster. Frequent probes add requests and can cause selection to fluctuate on an unstable network. Before tuning parameters, decide whether you need automatic best-route selection, a standby route, or connection distribution. Choosing the right group type matters more than fine-tuning its options.
Layered Groups and Circular References
Layered proxy groups can separate user choice from rule categories. For example, rules can target a stable group for a service, which then references a shared manual selection group. This avoids editing rules individually when remote resources change. More layers also make troubleshooting harder, so give each one a clear purpose and avoid stacking groups that merely forward traffic in the same way.
Groups must not reference each other in a loop. If Group A references Group B and Group B points back to Group A, the egress path cannot terminate. In a large configuration, a loop can also form through a third group even without a direct pair of references. Trace each path from its rule target until it reaches a real proxy or built-in action. Every path needs an endpoint and must not revisit a group it has already passed through.
| Type | How it selects | What to check |
|---|---|---|
select | Select a member manually | Is the current selection valid, and are member references correct? |
url-test | Select based on probe results | Are the probe URL and switching conditions appropriate? |
fallback | Select an available member by order | Does member order reflect the intended fallback sequence? |
load-balance | Distribute connections according to the configured strategy | Does the app need a stable egress route? |
For services that need to maintain a login session, distributing new connections may change the egress address and trigger extra verification. Choose a stable route based on the app's needs instead of treating load balancing as a default optimization. Existing connections usually do not move when the group selection changes; new connections use the updated decision. To verify a change, close the app's existing connections and retry. Check rule matches and the final egress path so an old session is not mistaken for a configuration failure.
SECTION 06 / FIRST MATCH
Rule Syntax and Match Order
First Match and the Catch-All Rule
In rule mode, the core checks rules from top to bottom. Once a rule matches, it uses that rule's target and does not keep searching for a more specific match. Priority comes from position, not the rule name or domain length. A common layout puts specific exceptions first, general categories in the middle, and the catch-all rule last.
Most rules use a comma-separated format: type, condition, and target. MATCH has no match condition and directly specifies how to handle all remaining connections. Rules after it usually never get a chance to run. If a rule does not seem to work, look for an earlier matching rule instead of adding the same rule again.
rules:
- DOMAIN,example.com,DIRECT
- DOMAIN-SUFFIX,github.com,PROXY
- IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
- IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
- GEOIP,CN,DIRECT
- MATCH,PROXY
This rule requires an existing proxy group named PROXY. The LAN address example is not a complete list of all private network ranges; add entries that match your network. GEOIP depends on the relevant geolocation data being available, and its classifications do not necessarily reflect where a service operator is based. For specific routing needs, prefer clear domain or address rules over geographic assumptions.
Domain Rules vs. IP Rules
DOMAIN matches an exact hostname, making it useful for a single-host exception. DOMAIN-SUFFIX matches a domain and its subdomains, which suits an entire service domain. DOMAIN-KEYWORD matches a keyword and can cover more than intended, so use it with care. Rule conditions generally do not include a URL scheme, path, or port. Pasting a full web address into a domain condition does not create path-based matching.
IP-CIDR and IP-CIDR6 match destination address ranges. Some address rules may trigger DNS resolution for requests originally made to a domain. no-resolve prevents that rule from actively triggering resolution; it does not mean the entire connection path never uses DNS. If the connection already has a destination IP, address matching can still work. If only a hostname is available and no address has been resolved, the rule may not match.
A website may use multiple domains; static assets, login, and API requests do not necessarily share a suffix. A rule for the homepage domain alone cannot guarantee that every part of the site follows the same route. Troubleshoot the specific failed request rather than stopping when the page loads. For apps that connect directly to an IP, domain rules may not have enough information; choose a policy based on the actual connection destination.
Rule Providers and Payload Formats
rule-providers manages independently updated rule collections, referenced from the main rules list with RULE-SET. A provider stores match conditions; the main rules list specifies where to apply them and which target to use. A collection will not participate in matching just because it downloaded successfully—it must also be referenced in the main rules list. A reference placed after the catch-all rule will not have the intended effect either.
rule-providers:
LOCAL-DOMAINS:
type: inline
behavior: domain
payload:
- "+.example.com"
rules:
- RULE-SET,LOCAL-DOMAINS,DIRECT
- MATCH,PROXY
This example uses an inline domain collection and does not depend on an external file. The payload for behavior: domain contains domain conditions; do not put full rule lines with policy targets in it. The payload formats for ipcidr and classical differ, so remote resources must match the declared behavior. When changing a provider's type or format, check its contents too instead of only renaming a field.
When organizing rules, record the reason for each locally added entry and periodically remove duplicates that are already covered by earlier rules. Avoid appending rules out of order with multiple override scripts; it makes the final order hard to understand. For a detailed guide to rule types, ordering, and match analysis, see Clash Custom Rule Syntax and Priority. The next section explains how to preserve personal rules across subscription updates.
SECTION 07 / CONFIGURATION PIPELINE
Overrides, Merging, and Update Boundaries
Separate Client Processing from Core Fields
An override is a client-side mechanism for applying changes to an original configuration; it is not a top-level field supported by every YAML file. Clash Nyanpasu may generate configurations through client-managed settings, config merging, and scripts. Override interfaces, processing order, and supported syntax vary between clients. Do not pass a client's extended configuration to the core as if it were plain mihomo configuration.
To understand overrides, separate input, transformation, and output. Inputs include a subscription or local Profile; transformations include field overrides, list operations, or script changes; the output is the runtime configuration read by the core. When troubleshooting, identify which layer contains the change and inspect the final output. Seeing a field in the override editor does not prove it was not overwritten by a later step.
# For override interfaces that support merging ordinary fields only
mode: rule
log-level: info
dns:
enable: true
enhanced-mode: fake-ip
This snippet shows the field value you want to preserve, but clients may use different merge algorithms. Some recursively merge mappings; others replace the entire object. If the whole dns object is replaced, the upstream list, filters, and policies from the subscription may disappear too. After applying an override, inspect the final dns object instead of just confirming that enable is now true.
Append, Prepend, and Replace Lists
Understand mapping merges and list merges separately. A listener port is a single scalar and can often be overridden directly; rules and proxy groups are structured lists that may be replaced, appended, prepended, or handled by a script. Do not assume a shorter rules list will automatically preserve the rest of the subscription's entries. With replacement semantics, all existing category rules may disappear.
Rule order is especially important. Personal exceptions usually need to go before general rules; appending them after MATCH will not produce the intended matches. Locate a proxy group by its unique name before changing its members—do not insert another group with the same name. For auto-updating configurations, overrides should also be idempotent: running the same input repeatedly must not keep adding duplicate rules or members.
Separate Subscription Updates from Personal Settings
Subscription-managed content is best for provider-maintained proxy parameters and resource collections. Manage local preferences such as the local port, log level, and specific personal access rules locally. This does not mean every local value should override the subscription: pinning outdated protocol parameters in an override can cause authentication or transport issues after an update. Keep overrides limited to necessary differences.
Scripts can do more than ordinary field merges, so they need stricter safeguards. Before editing, confirm the target array exists and locate the expected group; do not silently create an incomplete object when it is missing. Group name changes are a common risk with remote configuration updates. A script should return a clear error or skip safely, not produce an unloadable runtime configuration. Recheck references whenever you change processing order.
Before editing, keep a working Profile and a backup of your overrides. Never commit files containing subscription credentials to a public code repository. A backup should cover the configuration source, personal rules, and necessary client settings; a temporary generated runtime file alone may not restore the original update relationship. Record the goal of each change—for example, only change DNS or prepend one rule—to make rollback much easier.
After applying an override, validate three layers: first confirm the YAML parses, then confirm group and provider references are intact, and finally test real behavior with a new connection. If an update suddenly breaks things, compare resource changes with the override targets before deleting all personal settings. Disable one processing step at a time to locate conflicts; this preserves more useful information than replacing the subscription, core, and client all at once. For the basics of configuration sources, see Profile Management.
SECTION 08 / VALIDATE AND ISOLATE
Configuration Validation and Troubleshooting
Validate the Output, Then Test Traffic
A configuration needs three levels of checks: syntax, semantics, and runtime behavior. Syntax checks cover indentation, quotes, and list structure; semantic checks cover field support, policy references, and resource formats; runtime checks cover ports, network reachability, and actual rule matches. Passing one level does not replace the next. In particular, successfully loading a file does not mean apps can connect if remote resources have not loaded or the system proxy has not taken effect.
If you can run mihomo directly, use its test options to check the specified file. Use the same core as the client and run it from the same working directory—or set the data directory explicitly—so relative-path resources can be found. If the desktop client offers a configuration test or runtime configuration viewer, use it first to avoid starting another process that could conflict with existing listeners.
# Run from the configuration directory; adjust the command for the actual executable location
mihomo -t -f ./config.yaml
# Windows PowerShell, when the executable is in the current directory
.\mihomo.exe -t -f .\config.yaml
Line numbers in test output usually point to where parsing failed, but the actual cause may be on the preceding line—for example, an unclosed quote or incorrect indentation. Fix the first clear error and test again; do not keep changing things based on multiple messages caused by the same issue. If a field is reported as unsupported, check the core type and whether the current version supports the option instead of moving the field to another level and hoping it works.
Narrow Down the Connection Path
First confirm that the client and core start normally and that the logs show no listener failures. Next, confirm the app is connecting to the right proxy address, using an explicit proxy test if needed. Then check that DNS resolves the destination through the expected path. Review the rule match and final proxy group decision next. Finally, investigate the remote protocol handshake and server response. This order helps separate local configuration problems from remote connection issues.
# Test only the local HTTP proxy listener and the request path beyond it
curl --proxy http://127.0.0.1:7890 --head https://example.com
# In the SOCKS test, let the proxy resolve the destination hostname
curl --proxy socks5h://127.0.0.1:7890 --head https://example.com
These commands require curl to be installed and the port to match the runtime configuration. The test site is only for observing the request path; a failed command does not prove the entire configuration is invalid. A connection refusal usually points to the local listener; a name resolution failure points to DNS; a proxy handshake error calls for checking the protocol and authentication. Errors at different stages need different fixes.
| Symptom | Check first | Next step |
|---|---|---|
| Configuration fails to load | Indentation, duplicate keys, field types | Check the first parse error and nearby lines |
| Proxy group target not found | Do the group name and reference match? | Check whether an override removed or renamed it |
| Cannot connect to the local listener | Listener address, port, and core process | Check for duplicate clients and port conflicts |
| Rules produce an unexpected result | Mode, first matching rule, existing connections | Reconnect and review the full rule order |
| Issues after a subscription update | Differences between the original resource and override output | Restore changes one at a time in a backup Profile |
System Differences and Minimal Rollback
System proxy and firewall settings on Windows, service permissions on macOS, and proxy settings in Linux desktop environments all affect which traffic is intercepted, but they do not change YAML's basic structure. If the system displays a warning, investigate installation and permission settings rather than looking for a fix in the rules list. For macOS, see Installation Permissions and Keychain Prompts. Whether a permission is needed depends on the installation method.
Minimal rollback does not mean deleting the entire configuration; it means undoing the latest change while preserving evidence of the problem. First disable the newly added override, then restore a single field, and only then consider switching to a backup Profile. Change one variable at a time and repeat the same test with a new connection. If you update the client, core, and subscription at once, it is difficult to identify what changed the result or reproduce the issue.
When sharing troubleshooting details, keep the error text, field hierarchy, and steps taken, but remove subscription URLs, passwords, authentication parameters, and personal destinations. A screenshot cannot replace readable error text, but never publish a complete configuration either. Once the issue is resolved, restore the normal log level, remove temporary test rules, and record the changes that worked. Use the glossary for field definitions. To repeat the import and verification process, return to the quick start guide rather than mixing reference material with first-time setup steps.