Clawdbot Gateway — это постоянно работающий сервис, управляющий подключениями к мессенджерам, средой выполнения агентов и плоскостью управления для вашего AI-ассистента.

Обзор Clawdbot Gateway

Clawdbot Gateway — это постоянно работающий процесс, который владеет подключениями к мессенджерам (WhatsApp через Baileys, Telegram через grammY, Discord, Slack и другие) и плоскостью управления/событий. Это основной сервис, обеспечивающий круглосуточную работу вашего AI-ассистента Clawdbot.

Что такое Gateway?

Gateway — это долгоживущий демон, который:

Поддерживает все подключения к провайдерам мессенджеров
Предоставляет типизированный WebSocket API для запросов, ответов и серверных push-событий
Валидирует входящие фреймы по JSON Schema
Генерирует события: agent, chat, presence, health, heartbeat, cron

Ключевой принцип: Один Gateway на хост; это единственное место, открывающее сессии мессенджеров (например, WhatsApp).

Быстрый старт

Запуск Gateway

clawdbot gateway --port 18789

Для полных отладочных/трассировочных логов:

clawdbot gateway --port 18789 --verbose

Если порт занят, завершите слушателей и запустите:

clawdbot gateway --force

Режим разработки

Для разработки с автоперезагрузкой при изменениях TypeScript:

pnpm gateway:watch

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

Компоненты

Компонент	Описание
Gateway (демон)	Поддерживает подключения к провайдерам, предоставляет WS API
Клиенты	Приложение macOS, CLI, веб-интерфейс подключаются через WebSocket
Узлы	Устройства macOS/iOS/Android/headless с `role: node`
WebChat	Статический интерфейс, использующий Gateway WS API
Canvas Host	Обслуживает редактируемый агентом HTML (порт по умолчанию 18793)

Поток подключения

Client                    Gateway
  |                          |
  |---- req:connect -------->|
  |<------ res (ok) ---------|
  |                          |
  |<------ event:presence ---|
  |<------ event:tick -------|
  |                          |
  |------- req:agent ------->|
  |<------ res:agent --------|
  |<------ event:agent ------|

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

Базовая конфигурация

Расположение файла конфигурации: ~/.clawdbot/clawdbot.json

{
  "gateway": {
    "port": 18789,
    "auth": {
      "token": "your-secret-token"
    },
    "reload": {
      "mode": "hybrid"
    }
  }
}

Конфигурация порта

Приоритет порта:

Флаг CLI --port
Переменная окружения CLAWDBOT_GATEWAY_PORT
gateway.port в конфигурации
По умолчанию: 18789

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

Аутентификация Gateway обязательна по умолчанию. Настройте через:

gateway.auth.token в конфигурации
Переменную окружения CLAWDBOT_GATEWAY_TOKEN
gateway.auth.password для аутентификации по паролю

Клиенты должны отправлять connect.params.auth.token или connect.params.auth.password.

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

Горячая перезагрузка конфигурации отслеживает ~/.clawdbot/clawdbot.json:

Режим	Описание
`hybrid` (по умолчанию)	Безопасные изменения применяются на лету, критические — с перезапуском
`off`	Отключить горячую перезагрузку

Сервисы Gateway

HTTP-эндпоинты

Gateway обслуживает несколько HTTP-эндпоинтов на одном порту:

Эндпоинт	Описание
`/v1/chat/completions`	Совместим с OpenAI Chat Completions
`/v1/responses`	OpenResponses API
`/tools/invoke`	Вызов инструментов
Панель управления	Веб-панель управления

Canvas Host

Запускается по умолчанию на порту 18793, обслуживая:

http://<gateway-host>:18793/__clawdbot__/canvas/

Из ~/.clawdbot/workspace/canvas. Отключить:

canvasHost.enabled: false
CLAWDBOT_SKIP_CANVAS_HOST=1

Панель управления

Доступ к панели управления:

http://127.0.0.1:18789/

Или выполните:

clawdbot dashboard

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

SSH-туннель (рекомендуется)

ssh -N -L 18789:127.0.0.1:18789 user@host

Клиенты затем подключаются к ws://127.0.0.1:18789 через туннель.

Tailscale/VPN

Предпочтительно для удалённого доступа в продакшене. Применяется тот же handshake + токен аутентификации.

Управление Gateway

Команды сервиса

# Проверка статуса
clawdbot gateway status

# Проверка здоровья
clawdbot health

# Аудит безопасности
clawdbot security audit --deep

# Остановка gateway
clawdbot gateway stop

Супервизия

macOS: Использует LaunchAgent (bot.molt.<profile>)

Linux: Использует пользовательский сервис systemd (clawdbot-gateway-<profile>.service)

Windows: Использует Windows Service (Clawdbot Gateway (<profile>))

Несколько Gateway

Обычно не нужно — один Gateway может обслуживать несколько каналов и агентов. Используйте несколько Gateway только для:

Резервирования
Строгой изоляции (например, бот-спасатель)

Требования:

Изолированное состояние + конфигурация
Уникальные порты

Протокол Wire

Транспорт

WebSocket с текстовыми фреймами, содержащими JSON-пейлоады
Первый фрейм должен быть connect

Типы сообщений

Запросы:

{"type": "req", "id": "...", "method": "...", "params": {...}}

Ответы:

{"type": "res", "id": "...", "ok": true, "payload": {...}}

События:

{"type": "event", "event": "...", "payload": {...}, "seq": 1}

Проверьте, занят ли порт: lsof -i :18789
Просмотрите логи: cat /tmp/clawdbot/gateway.log
Используйте --force для завершения существующих слушателей

Проблемы подключения

Убедитесь, что токен аутентификации совпадает
Проверьте сетевое подключение
Просмотрите логи WebSocket-рукопожатия с --verbose

Проблемы каналов

Проверьте статус канала: clawdbot channels status
Повторно аутентифицируйте каналы: clawdbot channels login
Просмотрите логи конкретного канала

Лучшие практики

Используйте токены аутентификации: Всегда настраивайте gateway.auth.token для безопасности
Мониторьте здоровье: Регулярно проверяйте clawdbot health
Используйте супервизию: Позвольте launchd/systemd управлять перезапусками
Создавайте резервные копии: Храните бэкапы ~/.clawdbot/clawdbot.json
Просматривайте логи: Регулярно проверяйте логи на наличие проблем

Следующие шаги

Руководство по настройке Clawdbot - Полное руководство по установке
Интеграция Clawdbot с WhatsApp - Подключение к WhatsApp
Интеграция Clawdbot с Telegram - Подключение к Telegram

Clawdbot Gateway