跳到主内容

external-ui 与 external-ui-url:让内核自带 Web 面板

三个字段分工明确:external-ui 指定面板文件所在目录,external-ui-name 加一层子目录,external-ui-url 给出更新用的下载地址。

01这三个字段在做什么

Clash 内核可以开一个外部控制接口。配置了 external-ui 之后,这个接口会把一个目录里的静态网页文件,放在 /ui 路径下提供出来。那些静态文件通常就是一套 Web 面板,用浏览器打开就能管理节点和连接。

三个字段都属于配置顶层,出自 mihomo 文档的通用配置部分。

02external-ui:面板目录

文档对 external-ui 的描述是:通过 API 的 /ui 路径提供静态网页文件,路径可以是完整路径,也可以是相对 Clash 工作目录的路径。

external-ui: /path/to/ui/folder

这里有一条容易漏的限制:如果路径不在工作目录之内,需要把它加进环境变量 SAFE_PATHS。文档说明,条目之间用系统的 PATH 分隔符,Windows 是分号,其他系统是冒号。不加的话,内核可能不认这个目录。文档没有写不加时的具体报错,所以遇到面板打不开,先检查路径是不是在工作目录外。

文档没有写 external-ui 的默认值,不配置就不会提供 /ui。

03external-ui-name:多一层子目录

external-ui-name 是可选的。文档写它指定 external-ui 里的一个子文件夹,用来放置面板更新;不设置的话,更新直接放进 external-ui 目录。

external-ui-name: xd

文档示例的注释写,这样会合并到 external-ui/xd。这个字段适合想同时保留多套面板的人:每套放在自己的子目录,互不覆盖。

04external-ui-url:更新用的下载地址

external-ui-url 是面板压缩包的下载地址。文档示例用的是 metacubexd 项目 gh-pages 分支的压缩包:

external-ui-url: "https://example.com/ui-package.zip"

上面的地址是占位写法,实际使用时填你信任的面板项目提供的压缩包地址,文档示例指向的是 metacubexd 项目。文档同样没有写这个字段的默认值。

这个字段配合 external-ui 使用:内核更新面板时,会从该地址下载压缩包,放入 external-ui(或其下 external-ui-name 指定的子目录)。

05三个字段怎样配合

字段作用是否必须
external-ui面板文件目录,/ui 路径指向它想用内置面板就要写
external-ui-name目录下的子文件夹可选
external-ui-url面板压缩包下载地址想让内核更新面板时才需要

最小可用的配置只有 external-ui;想让面板能自动更新,再加 external-ui-url;想保留多套,再加 external-ui-name。

06用了客户端,还要写这些吗

图形客户端(如 Verge)本身带界面,不需要你再配 Web 面板。external-ui 这类字段更多用在命令行直接跑内核,或路由器、服务器上没有图形界面的场景。客户端与内核的分工见 Clash Verge 和 mihomo 的关系。

面板打不开时,除了路径之外,还要排查外部控制接口本身有没有启动,以及端口有没有被占用,见 客户端打不开的日志检查。

07面板包的来源要自己判断

external-ui-url 会让内核从一个地址下载并放入文件,所以地址是否可信由你负责。建议只填面板项目自己发布页或仓库给出的压缩包,不要用来路不明的链接。路由器等设备上尤其如此,因为面板文件直接跑在管理接口里。

配置文件整体怎么备份和迁移,可参考 Clash 配置备份与迁移,面板目录也要算在迁移范围内。

常见问题

external-ui 路径写在工作目录外怎么办?

+

文档要求把该路径加入环境变量 SAFE_PATHS。多个路径用系统的 PATH 分隔符分开,Windows 用分号,其他系统用冒号。不加时内核可能不认这个目录。

external-ui-name 一定要写吗?

+

不用。它是可选字段,不设置时面板更新直接放进 external-ui 目录。需要同时保留多套面板时,才用它给每套各开一个子目录。

external-ui-url 没写会怎样?

+

内核不知道去哪里下载面板包,但只要 external-ui 指向的目录里已经有面板文件,/ui 仍可以提供。文档没有写 external-ui-url 的默认值,这个字段只影响更新。

还没确定从哪一步开始,可把 从安装开始的操作教程 与 设备对应的软件档案 配合阅读。已有配置但访问失败时,转到 连接异常的分类检查 找对应表现。