Внешний контроллер (Clash API)

mihomo реализует RESTful API Clash. Все панели Clash (metacubexd, yacd, Clash Dashboard) общаются с mihomo именно через него. Эта страница описывает группу верхнеуровневых ключей, задающих адреса прослушивания API, встроенный UI и CORS.

Ключи верхнего уровня

Поле	Тип	По умолчанию	Допустимые значения	Описание
external-controller	string	(unset)	<host:port>	Адрес прослушивания RESTful API по обычному HTTP.
external-controller-pipe	string	(unset)	<pipe path>	Путь именованного канала Windows. Задавайте только в Windows, когда API должен быть доступен лишь локальным клиентам на той же машине.
external-controller-unix	string	(unset)	<socket path>	Путь Unix-сокета для API.
external-controller-tls	string	(unset)	<host:port>	Адрес прослушивания, защищённый TLS. Требует, чтобы верхнеуровневый блок `tls` содержал сертификат и закрытый ключ.
external-controller-cors	RawCors	(unset)	RawCors	Список разрешённых источников CORS для HTTP API.
external-controller-routing-mark	int	0	<uint32>	Linux SO_MARK (fwmark), устанавливаемый на сокеты слушателей API (обычный и TLS), чтобы политика маршрутизации могла обрабатывать трафик контроллера особо. 0 отключает.
external-ui	string	(unset)	<dir path>	Локальный каталог, содержимое которого раздаётся по адресу /ui.
external-ui-url	string	(unset)	<URL>	URL архива, который скачивается и распаковывается в external-ui, когда каталог пуст.
external-ui-name	string	(unset)	<name>	Подкаталог внутри external-ui для раздачи — позволяет держать несколько панелей бок о бок.
external-doh-server	string	(unset)	<path> | <host:port>	Смонтировать конечную точку DoH по этому пути, чтобы другие устройства могли пользоваться DNS-резолвером mihomo.
secret	string	(unset)	<bearer token>	Bearer-токен, требуемый для всех вызовов API. Настоятельно рекомендуется всякий раз, когда external-controller привязан не к loopback-адресу.

Исходный код: config/config.go:399-467 · зафиксировано на v1.19.29 (e26714a)

external-controller-cors

Поле	Тип	По умолчанию	Допустимые значения	Описание
allow-origins	[]string	[]	<origin>	Список разрешённых источников (origin). Пустой список означает только same-origin.
allow-private-network	bool	false	true | false	Учитывать предзапросы private-network, чтобы панели в частных LAN могли обращаться к API.

Исходный код: config/config.go:216-219 · зафиксировано на v1.19.29 (e26714a)

Пример

external-controller: 127.0.0.1:9090
external-controller-cors:
  allow-origins:
    - https://metacubex.github.io
    - http://localhost:5173
  allow-private-network: true
external-ui: /etc/mihomo/ui
external-ui-url: https://github.com/MetaCubeX/metacubexd/archive/refs/heads/gh-pages.zip
external-ui-name: metacubexd
secret: <random-string-here>

Примечания

• Если external-controller привязан не к loopback-адресу, обязательно задайте secret и/или external-controller-tls. Через API можно изменить любое решение маршрутизации демона.
• external-ui — это просто файловый сервер: никакой защиты, кроме той, что даёт CORS, у него нет. Большинство пользователей раздают панель с localhost и открывают её в браузере на той же машине.
• external-controller-pipe (Windows) и external-controller-unix (Linux/macOS) полезны, когда доступ к API нужен только клиентам на той же машине; сочетайте их с ACL файловой системы.

Исходный код: config/config.go:216-467 · v1.19.29 (e26714a)