Запуск Gateway: Демон и режимы работы

Чему вы научитесь

✅ Запускать процесс Gateway на переднем плане через командную строку
✅ Настраивать Gateway как фоновый демон (macOS LaunchAgent / Linux systemd / Windows Scheduled Task)
✅ Понимать различные режимы привязки (loopback / LAN / Tailnet) и способы аутентификации
✅ Переключаться между режимом разработки и производственным режимом
✅ Использовать --force для принудительного освобождения занятого порта

Трудности, с которыми вы сталкиваетесь

Вы уже завершили настройку мастера, базовая конфигурация Gateway готова. Однако:

Каждый раз, когда хотите использовать Gateway, приходится вручную запускать команды в терминале?
После закрытия окна терминала Gateway останавливается, и AI ассистент также "уходит в оффлайн"?
Хотите получить доступ к Gateway в локальной сети или сети Tailscale, но не знаете, как настроить?
Gateway не запускается, но не знаете, это проблема конфигурации или порт занят?

Когда использовать этот метод

Рекомендуемые способы запуска:

Сценарий	Команда	Описание
Ежедневное использование	`clawdbot gateway install` + `clawdbot gateway start`	Автоматический запуск как фоновая служба
Разработка и отладка	`clawdbot gateway --dev`	Создает конфигурацию разработки, автоматическая перезагрузка
Временное тестирование	`clawdbot gateway`	Запуск на переднем плане, логи выводятся в терминал
Конфликт портов	`clawdbot gateway --force`	Принудительно освобождает порт перед запуском
Доступ из локальной сети	`clawdbot gateway --bind lan`	Разрешает подключение устройств из локальной сети
Удаленный доступ Tailscale	`clawdbot gateway --tailscale serve`	Открывает Gateway через сеть Tailscale

🎒 Подготовка перед началом

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

Перед запуском Gateway убедитесь:

✅ Завершили настройку мастера (clawdbot onboard) или вручную установили gateway.mode=local
✅ AI модель настроена (Anthropic / OpenAI / OpenRouter и др.)
✅ Если требуется доступ к внешней сети (LAN / Tailnet), настроен способ аутентификации
✅ Понимаете сценарий использования (локальная разработка vs производственная работа)

Основная идея

Что такое Gateway?

Gateway — это управляющая плоскость WebSocket Clawdbot, которая отвечает за:

Управление сессиями: поддерживает состояние всех сессий AI диалогов
Подключение каналов: соединяет с 12+ каналами сообщений, такими как WhatsApp, Telegram, Slack и др.
Вызов инструментов: координирует выполнение инструментов, таких как автоматизация браузера, операции с файлами, запланированные задачи и др.
Управление узлами: управляет узлами устройств macOS / iOS / Android
Распространение событий: отправляет в реальном времени события, такие как прогресс размышлений AI, результаты вызова инструментов и др.

Зачем нужен демон?

Запуск Gateway в качестве фоновой службы имеет следующие преимущества:

Постоянно онлайн: даже при закрытии терминала AI ассистент остается доступным
Автоматический запуск: после перезагрузки системы служба автоматически восстанавливается (macOS LaunchAgent / Linux systemd)
Единое управление: управление жизненным циклом через команды start / stop / restart
Централизация логов: системный сбор логов для удобства устранения неполадок

Следуйте моим шагам

Шаг 1: Запуск Gateway (режим переднего плана)

Зачем

Режим переднего плана подходит для разработки и тестирования, логи выводятся непосредственно в терминал, удобно просматривать состояние Gateway в реальном времени.

bash

# Запуск с конфигурацией по умолчанию (прослушивание 127.0.0.1:18789)
clawdbot gateway

# Запуск с указанием порта
clawdbot gateway --port 19001

# Включить подробные логи
clawdbot gateway --verbose

Что вы должны увидеть:

bash

✓ agent model: anthropic/claude-opus-4-5
✓ listening on ws://127.0.0.1:18789 (PID 12345)
✓ log file: /Users/you/.clawdbot/logs/gateway.log

