EN 获取客户端

FlClash · Flutter / ClashMeta · Mihomo Config / External Controller

FlClash 开发者文档：Mihomo 配置与 External Controller API

FlClash 是使用 Flutter 构建、基于 ClashMeta（Mihomo）的多平台代理客户端。桌面端通过内部 socket 与独立 Core 进程通信，Android 通过 FFI 调用核心；这些内部通信并不是公开 REST API。需要脚本、Dashboard 或外部工具控制运行中的 Mihomo 时，应显式开启 Mihomo External Controller，并按当前 API 文档使用鉴权后的 REST / WebSocket 接口。

Mihomo 配置结构 Proxy Groups / Rules DNS / TUN / Providers External Controller REST API

FlClash 配置层与 Mihomo Core 的关系

Profile 是用户导入的原始配置来源，FlClash 再将界面中的端口、模式、DNS、TUN、IPv6、External Controller、Override 和附加规则等设置合并到最终运行配置，交给 Mihomo Core 执行。开发或排错时应区分原始 Profile、FlClash 覆写层与最终 config.yaml。

config.yaml — Mihomo 基础配置结构示例
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
ipv6: false

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

Profile、Override 与最终运行配置

FlClash 当前界面使用 Override / Override Script 等机制修改基础配置和规则。调试配置时应检查最终生效内容，而不是只看订阅源文件。

示例为什么只使用占位 URL？

订阅地址、代理节点、Provider URL 与认证信息属于用户自己的配置。示例使用 example.com，只说明字段结构，不提供代理线路、密钥或可直接使用的第三方订阅。

Proxy Groups：手动选择、自动测速与故障切换

Mihomo 的 Proxy Groups 负责把代理、其他策略组或 Proxy Providers 组织成可选择的出站策略。select 用于人工选择；url-test 根据探测结果自动选优；fallback 按成员顺序选择首个可用项。

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

proxies、use 与健康检查分别控制什么？

`proxies` 引用具体代理或其他组；`use` 引用 Proxy Providers。 url-test / fallback 的测试 URL、interval、timeout、lazy 等字段决定探测频率和选择行为。

Rules：按顺序匹配域名、IP 与规则集

Mihomo 按 Rules 列表自上而下匹配流量。DOMAIN、DOMAIN-SUFFIX、IP-CIDR、GEOIP、RULE-SET 等规则命中后，会把连接交给指定代理或策略组；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

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

域名规则

IP-CIDR / GEOIP

按目标 IP 网段或 GeoIP 数据匹配；涉及域名解析时还应考虑 DNS 与 no-resolve。

IP / GEO

RULE-SET / MATCH

RULE-SET 引用 Rule Provider；MATCH 通常作为最后一条规则承接剩余流量。

规则集 / 兜底

为什么规则顺序会改变最终出口？

Mihomo 使用首个命中的规则结果，因此具体规则应放在更宽泛规则之前，MATCH 通常放在末尾；修改规则后还要确认 FlClash 的 Override 或附加规则是否改变了最终顺序。

DNS 与 TUN：解析链路、Fake-IP 与系统流量接管

DNS 配置决定域名如何解析并与路由规则协作；TUN 通过虚拟网卡接管更广范围的系统流量。FlClash 提供图形化 DNS/TUN 设置，但最终行为仍由 Mihomo 配置、操作系统权限、路由和防火墙共同决定。

dns.yaml — Fake-IP、default-nameserver 与 DoH
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 — 顶层 TUN 配置示例
tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53
    - tcp://any:53
  strict-route: true

DNS 排错应同时检查哪些字段？

解析失败、Fake-IP 异常或代理节点域名无法解析时，应同时检查 enhanced-mode、default-nameserver、nameserver、proxy-server-nameserver、nameserver-policy、respect-rules 以及当前 Rules。

TUN 的 system、gVisor 与 mixed

Mihomo 当前提供 system、gvisor 与 mixed 三种 TUN 协议栈，官方文档在没有特殊兼容问题时建议 mixed。strict-route、auto-route、dns-hijack 与 auto-detect-interface 还会因 Windows、macOS、Linux 和 Android 行为不同而需要分别测试。

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

Proxy Providers 管理可更新的代理集合，Rule Providers 管理可被 RULE-SET 引用的规则集。将两者从主 Profile 拆开后，可以独立控制更新周期、文件路径、规则格式、过滤和健康检查。

rule-providers.yaml — 远程规则集
rule-providers:
  direct:
    type: http
    behavior: domain
    format: yaml
    path: ./ruleset/direct.yaml
    url: https://example.com/rules/direct.yaml
    interval: 86400
rules.yaml — 通过 RULE-SET 引用 Rule Provider
rules:
  - 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

Provider 与 FlClash“资源”页面的关系

Mihomo Core 负责加载和更新 Providers；FlClash 的 Resources / Providers 界面负责把这些外部资源状态、更新时间和节点或规则内容可视化。

