外部控制器（Clash API）

mihomo 实现了 Clash RESTful API。所有 Clash 面板（metacubexd、yacd、 Clash Dashboard）都通过它与 mihomo 通信。本页讲解控制 API 监听位置、 内置 UI 以及 CORS 的一组顶层键。

顶层键

字段	类型	默认值	允许值	描述
external-controller	string	(unset)	<host:port>	RESTful API 的明文 HTTP 监听地址。
external-controller-pipe	string	(unset)	<pipe path>	Windows 命名管道路径。仅当希望 API 只面向同主机本地客户端时在 Windows 上设置。
external-controller-unix	string	(unset)	<socket path>	API 的 Unix 域套接字路径。
external-controller-tls	string	(unset)	<host:port>	TLS 保护的监听地址。需要顶层 `tls` 块携带证书与私钥。
external-controller-cors	RawCors	(unset)	RawCors	HTTP API 的 CORS 允许列表。
external-ui	string	(unset)	<dir path>	本地目录，其中的内容在 /ui 路径下提供。
external-ui-url	string	(unset)	<URL>	当 external-ui 目录为空时，从此 URL 下载 tarball 解压到该目录。
external-ui-name	string	(unset)	<name>	external-ui 下要服务的子目录，便于并排提供多个面板。
external-doh-server	string	(unset)	<path> | <host:port>	在该路径挂载 DoH 端点，让其他设备使用 mihomo 的 DNS 解析器。
secret	string	(unset)	<bearer token>	所有 API 调用所需的 Bearer 令牌。external-controller 绑定到非 loopback 地址时强烈建议设置。

源码： config/config.go:393-460 · 锚定版本 v1.19.27 (5184081)

external-controller-cors

字段	类型	默认值	允许值	描述
allow-origins	[]string	[]	<origin>	源地址允许列表。空列表表示仅同源。
allow-private-network	bool	false	true | false	允许私有网络的 preflight 请求，便于私有 LAN 上的面板访问 API。

源码： config/config.go:213-216 · 锚定版本 v1.19.27 (5184081)

示例

external-controller: 127.0.0.1:9090
external-controller-cors:
  allow-origins:
    - https://metacubex.github.io
    - http://localhost:5173
  allow-private-network: true
external-ui: /etc/mihomo/ui
external-ui-url: https://github.com/MetaCubeX/metacubexd/archive/refs/heads/gh-pages.zip
external-ui-name: metacubexd
secret: <random-string-here>

说明

• external-controller 绑定到非 loopback 地址时，务必 设置 secret 和 / 或 external-controller-tls。该 API 能改变守护进程 的任何路由决策。
• external-ui 仅是文件服务 —— 除了 CORS 之外没有任何额外安全机制。 多数用户从 localhost 提供面板，并在同主机浏览器中访问。
• external-controller-pipe（Windows）与 external-controller-unix （Linux / macOS）在只希望同主机客户端能访问 API 时很有用；可配合 文件系统 ACL 使用。

源码： config/config.go:213-460 · v1.19.27 (5184081)