# Локальный HTTP API конфигураций

Source: https://onexray.com/ru/docs/advanced/local-api/
Description: Проверяйте JSON OneXray и создавайте предварительные конфигурации через защищённый локальный HTTP API настольного приложения.
Language: ru-RU
Last updated: 2026-09-28


Доверенные локальные инструменты могут использовать разбор, компиляцию, установленные GeoData и проверку libXray самого приложения. Отдельный CLI не нужен. API не импортирует и не сохраняет данные, не меняет настройки, не загружает зависимости и не управляет запуском VPN.

## Включение и авторизация

Откройте **Дополнительно → Xray → Локальный API**, включите его и сохраните. По умолчанию API отключён и доступен только на компьютере. Приложение должно работать и завершить подготовку служб. Скрытое окно не мешает; выход из приложения останавливает API, даже если VPN продолжает работать.

Адрес по умолчанию — `http://127.0.0.1:18587`, диапазон портов — 1024–65535. Прослушивается только IPv4 loopback, не локальная сеть. Автоматические порты Xray SOCKS/metrics исключают сохранённый порт API даже при отключённом API. Порты inbounds, заданные пользователем, не переписываются.

Скопируйте Token из приложения в защищённое хранилище доверенного локального инструмента. Каждый запрос требует `Authorization: Bearer <token>`. Token сохраняется при перезапуске; сброс немедленно отзывает прежнее значение. Отключение API сохраняет Token, очистка данных удаляет его; резервная копия подключений его не содержит.

Не помещайте Token в запрос к ИИ, URL, аргументы командной строки, репозиторий или журнал. Настраивайте авторизацию отдельно от генерируемого текста. Подключайтесь напрямую к указанному loopback-адресу, обходите прокси окружения и отключайте перенаправления. Запросы с браузерным Origin и межсайтовый доступ не поддерживаются. Token не защищает от вредоносного ПО, уже получившего доступ к вашей учётной записи.

## API версии 1

| Метод и путь | Результат |
| --- | --- |
| `GET /api/v1/info` | Версии API, приложения и Core; платформа и поддерживаемые типы конфигураций |
| `POST /api/v1/config/validate` | Разбор и проекция проверки приложения, затем проверка конфигурации libXray |
| `POST /api/v1/config/compile` | Предварительная рабочая конфигурация без проверки ядром и запуска |

POST использует `Content-Type: application/json`, размер тела ограничен 16 МиБ. Передавайте исходную конфигурацию как **текстовую строку**, не как повторно закодированный объект, чтобы позиции ошибок относились к оригиналу.

```json
{
  "kind": "raw",
  "text": "{\n  \"name\": \"Direct example\",\n  \"outbounds\": [{\"protocol\": \"freedom\", \"tag\": \"direct\"}]\n}"
}
```

Пример не содержит данных прокси и использует прямой доступ; это не предоставляемый VPN-сервер.

| `kind` | Содержимое `text` |
| --- | --- |
| `outbound` | Один объект outbound, как в редакторе узла, **не** документ с обёрткой `outbounds` |
| `routing` | [Обычная собственная маршрутизация](https://onexray.com/ru/docs/configuration/custom-routing/) с пустыми входными слотами |
| `advanced-routing` | [Расширенный собственный JSON](https://onexray.com/ru/docs/configuration/advanced-routing/) в пределах разрешённых полей шаблона |
| `raw` | [Полная конфигурация Raw JSON](https://onexray.com/ru/docs/configuration/raw-json/) |

Необязательное `name` следует правилам выбранного типа; имя конфигурации не равно тегу outbound. `validate` не принимает `options` и дополнительные `outbounds`. Проверка маршрутов использует заглушки, а не фактически выбранные узлы.

## Предварительная компиляция

Для `compile` кроме `kind` и `text` передайте явный объект `options`:

```json
{
  "platform": "macos",
  "sessionDirectory": "/explicit/preview-directory",
  "metricsPort": 19001,
  "socksPort": 19002,
  "ipv6": true
}
```

- `platform`: `ios`, `macos`, `android`, `windows` или `linux`. Это цель генерации, а не удалённого запуска.
- Для Windows нужен `windowsMode: "exe"` или `"msix"`; для Windows/Linux обязателен `interfaceName`.
- Для `routing` и `advanced-routing` также нужен корневой массив `outbounds` с реальными узлами по числу пустых слотов. `outbound` и `raw` используют собственные узлы и не принимают дополнительный массив.
- Необязательные `tunDnsIpv4Address`, `tunDnsIpv6Address`, `logEnabled`, `logFilesSupported`, `logLevel`, `dnsLog`, `maskAddress` при пропуске используют значения компилятора по умолчанию, а не текущие настройки пользователя.
- Пути GeoData указывают на каталог установленного приложения. Генерация для другой платформы не создаёт там эти пути. Компиляция не проверяет доступность портов и интерфейсов, не создаёт каталог сеанса и не записывает активную конфигурацию.

## Интерпретация результата

Проверяйте `status` (`passed`, `failed`, `notRun`) и `stage` (`input`, `compile`, `kernel`). HTTP 200 не означает успешную проверку; `passed` на этапе `compile` означает только создание предварительной конфигурации.

Диагностика содержит код и причину; `path`, `offset`, `line`, `column` добавляются лишь при надёжном определении. Смещение начинается с 0, строки и столбцы — с 1. Смещения и столбцы считаются в кодовых единицах UTF-16. Путь — массив, например `["routing", "rules", 0, "domain"]`. Не угадывайте позицию исходника по тексту ошибки Core или сгенерированному JSON.

`validationConfig` и `compiledConfig` — JSON-текст, который может содержать секреты. Защищайте сохранённые результаты и читайте `limitations`. Занятость возвращает 409, слишком большой запрос — 413, недоступность службы — 503; это не успешная проверка.

Проверка создаёт и закрывает экземпляр Core без запуска VPN, но может иметь побочные эффекты в процессе. Это **не песочница для недоверенных конфигураций**. Она не загружает недостающие GeoData, не проверяет ограничения имён и количества в базе, не доказывает правильность реального сочетания узлов и не гарантирует запуск или связь. Тайм-аут клиента не отменяет начавшуюся нативную проверку; не повторяйте её автоматически.

[Создание конфигураций с ИИ](https://onexray.com/ru/docs/ai/) · [Границы конфигураций](https://onexray.com/ru/docs/configuration/compatibility/)