ZHGet FlClash

FlClash Developer Docs · Mihomo Config / Core / External Controller

FlClash Developer Docs: Mihomo Configuration & API

FlClash is the Flutter client and platform-integration layer around ClashMeta (Mihomo). On desktop, FlClash communicates with a separate Core process over JSON sockets; on Android, it calls the shared Core through FFI. Those internal paths are not a public REST API. Use Mihomo External Controller only when an external script, dashboard or trusted tool needs API access.

Profile / OverrideProxy Groups / RulesDNS / TUN / ProvidersExternal Controller REST API

Profiles, Override and the final Mihomo runtime config

A Profile provides the base configuration. FlClash can apply local settings and Override / Override Script changes before the final config is loaded by Mihomo. When debugging, compare the source Profile with the effective runtime configuration instead of assuming they are identical.

config.yaml — self-contained Mihomo example
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

dns:
  enable: true
  enhanced-mode: fake-ip
  default-nameserver:
    - 1.1.1.1
  nameserver:
    - https://1.1.1.1/dns-query

proxy-providers:
  provider1:
    type: http
    url: https://example.com/proxies.yaml
    path: ./proxy_providers/provider1.yaml
    interval: 3600

proxy-groups:
  - name: PROXY
    type: select
    use:
      - provider1
    proxies:
      - DIRECT

rules:
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

What does FlClash add around a Profile?

FlClash manages the active Profile plus local options such as mode, ports, DNS, TUN, IPv6 and External Controller. Override and Override Script can also change the configuration before Mihomo loads it.

Why use placeholder provider URLs?

Subscription URLs, proxy credentials and provider endpoints belong to the user or their chosen service. Examples use example.com only to show field relationships and do not provide working proxy infrastructure.

Mihomo Proxy Groups: select, url-test and fallback

Proxy Groups turn individual proxies or Proxy Providers into routing policies that Rules can target. Use select for manual choice, url-test for automated testing, and fallback for ordered failover.

proxy-groups.yaml — select / url-test / fallback
proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - Auto
      - Failover
      - DIRECT

  - name: Auto
    type: url-test
    use:
      - provider1
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

  - name: Failover
    type: fallback
    use:
      - provider1
    url: https://www.gstatic.com/generate_204
    interval: 300

How do proxies and use differ inside a group?

`proxies` references named proxies or other groups, while `use` references Proxy Providers. Health-check URL, interval, timeout, lazy and tolerance settings determine how automated groups test and switch members.

Mihomo Rules: ordered matching and outbound policy

Mihomo evaluates Rules from top to bottom. DOMAIN, DOMAIN-SUFFIX, IP-CIDR, GEOIP and RULE-SET can direct matching traffic to a proxy group, DIRECT or another action; MATCH normally remains the final fallback.

rules.yaml — common ordered rules
rules:
  - DOMAIN-SUFFIX,example.com,PROXY
  - DOMAIN-KEYWORD,example,PROXY
  - IP-CIDR,203.0.113.0/24,PROXY,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

DOMAIN / DOMAIN-SUFFIX

Match a specific domain or domain suffix before broader fallback rules.

Domain rules

IP-CIDR / GEOIP

Match address ranges or GeoIP data; DNS behavior and no-resolve can affect how address-based rules are reached.

IP / Geo rules

RULE-SET / MATCH

RULE-SET references a Rule Provider, while MATCH usually handles traffic that did not match anything above it.

Ruleset / fallback

Why can Rule order change the final route?

Mihomo stops at the first matching Rule, so narrow conditions should appear before broader ones and MATCH normally belongs at the end. Also check whether FlClash Override or added Rules changed the effective order.

DNS and TUN: resolution, Fake-IP and system traffic capture

DNS controls how names are resolved and how resolver traffic interacts with Rules. TUN captures a wider range of system traffic through a virtual interface. FlClash exposes these settings in the UI, but Mihomo and the operating system still determine the runtime behavior.

dns.yaml — Fake-IP and resolver roles
dns:
  enable: true
  ipv6: false
  enhanced-mode: fake-ip
  default-nameserver:
    - 1.1.1.1
  nameserver:
    - https://1.1.1.1/dns-query
    - https://dns.google/dns-query
  proxy-server-nameserver:
    - https://1.1.1.1/dns-query
tun.yaml — top-level TUN example
tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53
    - tcp://any:53
  strict-route: true

Which DNS fields matter when routing looks wrong?

Check enhanced-mode, default-nameserver, nameserver, proxy-server-nameserver, nameserver-policy and respect-rules. Proxy node hostname resolution can fail even when ordinary domain lookups still work.

How should the TUN stack be chosen?

Mihomo currently supports system, gvisor and mixed. Its documentation recommends mixed when there are no compatibility issues. strict-route, auto-route, dns-hijack and firewall behavior can still vary by Android, Windows, macOS and Linux.

Proxy Providers and Rule Providers

Proxy Providers supply updateable proxy collections; Rule Providers supply reusable rule sets that can be referenced by RULE-SET. Keeping them separate lets you manage update intervals, paths, formats, filters and health checks independently.

