Clash Verge Rev · Mihomo Config / Rules / External Controller

Clash Verge Rev 的 Mihomo 配置与 API 开发文档

Clash Verge Rev 是基于 Tauri 的桌面 GUI，并内置 Mihomo 内核。配置、规则和对外控制能力主要来自 Mihomo；这里聚焦代理组、路由规则、DNS、TUN、Providers 与 External Controller API，不把 Clash Verge Rev 的内部 GUI 通信当作公开 API。

Mihomo 基础配置 Proxy Groups / Rules DNS / TUN External Controller API

Mihomo 基础配置与 Clash Verge Rev 的配置关系

Clash Verge Rev 负责 Profile 管理、图形界面和系统集成，实际执行代理、规则、DNS 与 TUN 的核心是 Mihomo。理解 mixed-port、mode、Providers、Proxy Groups、Rules 和 External Controller，有助于判断 GUI 设置最终如何落到内核配置。

config.yaml — Mihomo 基础配置结构示例

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

dns:
  enable: true
  nameserver:
    - https://1.1.1.1/dns-query
    - https://dns.google/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

mixed-port、allow-lan 与 mode 的职责

mixed-port 适合直接给浏览器插件、系统代理或本地工具统一接入；allow-lan 控制是否允许局域网访问；mode 决定当前是规则模式、全局模式还是直连模式。

配置示例为什么使用占位 Provider 地址？

节点和订阅属于用户自己的配置来源。示例使用 example.com 作为占位地址，只用于说明字段关系，避免把演示服务器、密钥或订阅 URL 误认为真实可用资源。

Mihomo Proxy Groups：选择、测速与故障切换

Proxy Groups 决定代理节点如何被组织和选择。select 用于手动选择，url-test 根据健康检查结果自动选择，fallback 则按成员顺序使用首个可用代理；组内既可以引用代理，也可以通过 use 引用 Proxy Providers。

proxy-groups.yaml — select / url-test / fallback 示例

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - Auto
      - Fallback
      - DIRECT

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

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

Proxy Groups 的三个核心选择逻辑

select 用于人工指定当前出口；url-test 根据健康检查结果自动选优；fallback 按成员顺序寻找首个可用代理。url、interval、timeout 与 lazy 等字段会影响测试和切换行为。

Mihomo 路由规则：匹配顺序与流量出口

Mihomo 从上到下匹配路由规则。DOMAIN、DOMAIN-SUFFIX、IP-CIDR、GEOIP 等规则用于识别流量，命中后交给指定代理或策略组；未命中的流量通常由最后的 MATCH 规则处理。

rules.yaml — 常见路由规则示例

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

按完整域名或域名后缀匹配，适合为特定网站和服务建立明确路由。

域名匹配

IP-CIDR / GEOIP

按目标 IP 网段或 GeoIP 国家代码匹配，适合基于地址范围进行路由。

IP 匹配

MATCH

承接前面规则没有命中的流量，因此通常作为规则列表的最终兜底。

最终兜底

为什么规则顺序会直接改变路由结果？

Mihomo 按规则列表从上到下匹配，越靠前优先级越高；命中后即使用对应目标。具体规则通常放在前面，MATCH 放在最后，避免过早兜底覆盖后续规则。

Mihomo DNS 与 TUN：解析链路和系统级流量接管

DNS 决定域名解析如何与规则系统配合；TUN 通过虚拟网卡接管更广泛的系统流量。Clash Verge Rev 提供 TUN 的图形化控制，但底层行为仍由 Mihomo 的 tun 配置、系统权限、防火墙和路由环境共同决定。

dns.yaml — Fake-IP 与 DoH 配置示例

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

tun.yaml — Mihomo 顶层 TUN 配置示例

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

哪些现象应该优先检查 DNS 配置？

域名解析失败、解析结果与规则不一致、Fake-IP 行为异常，或切换代理后仍出现错误解析，都可能与 DNS 配置相关。排查时应同时检查 nameserver、enhanced-mode、监听端口和规则关系。

TUN 的 system、gVisor 与 mixed 如何理解？

Mihomo 当前支持 system、gVisor 与 mixed 协议栈。官方文档在无特殊问题时建议使用 mixed；实际选择还应结合操作系统、防火墙、性能和兼容性测试。

Rule Providers 与 Proxy Providers：拆分规则集和节点来源

Rule Providers 用于加载可复用规则集，Proxy Providers 用于加载和更新代理集合。将规则和节点来源从主配置拆开，可以分别设置更新周期、健康检查、过滤和文件路径，更适合长期维护。

rule-providers.yaml — 远程规则集示例

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

  direct:
    type: http
    behavior: domain
    format: yaml
    path: ./ruleset/direct.yaml
    url: https://example.com/rules/direct.yaml
    interval: 86400

rules.yaml — 使用 RULE-SET 引用规则集

