Clash 控制器

Clash 控制器（Clash / mihomo RESTful API）

通过 clash-cli（封装 Clash RESTful API）在 Minis 内实时监控和控制 Clash / Mihomo。Clash 配置语法请参考官方文档，本文档只管运行态操作。

1. 入口授权（前提检查）

• Clash 必须正在运行（VPN / 代理开启），external-controller 才会监听端口。未启动时 clash-cli 报「连接失败」。
• 默认 API 地址 http://127.0.0.1:9090（本机 localhost）。
• secret 从环境变量 CLASH_SECRET 读取；未设置则免认证直接访问。
• 入口检查：clash-cli status 能返回版本、模式、内存、策略组即通过。

bashCopy code
clash-cli status
# mihomo 1.19.32  meta=True
# mode=rule  mixed-port=7890  tun=True stack=gVisor
# 内存 31MB  inuse=0KB
# 策略组 13 个：
#   PROXY → AUTO

2. 状态检查

3. 常用任务

• 查当前选中节点：clash-cli proxy get <组>（如 PROXY）
• 切换节点/策略：clash-cli proxy set <组> <节点>（组内任意成员名，含 DIRECT）

  bashCopy code
  clash-cli proxy set PROXY DIRECT    # 直连
  clash-cli proxy set PROXY AUTO      # 切回自动测速组
  

• 节点测速：clash-cli test <节点名> [url] [timeout_ms]；对组内全部节点测速 clash-cli grouptest <组名> [url] [timeout_ms]
• DNS 查询：clash-cli dns query <域名> [type]（走 mihomo 内部 DNS，返回 Answer 数组）
• 日志：clash-cli logs [秒数] [level]（SSE，默认 3 秒）
• 规则命中分析：mihomo 无 rule match 端点，看每连接命中规则用 clash-cli connections（最后一列显示匹配的规则名）

4. 影响边界（写操作）

• 写操作：proxy set、conn close <id|all>、reload、PATCH /configs 会改变运行状态，执行前先确认目标名存在（proxy get）。
• conn close all 会断开全部连接（SSH/下载会被打断）。
• reload 重载配置可能导致短暂断线，配置改动应先备份再 reload。
• 若配置文件含节点订阅密码等敏感信息，务必只备份到私有仓库，绝不推公共仓库。

5. 环境与安全注意事项

• external-controller 默认绑定 127.0.0.1 即可本地访问。
• 勿改 0.0.0.0 绑定（allow-lan: true 且无 secret 时，局域网内可被访问，有风险）。如确需远程访问，务必设置 secret。
• 环境变量：CLASH_API（默认 http://127.0.0.1:9090）、CLASH_SECRET、CLASH_TIMEOUT（默认 8 秒）。
• 切换节点时节点名必须与策略组成员精确匹配（含空格/emoji/特殊字符，如「🇭🇰香港trojan1」）。
• 实测确认：mihomo 的 /traffic、/memory 是裸 JSON 流（无 data: 前缀），/logs 为标准 SSE，解析需兼容两种格式。

6. 社区 CLI 备选：mihomosh（可选）

mihomosh 是社区为 Mihomo 写的命令行工具包（Rust，MIT），可覆盖几乎全部外部控制 API，作为本技能自带 clash-cli 脚本的补充/对照实现。

• 安装：GitHub Release 下载对应平台预编译二进制，解压后放 PATH（如 /usr/local/bin/mihomosh）。
• 配置：~/.local/share/mihomosh/config.yaml
  • mihomo-api: http://127.0.0.1:9090（Clash 控制端口）
  • mihomo-path: <你的 clash 配置路径>（Clash 配置副本）
• 常用命令：

  bashCopy code
  mihomosh proxy view        # 查看全部节点/策略组
  mihomosh proxy update     # 切换代理
  mihomosh proxy test        # 批量测速
  mihomosh rule view          # 查看规则
  mihomosh connection list    # 实时连接
  mihomosh inspect version    # 内核版本
  

• 注意事项：
  • Clash 未运行时控制端口无监听，mihomosh 报 Connection refused，属正常（开着才能用）。
  • 社区 CLI 本质仍是 HTTP API 客户端包装，能力边界 = API 边界（如内核禁止的端点，mihomosh 同样做不到）。

7. 安装方式

clash-cli 是独立 Python3 脚本（仅标准库），但作为 Minis 技能使用时需放进技能目录才能被自动发现。按环境选一种：

① Minis 内自动安装（推荐） 把本技能的 SKILL.md 的 GitHub URL 粘贴到 Minis 对话，智能体会自动拉取安装：

Copy code
https://github.com/openminis/MinisSkills/blob/main/clash-controller/SKILL.md

② git 克隆 + 软链（Minis 技能目录）

shCopy code
git clone https://github.com/openminis/MinisSkills ~/.minis-skills
ln -s ~/.minis-skills/clash-controller ~/.minis/skills/clash-controller

iOS 上 Minis 技能目录实际为 /var/minis/skills；macOS/其他环境可能是 ~/.minis/skills 或对应配置路径，以 Minis 设置中显示的技能目录为准。

③ 手动解压 下载本技能目录（zip）后解压到技能目录：

shCopy code
unzip clash-controller.zip -d ~/.minis/skills/

④ 仅用脚本（不装技能，任何有 Python3 的机器） scripts/clash-cli 可单独使用，只需本机运行着 Clash 且 external-controller 在监听：

shCopy code
chmod +x clash-cli
./clash-cli status
# 远程/带 secret：
# export CLASH_API=http://<IP>:9090 CLASH_SECRET=<你的secret>
# ./clash-cli status

验证安装

shCopy code
clash-cli status   # 返回版本/模式/策略组即成功；报「连接失败」说明 Clash 未运行或端口未开

参考资料（来源）

• mihomo（MetaCubeX）GitHub：https://github.com/MetaCubeX/mihomo
• mihomo Wiki：https://wiki.metacubex.one/
• Clash 原始 RESTful API 文档：https://clash.gitbook.io/doc/restful-api
• mihomosh（SamuNatsu）GitHub：https://github.com/SamuNatsu/mihomosh
• 校验：clash-cli 通过 python3 -m py_compile，核心命令实测通过（status/traffic/connections/rules/proxy get/set/test/dns）