rule-providers.yaml — remote rule set
rule-providers:
  direct:
    type: http
    behavior: domain
    format: yaml
    path: ./ruleset/direct.yaml
    url: https://example.com/rules/direct.yaml
    interval: 86400
proxy-providers.yaml — remote proxies and health check
proxy-providers:
  provider1:
    type: http
    url: https://example.com/proxies.yaml
    path: ./proxy_providers/provider1.yaml
    interval: 3600
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 300
      timeout: 5000

How do Providers relate to FlClash Resources?

Mihomo loads and updates Provider data. FlClash surfaces resource state, update information and related proxies or rules in its interface so the runtime data is easier to inspect.

Mihomo External Controller: optional REST / WebSocket access

FlClash keeps External Controller disabled by default. When enabled in the current client, it uses 127.0.0.1:9090. The Mihomo API can expose version, config, proxies, Providers, Rules, Connections, Logs and Traffic, and can perform selected runtime control operations.

config.yaml — enable local External Controller
external-controller: 127.0.0.1:9090
secret: "replace-with-a-strong-secret"
curl — read version and runtime config
curl -H "Authorization: Bearer replace-with-a-strong-secret"   http://127.0.0.1:9090/version

curl -H "Authorization: Bearer replace-with-a-strong-secret"   http://127.0.0.1:9090/configs
curl — read proxies and switch a Selector
curl -H "Authorization: Bearer replace-with-a-strong-secret"   http://127.0.0.1:9090/proxies

curl -X PUT   -H "Content-Type: application/json"   -H "Authorization: Bearer replace-with-a-strong-secret"   -d '{"name":"Example Node"}'   http://127.0.0.1:9090/proxies/PROXY
curl — trigger a Proxy Provider health check
curl -H "Authorization: Bearer replace-with-a-strong-secret"   http://127.0.0.1:9090/providers/proxies/provider1/healthcheck

Why should External Controller stay local by default?

The controller can read runtime state and perform actions such as Selector changes, config operations and Provider updates. FlClash currently opens it on 127.0.0.1:9090. If you design remote access yourself, add a strong secret plus network restrictions, firewall rules and any required proxy or TLS boundary.

Is External Controller the same as FlClash Core IPC?

No. Desktop FlClash uses JSON over sockets to communicate with its separate Core process, while Android uses FFI. External Controller is Mihomo's optional external API surface for scripts, dashboards and other trusted tools.

Integration boundaries: FlClash UI, Core IPC and Mihomo API

Choose the layer you actually need. FlClash is the human-facing multi-platform client, Mihomo is the execution core, and External Controller is the optional external API. FlClash internal Core communication is an implementation detail rather than a stable third-party plugin contract.

1. Do not treat FlClash Core IPC as a public REST API

Desktop builds run the Core as a separate process and exchange JSON over Unix sockets on macOS/Linux or TCP on Windows. Android integrates the shared Core through FFI.

2. Use current Mihomo API methods for automation

Read endpoints such as /version, /configs, /proxies, /rules and /providers/proxies using the documented methods, and verify method/response changes before shipping automation.

3. Use FlClash Override terminology for local config changes

Current FlClash exposes Override and Override Script. Treat the final generated config as the debugging target instead of assuming the remote Profile is the only layer.

4. Secure browser dashboards and remote control separately

A browser dashboard may also require External Controller CORS settings. Restrict allowed origins and keep the raw controller away from the public internet whenever possible.

config.yaml — conservative local controller example
external-controller: 127.0.0.1:9090
secret: "replace-with-a-strong-secret"

# Add CORS only when a browser dashboard genuinely needs it.
# Do not expose the listener address or secret in public client code.

Developer FAQ

FlClash and Mihomo API questions

These answers separate FlClash client behavior, the final Mihomo configuration and the optional External Controller API.

Does FlClash expose its own public REST API?+

Not as its primary integration model. Desktop FlClash communicates with its Core over internal sockets and Android uses FFI. For external automation, use Mihomo External Controller only after explicitly enabling it.

Should I debug the source Profile or the final Mihomo config?+

Start with the effective runtime configuration when behavior differs from the source. FlClash options, Override, Override Script, DNS and TUN settings can change what Mihomo ultimately loads.

Why can the same YAML behave differently across Mihomo clients?+

Clients may bundle different Mihomo versions, generate different defaults, apply different overrides, or integrate System Proxy, TUN and DNS differently. Compare the effective config, Core version and operating system environment.

Should a public web app call External Controller directly?+

No. The controller can expose sensitive runtime state and control operations. Keep it local or behind a trusted, authenticated boundary, and use narrowly scoped backend endpoints if a public product needs selected actions.

Continue

Download FlClash or continue with configuration

Use the download page for Android, Windows, macOS and Linux builds. Use the tutorial for Profiles, Override, routing modes, System Proxy, Android VPN and TUN before moving into advanced Mihomo API integration.

Download FlClashTerms