Clash 外部控制器 (External Controller) 配置与 RESTful API 调用教程:自建 Web 面板与远程节点切换

一、轻量化极客的终极形态:内核与 UI 解耦

在很多开发者的工作流中,原版的 Clash 图形客户端越来越重,动辄消耗几百兆内存。

更麻烦的是,如果你把 Clash 部署在家里的 Linux 软路由、NAS 或者无显示器的开发机上,根本没有图形桌面让你用鼠标去点选节点。

很多人不知道,Clash 内核本身是一个彻底遵循“前后端分离”的现代化网络引擎。

它在后台静默运行时,可以通过内置的 External Controller(外部控制器) 暴露出一套功能完备的标准 RESTful HTTP API。

只要开放这个接口,你可以用任何设备的浏览器打开开源的 Web 仪表盘(如 Yacd 或 Metacubexd),实时查看上行下行速率、一键批量测速、甚至用一句简单的 `curl` 命令在终端里自动化切换当前节点。

二、在 YAML 配置文件中开启外部控制器

步骤 1:定位核心配置块

用文本编辑器打开你的 Clash 核心配置文件(`config.yaml`)。

在最顶部的全局配置区域,找到或手动添加以下三行核心参数:

# 外部控制器监听的 IP 与端口(0.0.0.0 代表允许局域网其他设备访问;若仅本地访问写 127.0.0.1)
external-controller: 0.0.0.0:9090

# 访问控制器必须携带的 API 鉴权密钥(务必设置强密码,防止内网他人未授权调用)
secret: "MySecureClashKey2026"

# 可选:内置静态 Web 面板的存储路径(方便直接通过 http://ip:9090/ui 访问)
external-ui: "dashboard"

步骤 2:启动并验证端口监听

保存配置文件并启动 Clash 内核。

在终端中执行端口检查命令,确认 9090 端口已正常对外守候:

# Linux / macOS 验证命令
netstat -tlunp | grep 9090

# Windows 验证命令
netstat -ano | findstr :9090

如果显示 `LISTEN` 状态,说明 RESTful 控制引擎已在后台就绪。

三、接入开源 Yacd Web 仪表盘实操

Yacd网页仪表盘通过RESTful API成功连接并管理本地Clash核心界面

方式一:使用纯纯净在线 Web 仪表盘接入(最快捷)

无需在本地部署任何 Web 服务器,直接使用纯前端运行的开源仪表盘:

在电脑或手机浏览器中访问开源托管的 Yacd 面板(如 `http://yacd.haishan.me` 或 `https://yacd.metacubex.one`)。

在弹出的「API Configuration (添加连接)」对话框中填入:

  • API Base URL:如果是在本机访问,填写 `http://127.0.0.1:9090`;如果是局域网其他电脑访问软路由,填写软路由的内网 IP(如 `http://192.168.1.1:9090`);
  • Secret:填入你在 YAML 里设置的密钥字符串(如 `MySecureClashKey2026`)。

点击 「Add」。面板立刻连接成功:屏幕顶部实时刷新当前下行带宽折线图,中间整齐列出所有策略组与节点卡片,点击任何节点直接毫秒切换。

四、利用 cURL 命令行实现极客级自动化运维

除了网页点击,你还可以将节点切换写入自己的定时脚本中:

# 1. 查询当前所有代理节点状态与延迟
curl -X GET "http://127.0.0.1:9090/proxies"      -H "Authorization: Bearer MySecureClashKey2026"

# 2. 命令行一键将某个策略组切换为指定节点(如切换至“日本专线-01”)
curl -X PUT "http://127.0.0.1:9090/proxies/🚀%20节点选择"      -H "Authorization: Bearer MySecureClashKey2026"      -H "Content-Type: application/json"      -d '{"name": "日本专线-01"}'

执行完毕后,不需要刷新任何客户端,底层分流流量瞬间无缝平滑切至全新线路。