Контрольная точка

Видим listening on ws://... — запуск успешен
Запишите отображаемый PID (идентификатор процесса), он понадобится для последующей отладки
Порт по умолчанию — 18789, можно изменить через --port

Шаг 2: Настройка режима привязки

Зачем

По умолчанию Gateway слушает только адрес локальной петли (127.0.0.1), это означает, что подключаться может только локальный компьютер. Если вы хотите получить доступ в локальной сети или сети Tailscale, нужно настроить режим привязки.

bash

# Только локальная петля (по умолчанию, наиболее безопасно)
clawdbot gateway --bind loopback

# Доступ из локальной сети (требуется аутентификация)
clawdbot gateway --bind lan --token "your-token"

# Доступ через сеть Tailscale
clawdbot gateway --bind tailnet --token "your-token"

# Автоматическое определение (локальный + LAN)
clawdbot gateway --bind auto

Что вы должны увидеть:

bash

# режим loopback
✓ listening on ws://127.0.0.1:18789 (PID 12345)

# режим lan
✓ listening on ws://192.168.1.100:18789 (PID 12345)
✓ listening on ws://10.0.0.5:18789

Предупреждение безопасности

⚠️ Привязка к не-loopback адресу требует настройки аутентификации!

При --bind lan / --bind tailnet необходимо передать --token или --password
Иначе Gateway откажется запускаться с ошибкой: Refusing to bind gateway to lan without auth
Токен аутентификации передается через конфигурацию gateway.auth.token или параметр --token

Шаг 3: Установка как демон (macOS / Linux / Windows)

Зачем

Демон позволяет Gateway работать в фоновом режиме, даже при закрытии окна терминала это не влияет. После перезагрузки системы он автоматически запускается, поддерживая AI ассистент всегда онлайн.

bash

# Установка как системная служба (macOS LaunchAgent / Linux systemd / Windows Scheduled Task)
clawdbot gateway install

# Запуск службы
clawdbot gateway start

# Просмотр состояния службы
clawdbot gateway status

# Перезапуск службы
clawdbot gateway restart

# Остановка службы
clawdbot gateway stop

Что вы должны увидеть:

bash

# macOS
✓ LaunchAgent loaded
✓ service runtime: active

# Linux
✓ systemd service enabled
✓ service runtime: active

# Windows
✓ Scheduled Task registered
✓ service runtime: running

Контрольная точка

Запустите clawdbot gateway status, чтобы подтвердить, что состояние службы — active / running
Если служба показывает loaded, но runtime: inactive, запустите clawdbot gateway start
Логи демона записываются в ~/.clawdbot/logs/gateway.log

Шаг 4: Обработка конфликта портов (--force)

Зачем

Порт по умолчанию 18789 может быть занят другим процессом (например, предыдущим экземпляром Gateway). Использование --force позволяет автоматически освободить порт.

bash

# Принудительно освободить порт и запустить Gateway
clawdbot gateway --force

Что вы должны увидеть:

bash

✓ force: killed pid 9876 (node) on port 18789
✓ force: waited 1200ms for port 18789 to free
✓ agent model: anthropic/claude-opus-4-5
✓ listening on ws://127.0.0.1:18789 (PID 12345)

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

--force последовательно выполняет следующие операции:

Пытается завершить процесс через SIGTERM (ожидание 700ms)
Если не завершено, использует SIGKILL для принудительного завершения
Ожидает освобождения порта (максимум 2 секунды)
Запускает новый процесс Gateway

Шаг 5: Режим разработки (--dev)

Зачем

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

bash

# Запуск режима разработки (создание dev profile + workspace)
clawdbot gateway --dev

# Сброс конфигурации разработки (очистка учетных данных + сессий + рабочей области)
clawdbot gateway --dev --reset

Что вы должны увидеть:

bash

✓ dev config created at ~/.clawdbot-dev/clawdbot.json
✓ dev workspace initialized at ~/clawd-dev
✓ agent model: anthropic/claude-opus-4-5
✓ listening on ws://127.0.0.1:18789 (PID 12345)

