General configuration

Write global settings at the YAML top level. This fragment enables rule routing and persists policy selections and Fake IP mappings. Combine it with nodes, groups, DNS, and rules.

mode: rule
log-level: info
ipv6: false
unified-delay: true
tcp-concurrent: true
profile:
  store-selected: true
  store-fake-ip: true

Modes and logging

Field	Values or units	Choosing a value
mode	rule, global, direct	Route by rules, use the global outbound, or connect directly; normally use rule
log-level	silent, error, warning, info, debug	Use info normally and debug temporarily for diagnosis
ipv6	Boolean	IPv6 use also depends on the app's IP Stack setting
unified-delay	Boolean	Unified latency testing; enabled by default in this client
tcp-concurrent	Boolean	Try TCP connections to resolved addresses concurrently
find-process-mode	strict, always, off	Query as needed, always attempt, or disable; process rules mainly apply to macOS
keep-alive-idle / keep-alive-interval	Seconds	TCP keep-alive idle delay and probe interval; keep defaults without a specific need
disable-keep-alive	Boolean	Disable TCP keep-alive

See Inbound for ports, DNS for hosts, and Security for custom trust and controller access.

Platform behavior and field status

• IPv6: ipv6 and dns.ipv6 also depend on the app's IP Stack settings; TUN IPv6 capture is separate.
• Delay testing: unified-delay defaults to enabled when omitted; an explicit false disables it.
• Process routing: macOS can query process name, path, and UID. On iOS/tvOS, use destination domains, IPs, ports, or network types. See routing rules.
• Geodata: Clash manages resources. geo-auto-update stays off, and geo-update-interval does not enable scheduled updates. iOS/tvOS use precompiled resources, so some loader and matcher choices do not apply as written.
• Fingerprints: legacy global-client-fingerprint has no global effect; use client-fingerprint on supported outbound protocols.

External controllers and dashboards are advanced settings, not required for normal connections. Read access protection guidance before using them.

Search configuration fieldsPlatformAlliOS / iPadOSmacOStvOSStatusAllSupportedManaged / limitedAdvancedUnsupportedNot applicable

36 fields shown

