# Gateway

## Что такое Gateway?

Gateway, это сердце Neotask, единый долго работающий сервис, управляющий всеми сессиями агентов, каналами обмена сообщениями, выполнением инструментов и подключениями устройств. Всё проходит через Gateway.

Это WebSocket-сервер, который прослушивает подключения от клиентов (десктопное приложение, мобильные приложения, веб-дашборд) и управляет полным жизненным циклом ИИ-ассистента.

## Архитектура

### Компоненты

- **WebSocket-сервер**, принимает клиентские подключения (порт по умолчанию 18789)
- **HTTP-сервер**, обслуживает Control UI, хост canvas и эндпоинты проверки работоспособности
- **Адаптеры каналов**, поддерживают подключения к платформам обмена сообщениями (WhatsApp, Telegram, Discord и т.д.)
- **Менеджер сессий**, сохраняет и управляет состоянием разговоров агентов
- **Cron-планировщик**, выполняет запланированные задания и пробуждения heartbeat
- **Среда выполнения плагинов**, загружает и управляет жизненным циклом плагинов
- **Сервис браузера**, управляет экземплярами Chromium для веб-автоматизации

### Режимы привязки

| Режим | Описание |
|------|-------------|
| **Loopback** | По умолчанию. Доступен только с localhost (127.0.0.1) |
| **LAN** | Доступен в локальной сети. Автоматическое обнаружение через Bonjour/mDNS |
| **Tailnet** | Доступен через Tailscale VPN с MagicDNS |
| **Custom** | Привязка к конкретному адресу |

### Аутентификация

| Метод | Описание |
|--------|-------------|
| **Token** | Bearer-токен WebSocket (UUID или пользовательская строка) |
| **Password** | Аутентификация по паролю (хеш bcrypt) |
| **Trusted Proxy** | Для обратных прокси с заголовками предварительной аутентификации |
| **Local Trust** | Loopback-соединения одобряются автоматически |

## Конфигурация

Gateway настраивается через `neotask.json` (формат JSON5). Ключевые разделы:

| Раздел | Управляет |
|---------|----------|
| `agents` | Список агентов, настройки по умолчанию, рабочие пространства |
| `gateway` | Порт, режим привязки, аутентификация, поведение перезагрузки |
| `channels` | Конфигурация и учётные данные для каждого канала |
| `tools` | Разрешения для инструментов, профили, безопасность |
| `plugins` | Загрузка плагинов, включение, конфигурация для каждого плагина |
| `models` | Аутентификация провайдера, резервные варианты, настройки провайдера |
| `skills` | Директории навыков, конфигурация для каждого навыка |
| `browser` | Профили браузера, порты, режим headless |
| `cron` | Конфигурация планировщика |
| `session` | Правила сброса, пороги уплотнения |
| `messages` | Настройки TTS, политики медиа |
| `memory` | Конфигурация индексирования памяти |
| `security` | Изоляция в sandbox, расширенный режим, подтверждения |

### Горячая перезагрузка

Изменения конфигурации могут применяться без перезапуска:

| Режим | Поведение |
|------|----------|
| **Hybrid** (по умолчанию) | Горячее применение безопасных изменений, перезапуск для остальных |
| **Hot** | Применять только горячие изменения, игнорировать остальные |
| **Restart** | Перезапуск при любом изменении, требующем перезагрузки |
| **Off** | Без автоматической перезагрузки |

## Удалённый доступ

### Tailscale (Рекомендуется)

Tailscale обеспечивает безопасный удалённый доступ без настройки:

- Привязать Gateway к вашей Tailnet
- Доступ с любого устройства в той же сети Tailscale
- Автоматический DNS через MagicDNS
- Tailscale Serve может открыть дашборд по HTTPS

### SSH-туннель

Перенаправление порта Gateway через SSH:

- Простой, безопасный, без изменений конфигурации
- Работает с любой машиной, поддерживающей SSH
- Поддерживает полный протокол WebSocket и Control UI

### Правила безопасности

- Комбинация **Loopback + SSH/Tailscale**, наиболее безопасная
- Привязка вне loopback требует конфигурации токена аутентификации
- Доступна привязка к TLS-отпечатку для дополнительной безопасности
- Управление браузером отключено для удалённых подключений по умолчанию

## Мониторинг работоспособности

### Эндпоинт проверки работоспособности

HTTP-эндпоинт `/health` возвращает:

- Статус Gateway
- Живость RPC
- Работоспособность каждого канала (подключён, статус аутентификации, количество аккаунтов)
- Готовность браузера
- Активные агенты и подключённые узлы
- Время работы

### Пробы

- **Живость RPC**, подключение к WebSocket + тест эхо
- **Работоспособность канала**, проверка аутентификации + API-ping для каждого канала
- **Готовность браузера**, проверка порта, проверка процесса
- **Подключение узла**, метка времени последнего heartbeat

## Обнаружение

### Bonjour/mDNS

При привязке к LAN Gateway объявляет о себе через multicast DNS:

- Тип сервиса: `_neotask-gw._tcp`
- Включает порт, транспорт, статус TLS и информацию Tailscale DNS
- Компаньон-приложения обнаруживают Gateway автоматически

### Широкозональное обнаружение

Обнаруживайте шлюзы в вашей сети с настраиваемыми таймаутами. Поддерживает как локальный Bonjour, так и обнаружение через Tailscale DNS.

## Несколько шлюзов

Вы можете запускать несколько экземпляров Gateway на одной машине с использованием профилей:

- Каждый профиль имеет отдельную конфигурацию, рабочее пространство, сессии и состояние
- Разные порты для каждого Gateway
- Полезно для изоляции (личное vs рабочее) или тестирования

## Диагностика

### Doctor (Диагностический инструмент)

Встроенный диагностический инструмент проверяет:

- Валидность конфигурации
- Права доступа к файлам
- Подключение каналов
- Статус аутентификации модели
- Совместимость версии Node.js
- Распространённые неправильные настройки

Он может автоматически исправить многие проблемы, если ему дать разрешение.

### Логирование

Логи Gateway записываются в ежедневные JSONL-файлы:

- Отслеживание использования токенов за каждое завершение
- Логи событий каналов
- Логирование ошибок со структурированным контекстом
- Настраиваемые уровни логирования