rules:
  - RULE-SET,reject,REJECT
  - RULE-SET,direct,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

proxy-providers.yaml — 远程代理集合与健康检查

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

Rule Providers 和 Proxy Providers 的职责

rule-providers 提供可被 RULE-SET 引用的规则内容；proxy-providers 提供代理节点集合，可被策略组通过 use 引用，并独立配置更新和健康检查。

Mihomo External Controller API：状态读取与策略控制

Mihomo 提供 RESTful External Controller API。Clash Verge Rev 默认使用内部 IPC 与内核通信；只有在用户显式启用 External Controller 后，外部脚本或 Dashboard 才应通过监听地址和 secret 访问内置 Mihomo。

config.yaml — 仅在本机启用 External Controller

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

curl — 获取代理与策略组状态

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

curl — 为 Selector 策略组切换当前代理

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 — 触发 Proxy Provider 健康检查

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

External Controller 为什么应优先绑定本机地址？

External Controller 能读取状态并执行策略切换、Provider 更新等控制操作。优先绑定 127.0.0.1，并设置强 secret；若需要远程访问，还应增加防火墙、可信网络或受控反向代理限制。

Clash Verge Rev 是否把 External Controller 当作公开插件接口？

不是。项目维护者明确说明 GUI 默认使用内部 IPC；External Controller 需要用户主动启用。对于纯脚本化控制场景，维护者也更建议直接围绕 Mihomo 核心本身进行集成。

开发集成边界：Clash Verge Rev GUI、Mihomo 与 API

Clash Verge Rev、Mihomo 与 Dashboard 属于不同层级：Clash Verge Rev 提供桌面 GUI 和系统集成，Mihomo 负责实际代理与规则执行，External Controller 则是可选的外部控制入口。开发时应先确认真正需要集成的是哪一层。

1. External Controller 默认应保持本机或受控访问

如果启用 External Controller，优先绑定 127.0.0.1 并设置 secret 鉴权。需要远程访问时，应额外限制来源网络，避免将核心控制面直接暴露到公网。

2. 配置拆分应围绕 Providers 长期维护

节点来源适合拆到 proxy-providers，规则集适合拆到 rule-providers。这样可以分别处理更新周期、健康检查、规则格式和文件路径，降低主配置复杂度。

3. Dashboard 是控制层，Mihomo 才是执行核心

Dashboard 和桌面 GUI 负责展示与控制，真正处理代理连接、规则、DNS 与 TUN 的是 Mihomo。理解这一层级可以避免把客户端界面能力误认为内核 API。

4. API 方法和路径应按当前 Mihomo 文档校验

例如策略组切换使用 PUT /proxies/{name}，而 Proxy Provider 的 healthcheck 使用 GET。自动化脚本应避免继续复制旧示例中的请求方法和返回结构。

config.yaml — 更保守的 External Controller 示例

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

# 仅在确有远程控制需求时调整监听地址。
# 同时限制网络访问范围，并避免在前端代码中暴露 secret。

重点说明 Clash Verge Rev、Mihomo 配置和 External Controller 之间的技术边界，避免把 GUI、内核与外部控制接口混为同一层。

Clash Verge Rev 与 Mihomo 开发常见问题

如果你正在编写配置、调试规则或接入控制 API，下面这些问题通常最先会遇到。

Clash Verge Rev 有独立的公开 REST API 吗？+

Clash Verge Rev 的公开开发重点并不是独立 REST API。项目内置 Mihomo，并默认通过内部 IPC 与核心通信；如需外部控制，可以主动启用 Mihomo External Controller，但这属于需要自行评估安全风险的高级用法。

Clash Verge Rev 的 Profile 与 Mihomo 配置是什么关系？+

Clash Verge Rev 提供 Profile、Merge、Script、可视化节点和规则编辑等 GUI 能力，最终由 Mihomo 执行生效配置。具体字段行为仍应以当前 Mihomo 配置文档为主要技术参考。

为什么同一份 YAML 在不同客户端表现可能不同？+

客户端可能使用不同 Mihomo 版本、默认覆写、Merge 或 Script、系统代理逻辑以及 TUN 设置。排查时应查看最终生效配置和当前内核版本，而不只比较原始订阅文件。

External Controller 可以直接暴露给网页前端吗？+

不建议。该接口可以读取运行状态并执行策略切换、Provider 更新等操作。更安全的方式是限制在本机或可信网络，并配置 secret 与额外访问控制。

Clash Verge Rev

继续下载客户端或深入配置 Mihomo

下载页用于选择 Windows、macOS 或 Linux 的 Clash Verge Rev 版本；配置教程用于处理 Profile、系统代理和 TUN。涉及字段、Providers 与 External Controller 的开发集成，则应继续以 Mihomo 官方文档为技术依据。

前往下载页面服务条款