Clash Verge Rev Docs · Mihomo Config / Rules / External Controller

Clash Verge Rev Mihomo Configuration & API

This developer-focused guide separates Clash Verge Rev from the Mihomo core it embeds. Use the configuration sections for Mihomo YAML structure, rules, providers, DNS and TUN; use the API section only when External Controller is explicitly enabled.

Mihomo configRules & proxy groupsProvidersExternal Controller API

Mihomo base configuration used by Clash Verge Rev

Clash Verge Rev manages profiles and GUI settings, while Mihomo loads the final runtime configuration. The smallest useful example defines local ports, DNS, a proxy entry and ordered routing rules.

config.yaml — basic example

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

dns:
  enable: true
  nameserver:
    - https://1.1.1.1/dns-query
    - https://8.8.8.8/dns-query

proxies:
  - name: "Example Proxy"
    type: socks5
    server: 127.0.0.1
    port: 1080

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

What do the base networking fields mean?

The mixed-port listener accepts HTTP and SOCKS proxy traffic on one local port. allow-lan controls whether other devices can reach local proxy listeners, while mode selects the routing mode.

Why treat DNS as part of the core configuration?

DNS behavior affects name resolution before routing can work as expected. If a proxy appears reachable but domains fail or resolve inconsistently, inspect the DNS path before assuming the proxy node itself is broken.

Mihomo proxy group configuration

Proxy groups turn individual proxies into selectable or automated policies that rules can target. Common group types include manual selection, latency testing and ordered failover.

proxy-groups.yaml — example

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - Auto
      - Primary
      - Backup
      - DIRECT

  - name: Auto
    type: url-test
    url: https://www.gstatic.com/generate_204
    interval: 300
    proxies:
      - Primary
      - Backup

  - name: Failover
    type: fallback
    url: https://www.gstatic.com/generate_204
    interval: 600
    proxies:
      - Primary
      - Backup

How should proxy groups be designed?

select is for manual choice, url-test can select by measured latency, fallback follows an ordered failover strategy. Name groups by routing purpose so rules target stable policies rather than individual node names.

Mihomo routing rule examples

Rules are evaluated in order and stop at the first match. Keep specific matches above broader conditions and reserve MATCH for the final fallback path.

rules.yaml — common syntax

rules:
  - DOMAIN-SUFFIX,example.com,PROXY
  - DOMAIN-KEYWORD,example,PROXY
  - IP-CIDR,198.51.100.0/24,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

DOMAIN / DOMAIN-SUFFIX

Match an exact domain or domain suffix before the request reaches broader fallback rules.

Domain rules

GEOIP / IP-CIDR

Route by IP range or GeoIP data when address-based policy is more appropriate than domain matching.

IP rules

MATCH

The final catch-all rule for traffic that did not match any earlier condition.

Final fallback

Why is rule order part of the configuration logic?

Mihomo evaluates rules from top to bottom and stops at the first match. Put narrow conditions first and keep MATCH last so it does not swallow traffic intended for more specific rules.

DNS and TUN configuration for Mihomo

DNS and TUN operate close to the network layer. Treat these values as environment-sensitive settings rather than universal defaults, especially when system permissions, firewalls or other virtual adapters are involved.

dns.yaml — recommended structure

dns:
  enable: true
  ipv6: false
  enhanced-mode: fake-ip
  listen: 127.0.0.1:1053
  default-nameserver:
    - 1.1.1.1
    - 8.8.8.8
  nameserver:
    - https://1.1.1.1/dns-query
    - https://8.8.8.8/dns-query

tun.yaml — Mihomo example

tun:
  enable: true
  stack: mixed
  dns-hijack:
    - any:53
  auto-route: true
  auto-detect-interface: true
  strict-route: true

When should DNS be checked before routing rules?

If IP-based tests work while domain lookups fail, or only certain hostnames break, inspect the resolver and fake-IP path before rewriting proxy groups or rules.

What does the TUN stack setting control?

Mihomo supports system, gvisor and mixed TUN stacks. mixed combines the system stack for TCP with gVisor for UDP and is a useful general example, but the best choice still depends on the operating system and firewall behavior.

Rule Providers and Proxy Providers

Providers separate remotely maintained data from the main configuration. Rule Providers supply routing rules; Proxy Providers supply proxy entries and optional health checks.