Особенности режима разработки

Файл конфигурации: ~/.clawdbot-dev/clawdbot.json (независим от производственной конфигурации)
Каталог рабочей области: ~/clawd-dev
Пропуск выполнения скрипта BOOT.md
По умолчанию привязывается к loopback, аутентификация не требуется

Шаг 6: Интеграция Tailscale

Зачем

Tailscale позволяет получить доступ к удаленному Gateway через защищенную частную сеть без публичного IP или перенаправления портов.

bash

# Режим Tailscale Serve (рекомендуется)
clawdbot gateway --tailscale serve

# Режим Tailscale Funnel (требуется дополнительная аутентификация)
clawdbot gateway --tailscale funnel --auth password

Что вы должны увидеть:

bash

# режим serve
✓ Tailscale identity detected
✓ advertising gateway via Tailscale Serve
✓ MagicDNS: https://your-tailnet.ts.net
✓ listening on ws://127.0.0.1:18789 (PID 12345)

# режим funnel
✓ Tailscale Funnel enabled
✓ Funnel URL: https://your-tailnet.ts.net:18789
✓ listening on ws://127.0.0.1:18789 (PID 12345)

Настройка аутентификации

Интеграция Tailscale поддерживает два способа аутентификации:

Identity Headers (рекомендуется): установите gateway.auth.allowTailscale=true, идентификация Tailscale автоматически удовлетворяет аутентификацию
Token / Password: традиционный способ аутентификации, нужно вручную передать --token или --password

Шаг 7: Проверка состояния Gateway

Зачем

Подтвердить, что Gateway работает нормально и протокол RPC доступен.

bash

# Просмотр полного состояния (служба + зондирование RPC)
clawdbot gateway status

# Пропустить зондирование RPC (только состояние службы)
clawdbot gateway status --no-probe

# Проверка работоспособности
clawdbot gateway health

# Зондирование всех доступных Gateway
clawdbot gateway probe

Что вы должны увидеть:

bash

# вывод команды status
Gateway service status
┌──────────────────────────────────────┐
│ Service: LaunchAgent (loaded)      │
│ Runtime: running (PID 12345)       │
│ Port: 18789                       │
│ Last gateway error: none            │
└──────────────────────────────────────┘

RPC probe
┌──────────────────────────────────────┐
│ Target: ws://127.0.0.1:18789 │
│ Status: ✓ connected                │
│ Latency: 12ms                    │
└──────────────────────────────────────┘

# вывод команды health
✓ Gateway is healthy
✓ WebSocket connection: OK
✓ RPC methods: available

Устранение неполадок

Если status показывает Runtime: running, но RPC probe: failed:

Проверьте правильность порта: clawdbot gateway status
Проверьте конфигурацию аутентификации: привязан ли к LAN / Tailnet, но аутентификация не предоставлена?
Просмотрите логи: cat ~/.clawdbot/logs/gateway.log
Запустите clawdbot doctor для получения детальной диагностики

Предупреждения о ловушках

❌ Ошибка: Gateway отказывается запускаться

Сообщение об ошибке:

Gateway start blocked: set gateway.mode=local (current: unset) or pass --allow-unconfigured.

Причина: gateway.mode не установлен в local

Способы решения:

bash

# Способ 1: запустить мастер настройки
clawdbot onboard

# Способ 2: вручную изменить файл конфигурации
# ~/.clawdbot/clawdbot.json
{
  "gateway": {
    "mode": "local"
  }
}

# Способ 3: временно пропустить проверку (не рекомендуется)
clawdbot gateway --allow-unconfigured

❌ Ошибка: привязка к LAN, но нет аутентификации

Сообщение об ошибке:

Refusing to bind gateway to lan without auth.
Set gateway.auth.token/password (or CLAWDBOT_GATEWAY_TOKEN/CLAWDBOT_GATEWAY_PASSWORD) or pass --token/--password.

