Документация по заголовкам

Как это работает

Клиент забирает подписку обычным HTTP-запросом. Тело ответа — конфиг mihomo, а заголовки ответа — всё остальное: имя сервиса, остаток трафика, тема, набор виджетов, ссылки на биллинг. Ни SDK, ни плагина, ни договорённости с нами не требуется.

Заголовки перечитываются при каждом обновлении профиля — по кнопке или по интервалу. Значения привязаны к профилю, а не к приложению: тему задаёт тот профиль, который сейчас активен.

HTTP/1.1 200 OK
Content-Type: application/yaml; charset=utf-8
Subscription-Userinfo: upload=13421772800; download=83994443776; total=214748364800; expire=1798761600
Profile-Title: Nebula VPN
ReClash-ServiceName: Nebula VPN
ReClash-Hex: 2FD3B6:vibrant
ReClash-SupportURL: https://nebula.example/help

Три слоя заголовков

Заголовки, которые читает ReClash, делятся на три группы — стоит понимать, какая за что отвечает. Полный список каждого слоя — в справочнике.

Общие

Стандартные заголовки Clash — subscription-userinfo, profile-title и другие. Если вы их уже отдаёте, менять ничего не нужно.

ReClash

Двадцать заголовков reclash-* — всё, что делает панель фирменной: тема, кольцо, виджеты, объявления. Понимает только ReClash.

Псевдонимы

Заголовки flclashx-*, которые ReClash читает ради совместимости — чтобы вам не пришлось ничего переделывать. См. «Совместимость».

Заголовки — это подсказки оформления, а не механизм доверия. Пользователь может переопределить почти всё, что вы прислали.

Правила разбора

Эти правила действуют для всех заголовков сразу — держите их в голове, читая справочник.

Регистр не важен

Имена заголовков сравниваются без учёта регистра: ReClash-Hex, reclash-hex и RECLASH-HEX — одно и то же.

Приоритет у reclash-*

Если пришли и reclash-*, и псевдоним, и общий заголовок — побеждает reclash-*.

Повторы склеиваются

Несколько одинаковых заголовков соединяются через запятую — так же, как это делает HTTP.

Пустое игнорируется

Пустые значения и неизвестные токены просто отбрасываются: сломать приложение опечаткой нельзя.

Base64 для не-ASCII

Текстовые заголовки принимают префикс base64: или base64,. Для кириллицы и эмодзи это обязательно — в HTTP-заголовке им не место.

Только HTTPS в ссылках

Все URL — абсолютные и по HTTPS. Исключение — фон, который допускает и http. Логин и пароль в URL запрещены.

Совместимость

ReClash читает часть заголовков FlClashX, чтобы провайдерам не пришлось ничего переделывать. Порядок в таблице — порядок приоритета: побеждает первый непустой. В справочнике псевдоним показан прямо на карточке своего заголовка.

У надписи подключения, кольца, виджетов, reclash-custom, reclash-settings и запасных хостов псевдонимов нет — это возможности ReClash.

Доставка и отладка

Самая частая проблема — заголовки правильные на источнике, но клиент их не видит. Начните с того, чтобы посмотреть, что реально уходит по сети:

# что реально уходит клиенту
curl -sSI 'https://sub.nebula.example/sub/TOKEN' | grep -i 'reclash\|subscription\|profile\|content-disposition'

# тело подписки, без заголовков
curl -s 'https://sub.nebula.example/sub/TOKEN' | head -20

В выводе должны быть ваши reclash-* и subscription-userinfo. Если их нет — дело в том, что между панелью и клиентом, а не в самих значениях.

Заголовки не доходят до клиента

Почти всегда их срезает обратный прокси или CDN. nginx по умолчанию не пробрасывает произвольные заголовки апстрима — проверьте, что перед location подписки нет proxy_hide_header на reclash-*, а панель отдаёт их до прокси. Соберите готовый фрагмент для nginx или Caddy в конструкторе.

Кириллица приходит мусором

HTTP-заголовок несёт только ASCII. Любой не-латинский текст — имя сервиса, объявление, надпись подключения — кодируйте префиксом base64:. Конструктор делает это автоматически.

Значения задвоились

Панель уже отдаёт заголовок, а ваш прокси добавляет его ещё раз: add_header в nginx дописывает, а не заменяет. Спрячьте исходный через proxy_hide_header либо задавайте значение в одном месте.

CDN кэширует старый ответ

Если подписка идёт через CDN, он может отдавать закэшированный ответ с прежними заголовками. Исключите путь подписки из кэша или отдавайте Cache-Control: no-store на нём.

Заголовок игнорируется, хотя дошёл

Проверьте написание и значение по справочнику: неизвестные токены и пустые значения молча отбрасываются. Регистр имени роли не играет, а вот reclash-view и reclash-hex разбираются по строгим правилам — см. «Правила разбора».

Устройства и HWID

Если пользователь включил передачу идентификатора устройства, запрос подписки несёт несколько дополнительных заголовков. Они нужны, чтобы вы могли показать понятный список устройств и лимит по тарифу.

Ответ клиенту

Чеклист внедрения

1. Отдавайте subscription-userinfo — это самое заметное для пользователя.
2. Добавьте reclash-servicename и логотип: панель перестаёт быть безымянной.
3. Поставьте reclash-supporturl — меньше писем «куда писать».
4. Выберите цвет через reclash-hex и проверьте его в живом превью конструктора.
5. Проверьте ответ курлом: curl -sI 'https://…/sub' | grep -i reclash.
6. Убедитесь, что заголовки доживают до клиента через ваш прокси и CDN.
7. Не отправляйте reclash-settings без причины.

Первоисточник этой страницы — PROVIDER_HEADERS.md в репозитории. Если он разойдётся с этой страницей — прав репозиторий.