Ядро Mihomo поставляется с RESTful API. Собственный интерфейс Clash Verge общается с ядром именно через него — поняв эндпойнты, вы сможете сделать скриптом всё, что умеет интерфейс.
Как включить и чем это грозит
external-controller: 127.0.0.1:9090
secret: "достаточно длинная случайная строка"Сгенерировать случайный secret:
openssl rand -hex 24Аутентификация
Каждый запрос несёт bearer-токен:
curl -H "Authorization: Bearer ваш-secret" http://127.0.0.1:9090/versionЭндпойнты WebSocket (логи, трафик) вместо этого принимают параметр запроса:
ws://127.0.0.1:9090/traffic?token=ваш-secretПолная таблица эндпойнтов
| Метод | Путь | Назначение |
|---|---|---|
| GET | /version | Версия ядра |
| GET | /configs | Текущая конфигурация |
| PATCH | /configs | Изменить настройки на лету (порты, режим и прочее) |
| PUT | /configs?force=true | Перезагрузить файл конфигурации |
| GET | /proxies | Все узлы и группы политик |
| GET | /proxies/:name | Подробности по одному узлу или группе |
| PUT | /proxies/:name | Сменить выбранный узел в группе |
| GET | /proxies/:name/delay | Замерить задержку одного узла |
| GET | /group/:name/delay | Проверить всю группу политик |
| GET | /connections | Все текущие соединения |
| DELETE | /connections | Закрыть все соединения |
| DELETE | /connections/:id | Закрыть одно соединение |
| GET | /rules | Действующий список правил |
| GET | /providers/proxies | Все proxy-provider |
| PUT | /providers/proxies/:name | Обновить один провайдер вручную |
| GET | /providers/rules | Все rule-provider |
| PUT | /providers/rules/:name | Обновить набор правил вручную |
| GET | /logs | Поток логов (WebSocket) |
| GET | /traffic | Живой трафик (WebSocket) |
| GET | /memory | Потребление памяти (WebSocket) |
Частые операции
Перечислить все группы политик и текущий выбор
curl -s -H "Authorization: Bearer $SECRET" \
http://127.0.0.1:9090/proxies | jq '.proxies | to_entries[] | select(.value.type=="Selector") | {group: .key, now: .value.now}'Сменить узел
curl -X PUT \
-H "Authorization: Bearer $SECRET" \
-H "Content-Type: application/json" \
-d '{"name":"HK-01"}' \
http://127.0.0.1:9090/proxies/PROXYИмена групп с пробелами или эмодзи нужно кодировать в URL:
GROUP=$(printf '%s' "🚀 Выбор" | jq -sRr @uri)
curl -X PUT -H "Authorization: Bearer $SECRET" \
-d '{"name":"HK-01"}' \
"http://127.0.0.1:9090/proxies/$GROUP"Замерить задержку узла
curl -s -H "Authorization: Bearer $SECRET" \
"http://127.0.0.1:9090/proxies/HK-01/delay?timeout=5000&url=http%3A%2F%2Fwww.gstatic.com%2Fgenerate_204"
# возвращает {"delay":123}Сменить режим прокси
curl -X PATCH -H "Authorization: Bearer $SECRET" \
-H "Content-Type: application/json" \
-d '{"mode":"global"}' \
http://127.0.0.1:9090/configsmode принимает rule, global или direct. Тот же эндпойнт меняет log-level, allow-lan и другие поля.
Перезагрузить конфигурацию
curl -X PUT -H "Authorization: Bearer $SECRET" \
-H "Content-Type: application/json" \
-d '{"path":"/etc/mihomo/config.yaml"}' \
"http://127.0.0.1:9090/configs?force=true"Закрыть все соединения
curl -X DELETE -H "Authorization: Bearer $SECRET" \
http://127.0.0.1:9090/connectionsСмена узла не переносит уже установленные соединения (открытое TCP-соединение продолжает идти через старый узел); эта команда заставляет всё переподключиться.
Обновить провайдер
# обновить подписку с узлами
curl -X PUT -H "Authorization: Bearer $SECRET" \
http://127.0.0.1:9090/providers/proxies/main
# обновить набор правил
curl -X PUT -H "Authorization: Bearer $SECRET" \
http://127.0.0.1:9090/providers/rules/cn-domainПолезные скрипты
1. Автоматически переключаться на узел с наименьшей задержкой
#!/bin/bash
# pick-fastest.sh — проверить и переключиться на самый быстрый узел
set -euo pipefail
API="http://127.0.0.1:9090"
SECRET="ваш-secret"
GROUP="AUTO"
TEST_URL="http%3A%2F%2Fwww.gstatic.com%2Fgenerate_204"
# запустить проверку по всей группе
curl -s -H "Authorization: Bearer $SECRET" \
"$API/group/$GROUP/delay?timeout=5000&url=$TEST_URL" > /dev/null
# найти наименьшую задержку
BEST=$(curl -s -H "Authorization: Bearer $SECRET" "$API/proxies" \
| jq -r --arg g "$GROUP" '
.proxies[$g].all[] as $n
| .proxies[$n]
| select(.history | length > 0)
| select(.history[-1].delay > 0)
| "\(.history[-1].delay) \(.name)"
' | sort -n | head -1 | cut -d' ' -f2-)
echo "самый быстрый узел: $BEST"
curl -s -X PUT -H "Authorization: Bearer $SECRET" \
-d "{\"name\":\"$BEST\"}" "$API/proxies/$GROUP" > /dev/null2. Следить за здоровьем узлов и предупреждать, когда всё упало
#!/bin/bash
# health-watch.sh
API="http://127.0.0.1:9090"
SECRET="ваш-secret"
ALIVE=$(curl -s -H "Authorization: Bearer $SECRET" "$API/proxies" \
| jq '[.proxies[] | select(.type != "Selector" and .type != "URLTest")
| select(.history | length > 0)
| select(.history[-1].delay > 0)] | length')
if [ "$ALIVE" -eq 0 ]; then
echo "$(date '+%F %T') нет пригодных узлов" >> /var/log/mihomo-alert.log
# сюда подключите свой канал уведомлений
fi3. Перечислить самые тяжёлые соединения
curl -s -H "Authorization: Bearer $SECRET" http://127.0.0.1:9090/connections \
| jq -r '.connections
| sort_by(-.download)
| .[:10][]
| "\(.download/1048576 | floor)MB \(.metadata.host // .metadata.destinationIP) \(.metadata.processPath // "-")"'Очень удобно, чтобы выяснить, «что ест мой трафик».
4. Следить за логом вживую
# нужен websocat или wscat
websocat "ws://127.0.0.1:9090/logs?token=ваш-secret&level=info"Развёртывание веб-панели
Панель — это чисто статическая страница, общающаяся с ядром через API.
Вариант А: раздаётся ядром (рекомендуется)
external-ui: /etc/mihomo/ui
external-ui-name: metacubexd
external-ui-url: "https://адрес-релиза-панели/dist.zip"Распакуйте файлы панели в каталог, указанный в external-ui, затем откройте:
http://адрес-ядра:9090/uiПри первом открытии вводите адрес API (http://адрес-ядра:9090) и secret.
Вариант Б: публично размещённая панель
Панель — чистый фронтенд, так что можно взять чью-то размещённую страницу и указать ей адрес вашего API и secret.
Сравнение распространённых панелей
Несколько остроумных применений API
Переключение узлов по расписанию
Уходить на выделенную линию в час пик и возвращаться на обычный узел днём:
# crontab
0 20 * * * /usr/local/bin/switch-node.sh "IPLC-HK"
0 1 * * * /usr/local/bin/switch-node.sh "AUTO"Горячая клавиша (на десктопе)
В паре с AutoHotkey на Windows или Hammerspoon на macOS одна комбинация переключает глобальный режим и режим правил:
# перейти в глобальный
curl -X PATCH -H "Authorization: Bearer $SECRET" \
-d '{"mode":"global"}' http://127.0.0.1:9090/configsПодключение к системе мониторинга
/traffic — эндпойнт WebSocket, каждую секунду отдающий скорость приёма и передачи. Соберите это в базу временных рядов и получите графики трафика.
Диагностика
Быстрая проверка:
curl -i -H "Authorization: Bearer $SECRET" http://127.0.0.1:9090/versionОтвет 200 с JSON версии означает, что всё прошло.
Коротко
- API умеет всё, что умеет интерфейс, включая смену узлов, режима и перезагрузку конфигурации
secretобязателен, особенно при прослушивании на0.0.0.0- Имена групп с пробелами или эмодзи требуют URL-кодирования
- После смены узла не забудьте
DELETE /connections, иначе существующие соединения останутся на старом - Панель — только фронтенд; своя безопаснее сторонней страницы
Смотрите также: Mihomo как домашний шлюз и диагностика трафика и соединений.
Смежные документы
127.0.0.1 внутри контейнера — это не хост. Настройка для всех трёх сценариев Docker (загрузка образов демоном, сборка, запуск) плюс два подхода для разных режимов сети WSL2.
Справочная таблица, которую стоит сохранить. Команда для каждого инструмента, где лежит его файл настроек, как всё отменить и почему часть инструментов игнорирует переменные окружения.
Нулевая настройка для каждого устройства в доме. Компромиссы трёх подходов (боковой роутер, TProxy, TUN), полная конфигурация и служба systemd, правила брандмауэра и отказоустойчивость, чтобы домашние оставались в сети.