# Gateway

## Що таке Gateway?

Gateway, це серце Neotask, єдина довготривала служба, яка керує всіма сесіями агентів, каналами обміну повідомленнями, виконанням інструментів та підключеннями пристроїв. Все проходить через Gateway.

Це WebSocket-сервер, який приймає підключення від клієнтів (настільний застосунок, мобільні застосунки, веб-панель) і керує повним життєвим циклом AI-помічника.

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

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

- **WebSocket-сервер**, Приймає клієнтські підключення (порт за замовчуванням 18789)
- **HTTP-сервер**, Обслуговує інтерфейс керування, хост полотна та кінцеві точки перевірки стану
- **Адаптери каналів**, Підтримують підключення до платформ обміну повідомленнями (WhatsApp, Telegram, Discord тощо)
- **Менеджер сесій**, Зберігає та керує станом розмов агентів
- **Планувальник Cron**, Виконує заплановані завдання та пробудження пульсу
- **Середовище виконання плагінів**, Завантажує та керує життєвим циклом плагінів
- **Служба браузера**, Керує екземплярами Chromium для веб-автоматизації

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

| Режим | Опис |
|------|-------------|
| **Зворотна петля** | За замовчуванням. Доступний лише з localhost (127.0.0.1) |
| **Локальна мережа** | Доступний у вашій локальній мережі. Автоматичне виявлення через Bonjour/mDNS |
| **Tailnet** | Доступний через VPN Tailscale з MagicDNS |
| **Власний** | Прив'язка до конкретної адреси |

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

| Метод | Опис |
|--------|-------------|
| **Токен** | Токен авторизації WebSocket (UUID або власний рядок) |
| **Пароль** | Аутентифікація на основі пароля (хешовано за допомогою bcrypt) |
| **Довірений проксі** | Для зворотних проксі із заголовками попередньої аутентифікації |
| **Локальна довіра** | Підключення через зворотну петлю автоматично затверджуються |

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

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

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

### Гаряче перезавантаження

Зміни конфігурації можуть застосовуватися без перезапуску:

| Режим | Поведінка |
|------|----------|
| **Гібридний** (за замовчуванням) | Гаряче застосовує безпечні зміни, перезапускає для інших |
| **Гарячий** | Застосовує лише безпечні для гарячого режиму зміни, ігнорує інші |
| **Перезапуск** | Перезапускає при будь-яких змінах, що вимагають перезавантаження |
| **Вимкнено** | Без автоматичного перезавантаження |

## Віддалений доступ

### Tailscale (Рекомендовано)

Tailscale забезпечує безпечний, не потребуючий конфігурації віддалений доступ:

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

### SSH-тунель

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

- Простий, безпечний, не потребує змін конфігурації
- Працює з будь-якою машиною, що підтримує SSH
- Підтримує повний протокол WebSocket та інтерфейс керування

### Правила безпеки

- **Зворотна петля + SSH/Tailscale**, найбезпечніша комбінація
- Прив'язка до не-loopback-адреси вимагає налаштування токена аутентифікації
- Доступне закріплення відбитків TLS для додаткової безпеки
- Керування браузером за замовчуванням вимкнено для віддалених підключень

## Моніторинг стану

### Кінцева точка перевірки стану

HTTP-кінцева точка `/health` повертає:

- Статус Gateway
- Активність RPC
- Стан кожного каналу (підключено, статус аутентифікації, кількість акаунтів)
- Готовність браузера
- Активні агенти та підключені вузли
- Час роботи

### Зонди

- **Активність RPC**, Тест підключення WebSocket + ехо-тест
- **Стан каналу**, Перевірка аутентифікації + пінг API для кожного каналу
- **Готовність браузера**, Перевірка порту, перевірка процесу
- **Підключення вузлів**, Мітка часу останнього пульсу

## Виявлення

### Bonjour/mDNS

При прив'язці до локальної мережі Gateway оголошує себе через мультикастний DNS:

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

### Виявлення у широкій мережі

Виявляйте шлюзи у вашій мережі з конфігурованими таймаутами. Підтримує виявлення через локальний Bonjour та DNS Tailscale.

## Кілька Gateway

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

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

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

### Лікар (Doctor)

Вбудований інструмент діагностики перевіряє:

- Валідність конфігурації
- Дозволи на файли
- Підключення каналів
- Статус аутентифікації моделі
- Сумісність версії Node.js
- Поширені неправильні конфігурації

При наданні дозволу він може автоматично усунути багато проблем.

### Ведення журналу

Журнали Gateway записуються в щоденні файли JSONL:

- Відстеження використання токенів для кожного завершення
- Журнали подій каналів
- Журналювання помилок зі структурованим контекстом
- Конфігуровані рівні журналювання