本帖最后由 myhades 于 2025-2-12 14:12 编辑
[Custom Integration] Home Assistant Clash Controller
logo
Home Assistant Clash Controller 是一个用于控制外部 Clash 的 HA 集成，通过其 RESTful API 进行交互。
该集成使用的 API 与 yacd 等面板相同，且源项目似乎已更名为 Mihomo。
请注意，这个集成并不是 Clash 本身，而是一个 Clash 控制器，与网页面板本质上没有区别，你仍然需要先部署 Clash 才能使用该集成。
开发这个集成的目的只是为了更方便、自动化地管理 Clash 流量。
这是我第一个 Python 兼 Home Assistant 项目，因此可能存在一些缺陷，非常感谢任何试用和反馈！
集成做了 ConfigFlow 可以使用图形界面方便的添加，不需要修改配置反复重启 HA
如果你觉得不错也欢迎为我的仓库点个⭐Star
项目地址： https://github.com/myhades/ha-clash-controller
config_flow
device_page
当前的使用场景主要针对利用Clash，OpenClash，MerlinClash等进行全屋流量魔法的配置，通过该集成，你可以方便的：
1) 让家里人使用HA快速完成节点切换，而不必亲自动手或者进行yacd教学；
2) 自动检测当前魔法情况，根据延迟或者连接情况自动更改节点（鉴于Clash本身就是根据策略和延迟的分流魔法软件，所以这个主要针对于自定义一些连接测试，可能要求HA本身魔法）；
3) 实现流媒体解锁检测和切换（这个后续更新进集成，同样要求HA本身魔法）；
4) 利用提供的services进行一些进阶网络诊断，包括按关键词获取规则，获取/终止连接，DNS查询等。
1. 支持的 Clash
该集成适用于大多数 Clash 客户端。
已知可用：OpenClash、ShellClash 和 MerlinClash。
核心支持情况： | 内核名称 | 支持情况 | |------------------|-----------| | Clash | 部分 | | Clash Premium | 部分 | | Clash Meta | 完全 |
请确保启用了 external controller 选项，并设置了 token。（这个一般不用担心，网页面板能用这个集成就能用）
2. 安装
请进入本项目仓库 https://github.com/myhades/ha-clash-controller。
方式 1：通过 HACS 安装
1) 点击Open HACS图标，同意添加库，下载安装并重启；
2) 点击Add Integration图标，搜索"Clash Controller"，按UI说明添加。
方式 2：手动安装
下载仓库文件，并将 custom_components/clash_controller 文件夹复制到 Home Assistant 的 config/custom_components 目录下。
3. 配置
1）进入 Home Assistant，添加新集成，搜索并点击 "Clash Controller" ；
2）填入Clash 的地址（如192.168.1.1:9090）和 Bearer Token（配置的管理密码）。
注意事项：
1）如果找不到集成，确认装上了的话可以清除浏览器缓存试试；
2）如果 API 是 IP（如 192.168.1.1:9090），确保是静态 IP 或在路由器上添加 DHCP 静态租约（MAC地址绑定），否则 IP 变化后需要重新添加集成。使用IP不要勾选使用HTTPS；
3）如果 API 是域名（如配置了反代用域名连接，clash.mydomain.com），则视情况勾选https和允许不安全证书。（自签名证书则需要勾上，除非系统信任了CA）
4. 使用
以下实体和服务的可用性取决于所使用的 Clash 核心。
1. 实体支持
1）策略组相关（实体属性包含对应策略组的所有节点和延迟信息）
- 策略组传感器 - 对于 URLTest 组
- 策略组选择器 - 对于 Fallback, Selector 组
2）流量相关
3）系统信息
- 活跃连接数传感器
- 内存信息传感器
- FakeIP 缓存清除按钮
2. 服务支持
services
获取可用代理列表的服务示例：
action: clash_controller.api_call_service
data:
device_id: [YOUR_DEVICE_ID]
api_endpoint: proxies
api_method: GET
response_variable: proxy_data
3. 其他功能
该集成提供基本的流媒体可用性检测。
要使此功能正常运行，Home Assistant 必须通过正在测试的代理进行连接。此功能默认关闭。 要启用/禁用此功能，请导航至 设置 > 设备与服务 > Clash Controller > 选项。 当前支持的流媒体服务： Netflix。
5. 反馈 如果遇到问题，请提供 Clash 配置详情，并附上该集成的调试日志。 您可以在 Home Assistant UI 中启用调试日志（若支持），或在配置文件中添加以下内容：
logger: default: warning logs: custom_components.clash_controller: debug custom_components.clash_controller.sensor: debug
6. 免责声明
本项目不提供任何 Clash 订阅、代理或节点，仅用于 Clash API 控制。我不对 Clash 及其使用方式的合法性、准确性、适用性提供任何担保。
使用本集成即表示你已阅读并同意本免责声明。
7. 附录
由于 Clash 或者 OpenClash 均不提供启动状态的控制接口，若需要控制 OpenClash 开关，可以使用如下方法：
1）开启 OpenWRT 的 SSH 并生成密钥，然后保存到 Home Assistant 的"/config/sshkeys/"目录下（没有则新建）
2）使用 Shell Command 集成添加通用 SSH 命令执行服务:
shell_command:
ssh_by_key: `>-`
ssh -o StrictHostKeyChecking=no -o PubkeyAcceptedKeyTypes=+ssh-rsa -o HostKeyAlgorithms=+ssh-rsa -i {{ key_path }} {{ user }}@{{ location }} {{ "-p "+port|string if port is defined }} {{ command }}
3）利用如下示例调用服务：查询 OpenClash 状态
metadata: {}
data:
location: [YOUR_OPENWRT_IP]
user: root
key_path: /config/sshkeys/[YOUR_KEY]
port: [YOUR_SSH_PORT]
command: uci get openclash.config.enable
response_variable: ssh_result
action: shell_command.ssh_by_key
关闭 OpenClash
metadata: {}
data:
location: [YOUR_OPENWRT_IP]
user: root
key_path: /config/sshkeys/[YOUR_KEY]
port: [YOUR_SSH_PORT]
command: \>-
uci set openclash.config.enable=0; uci commit openclash;
/etc/init.d/openclash stop
response_variable: toggle_result
action: shell_command.ssh_by_key
启动 OpenClash
metadata: {}
data:
location: [YOUR_OPENWRT_IP]
user: root
key_path: /config/sshkeys/[YOUR_KEY]
port: [YOUR_SSH_PORT]
command: \>-
uci set openclash.config.enable=1; uci commit openclash;
/etc/init.d/openclash start
response_variable: toggle_result
action: shell_command.ssh_by_key
注意，由于论坛md渲染问题，请将以上代码中的“command: \>-”一行在粘贴后更改为"command: >-"
| 
发表于 2025-2-4 00:35:26
楼主
