Clash中文信息网external-controller是Clash内置的管理API接口，通过该接口可以实现对Clash运行状态的完整控制，包含节点切换、配置重载、连接监控和流量统计等核心管理功能。在配置文件中将external-controller设置为127.0.0.1:9090即可启用该接口，需要远程管理时改为0.0.0.0:9090并配合secret密钥提高安全性。接口启用后，在浏览器中访问http://127.0.0.1:9090/ui可以加载Yacd或Metacubexd等管理面板，实现图形化的节点管理和流量查看。在命令行环境中，通过curl -X GET http://127.0.0.1:9090/proxies可以查询当前所有策略组和节点的状态，通过curl -X PUT -d '{"name":"节点名"}' http://127.0.0.1:9090/proxies/策略组名可以实时切换节点而无需重启Clash或编辑配置文件。如果管理面板无法连接，首先检查http://127.0.0.1:9090/version能否返回JSON响应，如果不能则说明external-controller未正确启用或端口被占用。
基本定义：RESTful API管理接口
接口在配置文件中的声明方式
external-controller是Clash配置文件中用于启用RESTful API管理接口的顶层字段，通过指定IP地址和端口号来定义管理服务的监听地址。典型的配置写法为external-controller: 127.0.0.1:9090，表示管理接口监听在本机回环地址的9090端口上。配置该字段后，Clash核心会启动一个HTTP服务器，对外提供RESTful API接口，允许外部程序通过HTTP请求查询和修改Clash的运行状态。如果配置文件中未声明该字段，Clash默认不会开启管理接口。
管理接口的核心功能定位
external-controller提供的API接口是Clash与外部管理工具之间的桥梁，它允许用户在不直接修改配置文件或重启Clash的情况下，动态调整代理的运行参数。通过这个接口可以获取当前节点列表、切换选中的节点、查看实时连接状态、更新订阅配置以及获取流量统计信息。这个接口的存在使得Clash能够被图形化管理面板（如Yacd、Metacubexd）或自动化脚本所控制，是Clash可运维性的核心组件。
RESTful API的基本调用方式
RESTful API通过标准的HTTP方法（GET、POST、PUT、DELETE）进行调用，请求路径对应不同的管理功能。例如GET /proxies请求可以获取所有策略组和节点的信息，PUT /proxies/策略组名可以切换策略组中的选中节点。请求返回的数据格式为JSON，便于程序解析和处理。如果需要通过命令行快速查询Clash状态，可以使用curl命令直接调用这些API接口而无需打开图形界面。
在配置文件中的标准配置与参数说明
监听地址与端口的选择策略
external-controller字段的配置格式为IP:端口，其中IP地址决定了管理接口监听在哪个网络接口上。设置为127.0.0.1:9090时，管理接口仅允许本机访问，外部设备无法连接，这是默认且最安全的配置。设置为0.0.0.0:9090时，管理接口监听所有网络接口，局域网内的其他设备也可以通过本机的局域网IP访问管理面板，适合需要在手机或平板上管理Clash的场景。端口号可以选择任意未被占用的端口，推荐使用9000以上的端口避免与常用服务冲突。
secret密钥参数的安全配置
external-controller接口可以配合secret字段设置访问密钥，增强管理接口的安全性。在配置文件中添加secret: "自定义密码"后，所有访问管理接口的请求都需要在HTTP头部携带Authorization: Bearer 自定义密码才能通过认证。如果没有设置secret，管理接口默认不设防，任何能访问该IP和端口的人都可以获取和修改Clash的配置信息。在生产环境或局域网共享场景中，强烈建议设置secret密钥以防未授权访问。
配置修改后的生效方式
修改external-controller或secret字段后，需要让Clash重新加载配置才能生效。在图形客户端（如Clash for Windows）中修改配置文件保存后，客户端通常会自动重载配置。在命令行或systemd服务方式下，需要重启Clash进程或发送SIGHUP信号触发配置重载。修改生效后，可以通过访问http://127.0.0.1:9090/version测试API是否可访问——如果返回包含版本信息的JSON响应，说明管理接口已正常启动。
API接口的核心功能与常用调用场景
获取和切换代理节点
通过external-controller接口，用户可以无需打开客户端界面就能获取节点列表和切换节点。调用GET /proxies可以获取所有策略组的详细信息，包括每个策略组下的可选节点列表和当前选中的节点。调用PUT /proxies/{策略组名}并在请求体中指定新的节点名称，可以实时切换该策略组使用的节点。这种操作方式非常适合集成到自动化脚本中，例如根据时间段自动切换节点或结合网络质量监测实现故障转移。
查询实时连接状态与流量统计
GET /connections接口可以获取当前所有活跃的网络连接信息，包括每个连接的目标地址、使用的代理节点、传输的数据量以及连接持续时间。这个接口是图形化管理面板展示实时流量图的底层数据来源。GET /traffic接口提供实时的流量速率统计，返回每秒的上传和下载速率数据，可用于制作流量监控看板。这些接口在排查网络问题或监控代理使用情况时非常有用，比登录服务器查看日志更加直观高效。
管理配置与触发订阅更新
PUT /configs接口允许在不重启Clash的情况下动态更新配置，请求体中携带新的配置内容即可完成热加载。POST /configs接口触发Clash重新加载现有配置，适用于订阅链接已更新但Clash未自动拉取的情况。通过这些接口可以实现配置的自动化管理——例如编写定时任务从订阅链接拉取最新配置，然后通过API推送到正在运行的Clash实例中，实现无需人工介入的配置更新。
图形化管理面板的访问方式
Yacd面板的部署与访问
Yacd（Yet Another Clash Dashboard）是最常用的Clash图形化管理面板之一，通过external-controller接口与Clash核心通信。用户可以通过浏览器访问http://127.0.0.1:9090/ui来加载Yacd面板（前提是面板文件已放置在Clash配置目录的ui子目录中）。如果Clash配置中未包含UI静态文件，也可以从GitHub下载Yacd的发布版本，解压到配置目录中。面板加载后会自动连接external-controller接口，展示节点列表、连接状态和流量信息。
Metacubexd面板的接入方式
Metacubexd是Clash Meta生态中推荐的现代化管理面板，支持更丰富的节点信息和流量展示。接入方式与Yacd类似，需要将面板静态文件下载到Clash配置目录的ui文件夹中，Clash会自动托管这些文件并通过external-controller接口提供数据。Metacubexd面板在Clash Verge Rev等新版客户端中已经内置，用户无需手动部署即可通过菜单栏的“Dashboard”或“管理面板”入口直接访问。在浏览器输入http://127.0.0.1:9090/ui如果页面能正常加载，说明面板已正确配置。
面板连接失败时的排查要点
访问管理面板时如果显示“连接失败”或“无法连接到API”，首先检查external-controller是否已在配置文件中正确配置且Clash正在运行。确认http://127.0.0.1:9090/version能否返回JSON响应，如果不能则说明管理接口未正常启动或端口被其他服务占用。如果配置了secret密钥，需要在面板的设置页面中填入正确的密钥才能完成认证。端口号与配置文件中的声明不一致也是常见原因，检查面板配置中的API Base URL是否与配置文件中的external-controller端口匹配。
通过命令行工具调用API接口
使用curl命令获取代理状态
curl是最常用的命令行API调用工具，可以直接从终端查询和修改Clash状态。curl -X GET http://127.0.0.1:9090/proxies会返回所有策略组的完整信息，包括节点列表和当前选中节点。curl -X GET http://127.0.0.1:9090/proxies/策略组名可以查看特定策略组的详细信息。如果设置了secret密钥，需要在请求中添加-H "Authorization: Bearer 你的密钥"头部进行认证。这些命令在服务器运维场景中可以快速确认代理状态，不需要登录图形界面。
使用PUT请求切换代理节点
通过curl发送PUT请求可以实时切换策略组中的节点。命令格式为curl -X PUT -H "Content-Type: application/json" -d '{"name":"节点名称"}' http://127.0.0.1:9090/proxies/策略组名，其中节点名称必须是该策略组proxies列表中存在的节点名。执行成功后，Clash会立即将所有匹配该策略组的流量切换到指定的节点。这种操作方式在自动化脚本中非常实用，可以实现基于规则或时间表的自动节点切换。
使用API进行自动化脚本编写
external-controller接口提供了完整的自动化管理能力，用户可以将多个API调用组合成脚本实现复杂的运维逻辑。例如编写Shell脚本定期调用GET /proxies获取所有节点的延迟信息，当检测到当前节点延迟过高时自动切换到延迟最低的节点。或者编写脚本在订阅更新后自动调用POST /configs让Clash重新加载配置。这种自动化能力将Clash从纯手工操作的工具提升到了可编程管理的平台层面。
安全配置与公网暴露防护
绑定到127.0.0.1的本地访问限制
将external-controller设置为127.0.0.1:9090是限制访问的最直接方式，这样管理接口只能被本机进程访问，外部网络无法连接。这是最安全的基本配置，适用于单机使用且不需要远程管理的场景。即使是本机访问，如果系统中存在其他恶意进程，理论上也可以探测并调用该接口，因此仍需考虑额外安全措施。
secret密钥的强制启用
无论是否将管理接口绑定到127.0.0.1，都强烈建议为external-controller设置secret密钥。密钥应使用强密码（长度大于16位，包含大小写字母、数字和特殊字符），避免使用常见的弱口令。设置了密钥后，所有API请求都需要携带正确的认证头信息，即使管理接口被错误地暴露到公网，攻击者在没有密钥的情况下也无法执行任何操作。某些版本的Clash客户端在面板连接时会要求输入密钥，输入正确后才能加载数据。
通过Nginx反向代理增加认证层
对于需要远程管理Clash的场景，可以使用Nginx作为反向代理在external-controller之前增加一层认证。Nginx可以配置HTTP基本认证或更复杂的认证方式，并将请求转发到Clash的管理接口。这种方式的优势在于可以利用Nginx更强大的访问控制能力（如IP白名单、限流、请求日志等），同时避免将Clash的管理接口直接暴露在网络中。配置时需要注意Nginx与Clash之间的通信路径，确保两者在同一网络可达。
常见问题 FAQ
external-controller和external-ui之间有什么关系？
external-controller定义管理API的监听地址和端口，external-ui指定管理面板静态文件存放的目录名称。Clash通过external-controller提供API数据，同时托管external-ui目录中的静态网页文件，用户在浏览器访问http://IP:端口/ui时即可加载面板页面。两者配合使用才能提供完整的可视化管理体验。
external-controller的API接口需要认证吗？
默认不需要。但如果配置文件中设置了secret字段，所有API请求必须在HTTP头部携带该密钥才能通过认证。即使绑定在127.0.0.1，也建议设置secret以增加一层安全保护。未设置认证的管理接口如果暴露到局域网或公网，存在被未授权访问的风险。
可以通过external-controller API切换订阅配置吗？
可以。调用PUT /configs并携带新的配置内容可以热加载配置，调用POST /configs可以重新加载当前配置文件。也可以通过PUT /configs触发订阅更新流程，让Clash从订阅链接重新拉取配置。这些操作无需重启Clash进程即可生效。
外部设备如何通过API访问本机的Clash管理面板？
首先将external-controller的监听地址设置为0.0.0.0:9090而非127.0.0.1:9090，并确保防火墙放行了9090端口的入站连接。然后在外部设备的浏览器中输入http://本机局域网IP:9090/ui访问面板。同时建议在配置文件中设置secret密钥以防止未授权访问。