Configuration Overview

MeowX runs on a configuration file in the mihomo / Clash Meta config.yaml format. In practice this file almost always comes from a subscription: a URL from your provider that returns a complete YAML document with proxies, proxy-groups, rules and usually dns.

MeowX treats mihomo as the specification for behavior: field names, defaults, rule matching semantics, proxy group logic and DNS behavior follow mihomo wherever MeowX implements a feature. Keys MeowX does not use are ignored, so a file written for mihomo normally imports without changes. The pages in this section list exactly what is read and where MeowX differs. For a one-page summary see Compatibility.

Top-level keys

These are the only top-level keys MeowX reads. Every other top-level key is ignored.

Key	Type	Default	Description
mode	string	rule	Outbound mode: rule, global or direct (lowercase). The app’s mode switch changes this value; see below.
log-level	string	info	Accepted values: debug, info, warning, error, silent. The value is validated but otherwise ignored: logging is controlled by the “Record logs” switch in the app.
ipv6	bool	false	Accepted but ignored. Whether DNS returns IPv6 addresses is controlled by dns.ipv6, and whether IPv6 traffic enters the tunnel by the app’s IPv6 mode.
proxies	list	[]	The nodes. See Protocol overview.
proxy-groups	list	[]	See Proxy groups.
rules	list	[]	See Rules.
rule-providers	map	{}	See Rule providers.
dns	map	—	See DNS.
hosts	map	{}	Static domain-to-IP entries. See DNS → hosts.
sniffer	map	enabled	Only enable is read. Unlike mihomo, sniffing is on by default. See Sniffer.

A minimal working file:

mode: rule

proxies:
  - name: node-1
    type: ss
    server: 192.0.2.1
    port: 8388
    cipher: aes-128-gcm
    password: example-password
    udp: true

proxy-groups:
  - name: Proxy
    type: select
    proxies: [node-1, DIRECT]

rules:
  - DOMAIN-SUFFIX,example.com,Proxy
  - GEOIP,CN,DIRECT
  - MATCH,Proxy

Keys that are ignored

Common mihomo keys with no effect in MeowX include:

• Inbound ports and listeners: port, socks-port, mixed-port, redir-port, tproxy-port, allow-lan, bind-address, authentication, listeners. MeowX has its own optional local HTTP / SOCKS5 proxy, configured in the app.
• Controller and UI: external-controller, external-ui, secret, profile.
• tun (the whole section). The tunnel is set up by the system VPN framework; see TUN and IPv6.
• proxy-providers. Nodes must be listed under proxies:. A use: list in a proxy group is ignored.
• sub-rules, tunnels, ntp, experimental.
• Geodata settings: geox-url, geodata-mode, geo-auto-update, geo-update-interval. MeowX ships its own databases; see GeoIP and GeoSite.
• Global tuning: unified-delay, tcp-concurrent, find-process-mode, global-client-fingerprint, keep-alive-interval, interface-name, routing-mark.

Validation

When a configuration is imported or a subscription is refreshed, MeowX parses and checks it before using it. If the check fails, the new file is rejected and the configuration you were using stays active.

The whole file is rejected when:

• the YAML is invalid, or a key has the wrong type (for example mode: Rule instead of mode: rule);
• two proxies or groups have the same name, or a name collides with a built-in target (DIRECT, REJECT, REJECT-DROP, PASS, COMPATIBLE);
• a proxy is missing a required field (for example server / port, or the protocol’s password / UUID);
• a proxy group has an unknown type, lists a member that does not exist, or groups reference each other in a loop;
• a rule line has an unknown rule type or is malformed. See Rules → Unsupported rule types.

These problems only produce a warning, and the rest of the file still loads:

• a proxy of an unsupported type, or one that cannot be built (for example an unsupported cipher) — the node is skipped;
• a rule whose target is not a proxy, group or built-in target, or whose RULE-SET names a provider that is not defined — only that rule is dropped (mihomo refuses the whole file here);
• an invalid expected-status on a group — it is treated as not set.

What MeowX changes or adds

MeowX keeps your subscription file as downloaded and builds the active configuration from it. A few things are adjusted or layered on top.

