Обзор развертывания OpenClaw на сервере¶

Предварительные требования¶

Для корректной работы приложения требуются следующие условия:

Операционная система: Debian 11+ или Ubuntu 20.04+.
Права доступа: Права суперпользователя (root) для установки системных пакетов и настройки сервисов.
Порты:
80/tcp — HTTP (для проверки SSL и перенаправления).
443/tcp — HTTPS (основной доступ к панели управления).
18789/tcp — локальный порт шлюза OpenClaw.

FDQN итоговой панели на домене hostkey.in¶

Доступ к веб-интерфейсу осуществляется через персональный поддомен, сформированный по следующему шаблону:

Параметр	Значение
Префикс	`openclaw`
Домен	`hostkey.in`
Полный шаблон	`openclaw{Server_ID_from_Invapi}.hostkey.in`

Структура файлов и каталогов¶

Основные директории, используемые в системе:

/home/openclaw — домашний каталог пользователя приложения.
/home/openclaw/.openclaw — конфигурационные файлы OpenClaw.
/root/nginx — рабочая директория Docker Compose для прокси-сервера.
/data/nginx — пользовательские конфигурации Nginx и данные Certbot.
/etc/systemd/system/openclaw-gateway.service — системный юнит сервиса шлюза.

Процесс установки приложения¶

Развертывание OpenClaw выполняется в несколько этапов:

Подготовка системы:
Очистка существующих репозиториев NodeSource и Docker для предотвращения конфликтов.
Установка базовых системных пакетов (ca-certificates, curl, gnupg, sudo, dbus-user-session).
Установка Docker и настройка окружения для работы с SSL-сертификатами.
Установка среды выполнения:
Добавление официального репозитория NodeSource.
Установка Node.js (версия 24 или выше).
Глобальная установка пакетного менеджера pnpm.
Развертывание OpenClaw:
Создание системного пользователя openclaw с ограниченными правами.
Глобальная установка пакета openclaw@latest через pnpm.
Выполнение автоматической инициализации (onboard) для настройки локального режима работы.
Настройка конфигурации шлюза для поддержки работы через обратный прокси (Reverse Proxy).
Настройка веб-прокси:
Создание конфигурационных файлов Nginx с поддержкой SSL и перенаправлением трафика с HTTP на HTTPS.
Запуск контейнера для автоматического получения и обновления сертификатов Let's Encrypt.

Права доступа и безопасность¶

Для работы приложения используется выделенный пользователь openclaw.
Включена функция "lingering" для пользователя openclaw, что позволяет процессам продолжать работу после завершения сессии.
Настроен безопасный путь (secure_path) в sudoers для корректной работы бинарных файлов pnpm и openclaw.
Файлы конфигурации и токены доступа имеют ограниченные права доступа (например, 0600 или 0700).
Включено автоматическое обновление системных пакетов (unattended-upgrades).

Базы данных¶

Приложение использует локальный режим работы. Данные хранятся в директориях пользователя openclaw.

Контейнеры Docker и их запуск¶

Для обеспечения работы веб-интерфейса через защищенное соединение используется следующий контейнер:

Параметр	Значение
Имя образа	`jonasal/nginx-certbot:latest`
Режим сети	`host`
Тома (volumes)	`nginx_secrets:/etc/letsencrypt` `/data/nginx/user_conf.d:/etc/nginx/user_conf.d`
Переменные окружения	`CERTBOT_EMAIL=hkadm@hostkey.com` `RENEWAL_INTERVAL=8d`
Политика перезапуска	`unless-stopped`

Кастомные скрипты и дополнительные настройки¶

В процессе развертывания выполняются следующие действия:

Инициализация OpenClaw: Выполняется команда openclaw onboard --non-interactive, которая настраивает шлюз в локальном режиме с использованием токена безопасности.
Патч конфигурации: Скрипт модифицирует JSON5-конфигурацию приложения, чтобы разрешить запросы от доверенных прокси (127.0.0.1) и настроить allowedOrigins для работы через HTTPS.
Настройка системного сервиса: Создается и активируется unit-файл openclaw-gateway.service, который управляет процессом шлюза как фоновым системным сервисом.

Инструкция по обновлению приложения¶

Для обновления основного приложения необходимо выполнить следующие действия:

Обновить пакет через глобальный менеджер пакетов:
```
pnpm install -g openclaw@latest
```
Перезапустить системную службу шлюза для применения изменений:
```
sudo systemctl restart openclaw-gateway.service
```

Расположение конфигурационных файлов и данных¶

Конфигурация приложения: /home/openclaw/.openclaw
Конфигурация прокси (Nginx): /data/nginx/user_conf.d/{domain}.conf
Сертификаты SSL: Внутри Docker-тома nginx_secrets.

Доступные порты для подключения¶

HTTPS: 443 (через доменное имя).
HTTP: 80 (перенаправляет на HTTPS).

Запуск, остановка приложения¶

Управление шлюзом OpenClaw осуществляется через системную службу:

Запуск: sudo systemctl start openclaw-gateway.service
Остановка: sudo systemctl stop openclaw-gateway.service
Статус: sudo systemctl status openclaw-gateway.service