Причина: привязка к не-loopback адресу требует настройки аутентификации (ограничение безопасности)

Способы решения:

bash

# Установить аутентификацию через файл конфигурации
# ~/.clawdbot/clawdbot.json
{
  "gateway": {
    "auth": {
      "mode": "token",
      "token": "your-secure-token"
    }
  }
}

# Или передать через командную строку
clawdbot gateway --bind lan --token "your-secure-token"

❌ Ошибка: порт уже занят

Сообщение об ошибке:

Error: listen EADDRINUSE: address already in use :::18789

Причина: другой экземпляр Gateway или другая программа заняла порт

Способы решения:

bash

# Способ 1: принудительно освободить порт
clawdbot gateway --force

# Способ 2: использовать другой порт
clawdbot gateway --port 19001

# Способ 3: вручную найти и завершить процесс
lsof -ti:18789 | xargs kill -9  # macOS / Linux
netstat -ano | findstr :18789               # Windows

❌ Ошибка: для сброса режима dev требуется --dev

Сообщение об ошибке:

Use --reset with --dev.

Причина: --reset можно использовать только в режиме разработки, чтобы случайно не удалить производственные данные

Способы решения:

bash

# Правильная команда сброса среды разработки
clawdbot gateway --dev --reset

❌ Ошибка: служба установлена, но все равно используется режим переднего плана

Явление: при запуске clawdbot gateway появляется сообщение "Gateway already running locally"

Причина: демон уже работает в фоновом режиме

Способы решения:

bash

# Остановить фоновую службу
clawdbot gateway stop

# Или перезапустить службу
clawdbot gateway restart

# Затем запустить на переднем плане (если нужна отладка)
clawdbot gateway --port 19001  # использовать другой порт

Итог урока

В этом уроке вы узнали:

✅ Способы запуска: режим переднего плана vs демон ✅ Режимы привязки: loopback / LAN / Tailnet / Auto ✅ Способы аутентификации: Token / Password / Tailscale Identity ✅ Режим разработки: независимая конфигурация, горячая перезагрузка, сброс через --reset ✅ Устранение неполадок: команды status / health / probe ✅ Управление службами: install / start / stop / restart / uninstall

Быстрый справочник ключевых команд:

Сценарий	Команда
Ежедневное использование (служба)	`clawdbot gateway install && clawdbot gateway start`
Разработка и отладка	`clawdbot gateway --dev`
Временное тестирование	`clawdbot gateway`
Принудительное освобождение порта	`clawdbot gateway --force`
Доступ из локальной сети	`clawdbot gateway --bind lan --token "xxx"`
Удаленный доступ Tailscale	`clawdbot gateway --tailscale serve`
Просмотр состояния	`clawdbot gateway status`
Проверка работоспособности	`clawdbot gateway health`

Предварительный просмотр следующего урока

На следующем уроке мы изучим Отправка первого сообщения.
Вы узнаете:
Как отправить первое сообщение через WebChat
Как общаться с AI ассистентом через настроенные каналы (WhatsApp/Telegram и др.)
Понять процесс маршрутизации сообщений и откликов

Приложение: справочник по исходному коду

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

Дата обновления: 2026-01-27

Функция	Путь к файлу	Номер строки
Точка запуска Gateway	`src/cli/gateway-cli/run.ts`	55-310
Абстракция службы демона	`src/daemon/service.ts`	66-155
Запуск боковой службы	`src/gateway/server-startup.ts`	26-160
Реализация сервера Gateway	`src/gateway/server.ts`	1-500
Парсинг аргументов программы	`src/daemon/program-args.ts`	1-250
Вывод логов запуска	`src/gateway/server-startup-log.ts`	7-40
Конфигурация режима разработки	`src/cli/gateway-cli/dev.ts`	1-100
Логика освобождения порта	`src/cli/ports.ts`	1-80

Ключевые константы:

Порт по умолчанию: 18789 (источник: src/gateway/server.ts)
Привязка по умолчанию: loopback (источник: src/cli/gateway-cli/run.ts:175)
Путь конфигурации режима разработки: ~/.clawdbot-dev/ (источник: src/cli/gateway-cli/dev.ts)