DNS section

• dns.enable is always set to true.
• dns.enhanced-mode is set according to the app’s DNS mode setting: Follow subscription (the default), Redir-Host or Fake-IP. Follow subscription uses the subscription’s own enhanced-mode and falls back to redir-host when the subscription doesn’t set one.
• When the effective mode is fake-ip and the file has no fake-ip-range / fake-ip-filter, defaults are added.
• When the file has no dns section at all, a built-in fallback DNS section is used.

All other DNS keys (nameserver, nameserver-policy, direct-nameserver, …) are kept as written. Details are on the DNS page.

Outbound mode

The Rule / Global / Direct switch in the app writes the mode value of the active configuration and takes effect immediately, without reconnecting. Refreshing the subscription rebuilds the configuration from the downloaded file, so the subscription’s own mode value applies again.

• Rule — rules decide; see Rules → Matching order.
• Global — all traffic goes to the group named GLOBAL if the file defines one, otherwise to the first group in proxy-groups, otherwise DIRECT. MeowX does not create a built-in GLOBAL group.
• Direct — all traffic goes direct.

Remembered selections

The node you pick in a select group, and a node you pin in a url-test or fallback group, is remembered per group name and restored the next time the tunnel starts. If that member no longer exists (for example after switching subscriptions), the group starts from its default.

Settings that are never written into the file

The following live in the app, apply to every configuration, and are evaluated before your subscription’s rules. They are stored separately so that refreshing a subscription never erases them:

Setting	Effect
Bypass list (domains and IP / CIDR)	Always DIRECT, in every mode.
APNs direct (on by default)	Apple Push Notification traffic always goes DIRECT, in every mode. Can be turned off.
Your provider’s dashboard	When you are signed in, the dashboard’s own domain and its subscription domains always go DIRECT, in every mode.
DNS overrides	Fixed answers for domains, used before hosts, fake-ip and upstream servers.
Block QUIC	Drops UDP to port 443 so apps fall back to TCP.
Custom rules	“Direct / Proxy / Reject this domain”, in Rule mode only, before the subscription’s rules.
Rules from enabled modules	A module’s [Rule] section, in Rule mode only, after custom rules and before the subscription’s rules.

Subscriptions

How a subscription is downloaded

MeowX sends a plain HTTP(S) GET with this User-Agent:

mihomo/1.19.0 MeowX/<version> (<platform>)

where <platform> is iOS or macOS, for example mihomo/1.19.0 MeowX/0.5.8 (iOS).

• The leading mihomo/1.19.0 is what most providers and panels look for to decide that the client wants a complete mihomo YAML (with proxies, proxy-groups, rules and dns) instead of a list of share links. Don’t strip it if you proxy or rewrite subscription requests.
• MeowX/<version> identifies the official MeowX client. A MeowX-compatible provider dashboard uses it to include nodes that only MeowX supports (for example AnyTLS with REALITY), which it filters out for other Clash clients.

The response is never served from a local HTTP cache, so pressing refresh always fetches the current file. The request times out after 20 seconds.

Caution

The response body must be a mihomo / Clash YAML configuration. Base64-encoded lists of share links (ss://, vmess://, …) are not converted and fail to import.

Response headers

Header	Used for
subscription-userinfo	Traffic usage and expiry shown in the app and widgets. Format: upload=<bytes>; download=<bytes>; total=<bytes>; expire=<unix seconds>. Any field may be missing.
profile-title	The subscription’s display name. A base64: prefix is decoded (profile-title: base64:<base64 of UTF-8 text>). Without this header the name is the URL’s host.
profile-update-interval	Recorded, but not used for scheduling. Automatic updates follow the app’s sync interval setting (below).

Automatic updates

The active subscription is refreshed automatically when it is older than the app’s sync interval (24 hours by default; 0 means manual only). The check runs when the app starts or returns to the foreground; on iPhone and iPad it can also run in the background through Background App Refresh. A failed refresh keeps the previous configuration.

Rule providers referenced by the configuration are downloaded separately; see Rule providers → Downloading and caching.