Field	Type	iOS	macOS	tvOS	Platform notes
clash-for-android.append-system-dns	Boolean	Not applicable	Not applicable	Not applicable	Android-specific; not used on Apple platforms.
clash-for-android.ui-subtitle-pattern	String	Not applicable	Not applicable	Not applicable	Android-specific; not used on Apple platforms.
disable-keep-alive	Boolean	Supported	Supported	Supported	Controls connection keep-alive behavior; verify changes with new connections.
etag-support	Boolean	Supported	Supported	Supported	Controls ETag use for relevant HTTP resource requests.
external-controller	String	Advanced	Advanced	Advanced	Creates an HTTP/HTTPS controller. Prefer loopback binding and a secret; some desktop control APIs are unavailable.
external-controller-cors.allow-origins	List	Advanced	Advanced	Advanced	Controls browser cross-origin access; does not replace authentication.
external-controller-cors.allow-private-network	Boolean	Advanced	Advanced	Advanced	Controls browser cross-origin access; does not replace authentication.
external-controller-pipe	String	Not applicable	Not applicable	Not applicable	Windows named-pipe setting; not used on Apple platforms.
external-controller-routing-mark	Integer	Not applicable	Not applicable	Not applicable	Linux routing mark; not used on Apple platforms.
external-controller-tls	String	Advanced	Advanced	Advanced	Creates an HTTP/HTTPS controller. Prefer loopback binding and a secret; some desktop control APIs are unavailable.
external-controller-unix	String	Unsupported	Unsupported	Unsupported	The user-supplied Unix controller path is not used on any of the three platforms.
external-doh-server	String	Advanced	Advanced	Advanced	Sets a DoH path on the controller; controller secret does not protect this path.
external-ui	String	Advanced	Advanced	Advanced	Sets the dashboard directory, name, or download URL. The name must be a local relative path; static pages are outside secret authentication, while APIs authenticate separately.
external-ui-name	String	Advanced	Advanced	Advanced	Sets the dashboard directory, name, or download URL. The name must be a local relative path; static pages are outside secret authentication, while APIs authenticate separately.
external-ui-url	String	Advanced	Advanced	Advanced	Sets the dashboard directory, name, or download URL. The name must be a local relative path; static pages are outside secret authentication, while APIs authenticate separately.
find-process-mode	String	Unsupported	Supported	Unsupported	macOS can query process name, path, and UID per connection; always off on iOS/tvOS. Some connections may lack process information.
geo-auto-update	Boolean	Managed / limited	Managed / limited	Managed / limited	Always off at runtime; Clash manages resource preparation.
geo-update-interval	Integer	Unsupported	Unsupported	Unsupported	Automatic updates are off; this interval does not enable scheduled updates.
geodata-loader	String	Managed / limited	Supported	Managed / limited	iOS/tvOS use memconservative; macOS keeps the selection. Precompiled resources bypass source-data loading.
geodata-mode	Boolean	Managed / limited	Managed / limited	Managed / limited	Selects the GeoIP data mode and requires matching resources; does not bypass platform precompilation requirements.
geosite-matcher	String	Managed / limited	Managed / limited	Managed / limited	Precompiled GeoSite uses a fixed matcher. iOS/tvOS use precompiled resources; macOS may apply this choice when falling back to source data.
geox-url.asn	String	Managed / limited	Managed / limited	Managed / limited	Does not trigger automatic downloads in the tunnel; prepare data through Clash resource management.
geox-url.geoip	String	Managed / limited	Managed / limited	Managed / limited	Does not trigger automatic downloads in the tunnel; prepare data through Clash resource management.
geox-url.geosite	String	Managed / limited	Managed / limited	Managed / limited	Does not trigger automatic downloads in the tunnel; prepare data through Clash resource management.
geox-url.mmdb	String	Managed / limited	Managed / limited	Managed / limited	Does not trigger automatic downloads in the tunnel; prepare data through Clash resource management.
global-client-fingerprint	String	Unsupported	Unsupported	Unsupported	No longer sets a global fingerprint; use client-fingerprint on a supported outbound protocol.
global-ua	String	Supported	Supported	Supported	Sets the default User-Agent for relevant HTTP requests.
hosts	Mapping	Supported	Supported	Supported	Sets static domain-to-address mappings.
ipv6	Boolean	Managed / limited	Managed / limited	Managed / limited	Affected by the app’s IP Stack settings; DNS IPv6 also requires global IPv6. Tunnel IPv6 capture is a separate setting.
keep-alive-idle	Integer	Supported	Supported	Supported	Controls connection keep-alive behavior; verify changes with new connections.
keep-alive-interval	Integer	Supported	Supported	Supported	Controls connection keep-alive behavior; verify changes with new connections.
log-level	String	Supported	Supported	Supported	Sets logging level. debug also enables controller debugging endpoints; restore a normal level after troubleshooting.
mode	String	Supported	Supported	Supported	Selects rule, global, or direct outbound mode.
secret	String	Advanced	Advanced	Advanced	Protects authenticated controller APIs; an empty value requires no password. Does not protect static UI, External DoH, or independent services.
tcp-concurrent	Boolean	Supported	Supported	Supported	Controls concurrent TCP dialing; verify changes with new connections.
unified-delay	Boolean	Managed / limited	Managed / limited	Managed / limited	Defaults to true when omitted; an explicit false is preserved.

Saving runtime state

profile.store-selected saves core policy selections; profile.store-fake-ip saves Fake IP mappings. Both default to enabled when omitted; explicit false disables the corresponding cache. They do not save Profile configuration files.

Saving also requires persistent storage. tvOS may clear caches, so previous selections and mappings may be lost.

2 fields shown

Field	Type	iOS	macOS	tvOS	Platform notes
profile.store-fake-ip	Boolean	Supported	Supported	Managed / limited	Controls Fake IP cache persistence; defaults to true, false disables it. Requires persistent storage; tvOS cache loss may discard previous mappings.
profile.store-selected	Boolean	Supported	Supported	Managed / limited	Controls core policy-selection persistence; defaults to true, false disables it. Does not save Profiles; tvOS cache loss may discard previous selections.

Reference: mihomo.