rule-providers.yaml — remote rules

rule-providers:
  example-rules:
    type: http
    behavior: domain
    path: ./ruleset/example.yaml
    url: https://example.com/rules/example.yaml
    interval: 86400

proxy-providers.yaml — remote nodes

proxy-providers:
  example-provider:
    type: http
    url: https://example.com/subscription.yaml
    path: ./providers/example.yaml
    interval: 3600
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 600

What is the provider boundary?

rule-providers supply routing rule sets, while proxy-providers supply remote proxy definitions. Keeping those responsibilities separate makes updates and debugging easier.

Optional Mihomo External Controller API

Clash Verge Rev normally controls its embedded Mihomo core through IPC. The HTTP External Controller is not exposed unless you explicitly enable it, so the examples below describe Mihomo API access after that setting is turned on.

config.yaml — enable API control

external-controller: 127.0.0.1:9090
secret: "replace-with-a-strong-secret"
external-ui: ./dashboard

curl — read proxy state

curl -H "Authorization: Bearer replace-with-a-strong-secret"   http://127.0.0.1:9090/proxies

curl — switch current node in a group

curl -X PUT   -H "Content-Type: application/json"   -H "Authorization: Bearer replace-with-a-strong-secret"   -d '{"name":"Primary"}'   http://127.0.0.1:9090/proxies/PROXY

curl — trigger a provider health check

curl   -H "Authorization: Bearer replace-with-a-strong-secret"   http://127.0.0.1:9090/providers/proxies/example-provider/healthcheck

How should External Controller be exposed?

Keep the HTTP controller on 127.0.0.1 unless you have a specific trusted-network design, and configure a strong secret. Do not treat the raw controller as a public application API.

When does External Controller make sense in Clash Verge Rev?

Use it only when an external dashboard or trusted local tool genuinely needs the Mihomo REST API. Clash Verge Rev itself is designed to control the embedded core through its own GUI and IPC path.

Integration boundaries for Clash Verge Rev and Mihomo

For custom automation, decide first whether you need Clash Verge Rev at all. The application is designed as a human-facing desktop GUI; direct Mihomo deployment is often cleaner for headless services or automation-first systems.

1. Keep External Controller private

Enable the HTTP controller only when required, use authentication, and place any remote access behind a controlled network boundary.

2. Separate source config from generated runtime config

Profiles, Merge or Script logic in Clash Verge Rev can influence the final Mihomo configuration. Debug the effective runtime config rather than assuming the remote source is the only layer.

3. Clash Verge Rev is the GUI layer

The desktop application manages user interaction and configuration; Mihomo performs proxy, rule, DNS and TUN execution.

4. Prefer direct Mihomo for automation-first services

If the real requirement is a headless daemon, API automation or remote control, running Mihomo directly usually creates a clearer architecture than wrapping automation around the desktop GUI.

config.yaml — safer external-controller example

external-controller: 127.0.0.1:9090
secret: "replace-with-a-strong-secret"
external-ui: ./dashboard

# Enable External Controller only when an external tool needs it.
# Keep the listener private or place remote access behind a
# trusted and authenticated network boundary.

Developer FAQ

Developer questions about Clash Verge Rev and Mihomo

These answers clarify the boundary between the desktop client, Mihomo configuration and the optional External Controller API.

Does Clash Verge Rev expose its own REST API by default?+

No. Clash Verge Rev normally communicates with its embedded Mihomo core through IPC. An HTTP External Controller is exposed only when you explicitly enable that option.

Should I debug a Profile or the final Mihomo configuration?+

Start with the final runtime configuration when behavior differs from the source Profile. Clash Verge Rev settings, Merge and Script processing can change what Mihomo ultimately loads.

Why can the same YAML behave differently across clients?+

Different clients may bundle different Mihomo versions, apply different generated settings, or modify the configuration before the core loads it. Compare the effective runtime config and core version.

Should a public web app call Mihomo External Controller directly?+

No. Keep the raw controller private. If a public-facing product needs selected operations, expose only those operations through your own authenticated backend or trusted service boundary.

Continue

Need the desktop client or configuration guide?

Use the download page for Windows, macOS and Linux builds, or continue with the tutorial for Profiles, rules, system proxy and TUN configuration.

Download Clash Verge Rev Terms