Ключевые функции:

runGatewayCommand(): основной вход в CLI Gateway, обработка аргументов командной строки и логики запуска
startGatewayServer(): запуск WebSocket сервера, прослушивание указанного порта
forceFreePortAndWait(): принудительное освобождение порта и ожидание
resolveGatewayService(): возвращает соответствующую реализацию демона в зависимости от платформы (macOS LaunchAgent / Linux systemd / Windows Scheduled Task)
logGatewayStartup(): вывод информации о запуске Gateway (модель, адрес прослушивания, файл логов)

Начало работы с нуля

Интеграция с популярными мессенджерами

Разблокируйте сверхспособности AI

Что делать при возникновении проблем

Запуск Gateway: Демон и режимы работы

Чему вы научитесь

Трудности, с которыми вы сталкиваетесь

Когда использовать этот метод

🎒 Подготовка перед началом

Основная идея

Следуйте моим шагам

Шаг 1: Запуск Gateway (режим переднего плана)

Шаг 2: Настройка режима привязки

Шаг 3: Установка как демон (macOS / Linux / Windows)

Шаг 4: Обработка конфликта портов (--force)

Шаг 5: Режим разработки (--dev)

Шаг 6: Интеграция Tailscale

Шаг 7: Проверка состояния Gateway

Предупреждения о ловушках

❌ Ошибка: Gateway отказывается запускаться

❌ Ошибка: привязка к LAN, но нет аутентификации

❌ Ошибка: порт уже занят

❌ Ошибка: для сброса режима dev требуется --dev

❌ Ошибка: служба установлена, но все равно используется режим переднего плана

Итог урока

Предварительный просмотр следующего урока

Приложение: справочник по исходному коду

Запуск Gateway: Демон и режимы работы ​

Чему вы научитесь ​

Трудности, с которыми вы сталкиваетесь ​

Когда использовать этот метод ​

🎒 Подготовка перед началом ​

Основная идея ​

Следуйте моим шагам ​

Шаг 1: Запуск Gateway (режим переднего плана) ​

Шаг 2: Настройка режима привязки ​

Шаг 3: Установка как демон (macOS / Linux / Windows) ​

Шаг 4: Обработка конфликта портов (--force) ​

Шаг 5: Режим разработки (--dev) ​

Шаг 6: Интеграция Tailscale ​

Шаг 7: Проверка состояния Gateway ​

Предупреждения о ловушках ​

❌ Ошибка: Gateway отказывается запускаться ​

❌ Ошибка: привязка к LAN, но нет аутентификации ​

❌ Ошибка: порт уже занят ​

❌ Ошибка: для сброса режима dev требуется --dev ​

❌ Ошибка: служба установлена, но все равно используется режим переднего плана ​

Итог урока ​

Предварительный просмотр следующего урока ​

Приложение: справочник по исходному коду ​

Запуск Gateway: Демон и режимы работы

Чему вы научитесь

Трудности, с которыми вы сталкиваетесь

Когда использовать этот метод

🎒 Подготовка перед началом

Основная идея

Следуйте моим шагам

Шаг 1: Запуск Gateway (режим переднего плана)

Шаг 2: Настройка режима привязки

Шаг 3: Установка как демон (macOS / Linux / Windows)

Шаг 4: Обработка конфликта портов (--force)

Шаг 5: Режим разработки (--dev)

Шаг 6: Интеграция Tailscale

Шаг 7: Проверка состояния Gateway

Предупреждения о ловушках

❌ Ошибка: Gateway отказывается запускаться

❌ Ошибка: привязка к LAN, но нет аутентификации

❌ Ошибка: порт уже занят

❌ Ошибка: для сброса режима dev требуется --dev

❌ Ошибка: служба установлена, но все равно используется режим переднего плана

Итог урока

Предварительный просмотр следующего урока

Приложение: справочник по исходному коду