Mihomo External Controller：REST / WebSocket 外部控制接口

FlClash 当前默认关闭 External Controller；开启后使用 127.0.0.1:9090。Mihomo API 可读取版本、运行配置、代理、Providers、Rules、Connections、Logs 和 Traffic，也可以切换 Selector、更新 Provider 或修改部分运行配置。

config.yaml — 开启本机 External Controller 与 secret
external-controller: 127.0.0.1:9090
secret: "replace-with-a-strong-secret"
curl — 读取 Mihomo 版本与运行配置
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 — 查看代理并切换 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 — 触发 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 操作。FlClash 打开该功能时当前使用 127.0.0.1:9090；如自行改为其他监听地址，应同时配置 secret、网络访问限制和防火墙，不应直接暴露到公网。

FlClash 的 Dashboard / Core 通信是否等于这个 API？

不等于。桌面端 FlClash 与 Core 之间使用内部 socket/JSON 通信，Android 通过 FFI；External Controller 是 Mihomo 可选的外部 REST / WebSocket 控制面。FlClash 当前生成运行配置时还会清空 external-ui 与 external-ui-url，因此不要把内置 Web Dashboard 当作 FlClash 默认插件接口。

开发集成边界：FlClash UI、Core IPC 与 Mihomo API

开发前先确认要控制哪一层：FlClash 是多平台 GUI 与系统集成层；Mihomo 是代理、Rules、DNS、TUN 和 Provider 的执行核心；External Controller 是 Mihomo 面向外部脚本与 Dashboard 的可选 API。FlClash 内部 IPC 不是稳定公开的第三方插件协议。

1. 不要把 FlClash 内部 Core IPC 当公开 REST API

桌面端 Core 以独立进程运行，FlClash 通过内部 socket 交换 JSON；Android 则通过 FFI 调用共享库。这些接口服务于客户端自身实现，不应与 Mihomo External Controller 混用。

2. 自动化控制优先使用当前 Mihomo API 文档

读取 /version、/configs、/proxies、/rules、/connections、/providers/proxies 等状态，或切换 Selector、更新 Provider 时，应按当前 Mihomo API 的 HTTP 方法和返回结构编写脚本。

3. 配置扩展使用 FlClash Override / Override Script 术语

FlClash 当前提供标准覆写、附加规则和 Override Script。多 Profile 合并并不是当前已经完成的官方核心能力，因此开发文档不应把 Merge 当作既有配置层。

4. 浏览器 Dashboard 还需要考虑 CORS 与 secret

远程网页 Dashboard 连接本机 External Controller 时，除了 Bearer secret，还可能需要配置 external-controller-cors。应限制允许的来源，而不是为了方便长期使用无限制的通配配置。

config.yaml — 更保守的本机 External Controller
external-controller: 127.0.0.1:9090
secret: "replace-with-a-strong-secret"

# 仅在确有浏览器 Dashboard 需求时配置 CORS。
# 不要把 API 监听地址和 secret 暴露在公开网页或客户端代码中。

FlClash、Mihomo Core、配置与 External Controller

FlClash 开发与 Mihomo API 常见问题

这些问题用于区分 FlClash 自身实现、最终 Mihomo 配置和可选 External Controller，避免把 GUI、内部 IPC 和公开控制 API 混为一层。

FlClash 有独立的公开 REST API 吗？+

当前项目没有把 FlClash 自身定义为独立 REST API 服务。桌面端客户端与 Core 通过内部 socket/JSON 通信，Android 通过 FFI。需要外部脚本或 Dashboard 控制时，应使用显式开启的 Mihomo External Controller。

FlClash 的 Profile 与最终 Mihomo 配置是什么关系？+

Profile 是配置来源。FlClash 会结合当前界面设置、DNS/TUN 选项、Override、Override Script 和附加规则生成最终运行配置，再由 Mihomo Core 加载。排错时应比较最终生效配置，而不是只看订阅源文件。

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

客户端可能使用不同的 Mihomo 版本、默认值、覆写逻辑、系统代理实现、TUN 权限与 DNS 设置。即使原始 YAML 相同，最终传给 Core 的配置和系统网络环境也可能不同。

External Controller 可以直接暴露到公网或网页前端吗？+

不建议。该接口能够读取运行状态并执行策略切换、配置修改和 Provider 操作。应优先绑定本机地址，设置 secret，并在需要远程访问时叠加可信网络、防火墙、反向代理鉴权和严格的 CORS 来源限制。

FlClash / Mihomo

继续配置 FlClash，或按 Mihomo API 开发外部控制

下载页负责 Android、Windows、macOS 与 Linux 安装包；配置教程负责 Profile、系统代理和 TUN。需要脚本化读取状态、切换策略组、管理 Providers 或查看 Connections 时，再使用显式开启并受保护的 Mihomo External Controller。

前往下载页面 服务条款