Установка OpenClaw через Docker

Docker — это опциональный способ запуска OpenClaw. Он подходит для изолированного развёртывания на сервере или VPS, а также для тестовых окружений. Для повседневной работы на локальном компьютере обычно удобнее использовать нативную установку.

В этом руководстве разберём, когда Docker действительно нужен, какие требования надо выполнить, как быстро запустить OpenClaw, как управлять контейнерами, подключать каналы и решать типовые проблемы.

Когда стоит использовать Docker

Запуск через Docker особенно полезен в тех случаях, когда нужен изолированный контейнерный запуск на VPS или сервере, одноразовое тестовое окружение либо песочница для агентов. Если вы запускаете OpenClaw на своём Mac или Windows только для обычной работы, чаще всего лучше выбрать нативную установку.

Требования

• Docker Desktop или Docker Engine
• Docker Compose v2
• Достаточное количество свободного места на диске для образов и логов

Перед началом проверьте, что Docker установлен и доступен в системе:

docker --version docker compose version

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

Рекомендуемый способ — клонировать репозиторий OpenClaw и запустить скрипт настройки. Он автоматизирует основные шаги и упрощает первый запуск.

git clone https://github.com/openclaw/openclaw.git cd openclaw ./docker-setup.sh

Скрипт автоматически:

1. собирает Docker-образ gateway;
2. запускает мастер первичной настройки;
3. показывает подсказки по подключению провайдера LLM;
4. поднимает gateway через Docker Compose;
5. генерирует токен gateway и записывает его в файл .env.

После завершения откройте в браузере адрес http://127.0.0.1:18789/, затем вставьте токен в Control UI в разделе настроек. Если токен понадобится снова, выполните:

docker compose run --rm openclaw-cli dashboard --no-open

Конфигурация сохраняется на хосте в каталогах ~/.openclaw/ и ~/.openclaw/workspace.

Ручной запуск через Docker Compose

Если вы хотите контролировать каждый шаг самостоятельно, можно выполнить запуск вручную:

docker build -t openclaw:local -f Dockerfile . docker compose run --rm openclaw-cli onboard docker compose up -d openclaw-gateway

Как устроен официальный docker-compose

Официальная схема развёртывания включает два сервиса:

• openclaw-gateway — основной сервис gateway;
• openclaw-cli — CLI-контейнер для настройки и служебных команд.

Gateway использует локально собранный образ openclaw:local, а контейнер работает не от root, а от пользователя node с UID 1000. Это важно учитывать при работе с правами доступа и монтируемыми директориями.

Основные переменные окружения, такие как OPENCLAW_CONFIG_DIR, OPENCLAW_WORKSPACE_DIR и OPENCLAW_GATEWAY_TOKEN, обычно автоматически прописываются скриптом docker-setup.sh в файле .env.

Подключение каналов

После запуска gateway можно подключать нужные каналы через CLI-контейнер.

Telegram:

docker compose run --rm openclaw-cli channels add --channel telegram --token "<ваш-токен-бота>"

WhatsApp:

docker compose run --rm openclaw-cli channels login

Discord:

docker compose run --rm openclaw-cli channels add --channel discord --token "<ваш-токен>"

Управление контейнерами

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

# Статус контейнеров docker compose ps
Просмотр логов в реальном времени

docker compose logs -f

Перезапуск gateway

docker compose restart openclaw-gateway

Остановка окружения

docker compose down

Дополнительные настройки

Docker-развёртывание OpenClaw поддерживает несколько полезных опций.

Дополнительные монтирования

Если нужно пробросить директории с хоста внутрь контейнера, задайте переменную и заново выполните настройку:

export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw" ./docker-setup.sh

Сохранение каталога /home/node

Чтобы сохранить содержимое домашней директории контейнера между пересозданиями, используйте отдельный volume:

export OPENCLAW_HOME_VOLUME="openclaw_home" ./docker-setup.sh

Установка системных пакетов

При необходимости можно заранее добавить нужные пакеты в образ:

export OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg build-essential" ./docker-setup.sh

Песочница агентов

Agent Sandbox — это отдельная Docker-функция, не равная самому gateway. Gateway может работать нативно на хосте, а инструменты агента — запускаться в изолированном контейнере.

Для включения песочницы добавьте настройки в файл ~/.openclaw/openclaw.json:

{ agents: { defaults: { sandbox: { mode: "non-main", scope: "agent" } } } }

Далее можно собрать нужный образ песочницы:

# Базовая песочница scripts/sandbox-setup.sh
С инструментами разработки

scripts/sandbox-common-setup.sh

С браузером

scripts/sandbox-browser-setup.sh

По умолчанию песочница использует образ openclaw-sandbox:bookworm-slim, работает без доступа в интернет, запускается не от root и автоматически очищается при длительном простое или старении контейнера.

Развёртывание на VPS

Для VPS общий порядок действий выглядит так:

# 1. Установка Docker curl -fsSL https://get.docker.com | sh sudo usermod -aG docker $USER newgrp docker
2. Клонирование репозитория

git clone https://github.com/openclaw/openclaw.git

cd openclaw

3. Запуск настройки

./docker-setup.sh

По умолчанию gateway привязывается к режиму lan и использует порт 18789. Это стоит учитывать при настройке сетевого доступа и безопасности сервера.

Права доступа

Так как контейнер работает от пользователя node с UID 1000, возможны ошибки вида Permission denied при монтировании volume. В таком случае скорректируйте владельца каталогов:

sudo chown -R 1000:1000 ~/.openclaw ~/.openclaw/workspace

Проверка здоровья gateway

Для быстрой проверки состояния gateway выполните:

docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"

Типичные проблемы и решения

Ошибка Permission denied

Проверьте, кому принадлежат каталоги OpenClaw на хосте:

ls -ln ~/.openclaw/

Если владельцем является не UID 1000, исправьте права:

sudo chown -R 1000:1000 ~/.openclaw

Ошибка Unauthorized или pairing required

Получите новый токен gateway:

docker compose run --rm openclaw-cli dashboard --no-open

Затем подтвердите устройство:

docker compose run --rm openclaw-cli devices approve 

Контейнер уходит в цикл перезапуска

Сначала посмотрите последние логи:

docker compose logs --tail 50

Частая причина — ошибка в конфигурации, например некорректный синтаксис в openclaw.json.

Агент не отвечает в мессенджере

Проверьте, добавлен ли нужный канал:

docker compose run --rm openclaw-cli channels list

Также убедитесь, что у контейнера есть необходимый сетевой доступ.

Что делать дальше

После успешной установки можно переходить к следующим шагам: выбрать нативную установку для других платформ, усилить безопасность VPS, настроить Telegram-бота или подключить дополнительные каналы общения.

Docker-подход особенно хорош тогда, когда нужен чистый, управляемый и воспроизводимый способ запуска OpenClaw. Для серверов и тестовых сред это один из самых удобных вариантов.