Docker

Docker необязателен. Используйте его только если вам нужен контейнеризированный Gateway или проверка Docker-сценария.

Подходит ли мне Docker?

• Да: вам нужна изолированная одноразовая среда Gateway или запуск OpenClaw на хосте без локальных установок.
• Нет: вы запускаете OpenClaw на своей машине и хотите самый быстрый цикл разработки. Вместо этого используйте обычный процесс установки.
• Примечание о песочнице: стандартный бэкенд песочницы использует Docker, когда песочница включена, но песочница по умолчанию отключена и не требует запуска всего Gateway в Docker. Также доступны бэкенды песочницы SSH и OpenShell. См. Песочница.

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

• Docker Desktop (или Docker Engine) + Docker Compose v2
• Минимум 2 ГБ ОЗУ для сборки образа (pnpm install может быть завершен из-за нехватки памяти на хостах с 1 ГБ с кодом выхода 137)
• Достаточно места на диске для образов и журналов
• При запуске на VPS/публичном хосте изучите Усиление безопасности для сетевой доступности, особенно политику файрвола Docker DOCKER-USER.

Контейнеризированный Gateway

./scripts/docker/setup.sh

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"./scripts/docker/setup.sh

export OPENCLAW_IMAGE="openclaw/openclaw:latest"./scripts/docker/setup.sh

docker load -i openclaw-image.tarexport OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"./scripts/docker/setup.sh --offline

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

# WhatsApp (QR)docker compose run --rm openclaw-cli channels login # Telegramdocker compose run --rm openclaw-cli channels add --channel telegram --token "<token>" # Discorddocker compose run --rm openclaw-cli channels add --channel discord --token "<token>"

Ручной процесс

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

docker build -t openclaw:local -f Dockerfile .docker compose run --rm --no-deps --entrypoint node openclaw-gateway \  dist/index.js onboard --mode local --no-install-daemondocker compose run --rm --no-deps --entrypoint node openclaw-gateway \  dist/index.js config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"},{"path":"gateway.controlUi.allowedOrigins","value":["http://localhost:18789","http://127.0.0.1:18789"]}]'docker compose up -d openclaw-gateway

Переменные окружения

Скрипт настройки принимает следующие необязательные переменные окружения:

Официальный образ Docker не включает Homebrew. Во время первичной настройки OpenClaw скрывает установщики зависимостей Skills, доступные только через brew, когда он работает в Linux- контейнере без brew; эти зависимости должны быть предоставлены пользовательским образом или установлены вручную. Для зависимостей, доступных из пакетов Debian, используйте OPENCLAW_IMAGE_APT_PACKAGES во время сборки образа. Устаревшее имя OPENCLAW_DOCKER_APT_PACKAGES по-прежнему принимается. Для зависимостей Python используйте OPENCLAW_IMAGE_PIP_PACKAGES. Это выполняет python3 -m pip install --break-system-packages во время сборки образа, поэтому закрепляйте версии пакетов и используйте только доверенные индексы пакетов.

Сопровождающие могут тестировать исходный код встроенного Plugin с упакованным образом, смонтировав один каталог исходного кода Plugin поверх его упакованного пути исходного кода, например OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro. Этот смонтированный каталог исходного кода переопределяет соответствующий скомпилированный бандл /app/dist/extensions/synology-chat для того же идентификатора Plugin.

Наблюдаемость

Экспорт OpenTelemetry выполняется из контейнера Gateway наружу к вашему коллектору OTLP. Он не требует опубликованного порта Docker. Если вы собираете образ локально и хотите, чтобы встроенный экспортер OpenTelemetry был доступен внутри образа, добавьте его runtime-зависимости:

export OPENCLAW_EXTENSIONS="diagnostics-otel"export OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4318"export OTEL_SERVICE_NAME="openclaw-gateway"./scripts/docker/setup.sh

Установите официальный Plugin @openclaw/diagnostics-otel из ClawHub в упакованных установках Docker перед включением экспорта. Пользовательские образы, собранные из исходного кода, могут по-прежнему включать локальный исходный код Plugin с OPENCLAW_EXTENSIONS=diagnostics-otel. Чтобы включить экспорт, разрешите и включите Plugin diagnostics-otel в конфигурации, затем задайте diagnostics.otel.enabled=true или используйте пример конфигурации в Экспорт OpenTelemetry . Заголовки аутентификации коллектора настраиваются через diagnostics.otel.headers, а не через переменные окружения Docker.

Метрики Prometheus используют уже опубликованный порт Gateway. Установите clawhub:@openclaw/diagnostics-prometheus, включите Plugin diagnostics-prometheus, затем собирайте метрики:

http://<gateway-host>:18789/api/diagnostics/prometheus

Маршрут защищен аутентификацией Gateway. Не открывайте отдельный публичный порт /metrics или неаутентифицированный путь reverse-proxy. См. Метрики Prometheus.

Проверки работоспособности

Конечные точки проб контейнера (аутентификация не требуется):

curl -fsS http://127.0.0.1:18789/healthz   # livenesscurl -fsS http://127.0.0.1:18789/readyz     # readiness

Образ Docker включает встроенный HEALTHCHECK, который опрашивает /healthz. Если проверки продолжают завершаться ошибкой, Docker помечает контейнер как unhealthy, и системы оркестрации могут перезапустить или заменить его.

Аутентифицированный глубокий снимок состояния:

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

LAN и loopback

scripts/docker/setup.sh по умолчанию задает OPENCLAW_GATEWAY_BIND=lan, чтобы доступ с хоста к http://127.0.0.1:18789 работал через публикацию порта Docker.

• lan (по умолчанию): браузер хоста и CLI хоста могут обращаться к опубликованному порту Gateway.
• loopback: только процессы внутри сетевого пространства имен контейнера могут напрямую обращаться к Gateway.

Локальные провайдеры хоста

Когда OpenClaw работает в Docker, 127.0.0.1 внутри контейнера — это сам контейнер, а не ваша хост-машина. Используйте host.docker.internal для AI-провайдеров, которые работают на хосте:

Встроенная настройка Docker использует эти URL хоста как значения по умолчанию для подключения LM Studio и Ollama при onboarding, а docker-compose.yml сопоставляет host.docker.internal с host gateway Docker для Linux Docker Engine. Docker Desktop уже предоставляет то же имя хоста в macOS и Windows.

Сервисы хоста также должны слушать на адресе, доступном из Docker:

lms server start --port 1234 --bind 0.0.0.0OLLAMA_HOST=0.0.0.0:11434 ollama serve

Если вы используете собственный файл Compose или команду docker run, добавьте такое же сопоставление хоста самостоятельно, например --add-host=host.docker.internal:host-gateway.

Бэкенд Claude CLI в Docker

Официальный Docker-образ OpenClaw не предустанавливает Claude Code. Установите и войдите в Claude Code внутри пользователя контейнера, который запускает OpenClaw, затем сохраните домашний каталог этого контейнера, чтобы обновления образа не стирали бинарный файл или состояние аутентификации Claude.

Для новых установок Docker включите постоянный том /home/node перед запуском настройки:

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"export OPENCLAW_HOME_VOLUME="openclaw_home"./scripts/docker/setup.sh

Для существующей установки Docker сначала остановите стек и повторно загрузите текущие значения Docker .env перед повторным запуском настройки. Скрипт настройки сам не читает .env; он перезаписывает .env из текущей оболочки и значений по умолчанию. Для сгенерированного .env выполните:

set -a. ./.envset +aexport OPENCLAW_HOME_VOLUME="${OPENCLAW_HOME_VOLUME:-openclaw_home}"./scripts/docker/setup.sh

Если ваш .env содержит значения, которые ваша оболочка не может загрузить, сначала вручную повторно экспортируйте существующие значения, на которые вы полагаетесь, такие как OPENCLAW_IMAGE, порты, режим привязки, пользовательские пути, OPENCLAW_EXTRA_MOUNTS, песочница и настройки пропуска onboarding. Сгенерированный overlay монтирует домашний том как для openclaw-gateway, так и для openclaw-cli.

Запускайте оставшиеся команды со сгенерированным overlay Compose, чтобы оба сервиса монтировали сохраненный домашний каталог. Если ваша настройка также использует docker-compose.override.yml, включите его перед docker-compose.extra.yml.

Установите Claude Code в этот сохраненный домашний каталог:

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint sh openclaw-cli -lc \  'curl -fsSL https://claude.ai/install.sh | bash'

Нативный установщик записывает бинарный файл claude в /home/node/.local/bin/claude. Укажите OpenClaw использовать этот путь внутри контейнера:

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli config set \  agents.defaults.cliBackends.claude-cli.command \  /home/node/.local/bin/claude

Войдите в систему и проверьте изнутри того же сохраненного домашнего каталога контейнера:

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint /home/node/.local/bin/claude openclaw-cli auth logindocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint /home/node/.local/bin/claude openclaw-cli auth status --textdocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli models auth login \  --provider anthropic --method cli --set-defaultdocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli models list --provider anthropic

После этого можно использовать встроенный бэкенд claude-cli:

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli agent \  --agent main \  --model claude-cli/claude-sonnet-4-6 \  --message "Say hello from Docker Claude CLI"

OPENCLAW_HOME_VOLUME сохраняет нативную установку Claude Code в /home/node/.local/bin и /home/node/.local/share/claude, а также настройки и состояние аутентификации Claude Code в /home/node/.claude и /home/node/.claude.json. Сохранения только /home/node/.openclaw недостаточно для повторного использования Claude CLI. Если вы используете OPENCLAW_EXTRA_MOUNTS вместо домашнего тома, смонтируйте все эти пути Claude в оба сервиса Docker.

Bonjour / mDNS

Сетевой мост Docker обычно ненадежно пересылает multicast Bonjour/mDNS (224.0.0.251:5353). Поэтому встроенная настройка Compose по умолчанию задает OPENCLAW_DISABLE_BONJOUR=1, чтобы Gateway не уходил в цикл сбоев и не перезапускал рекламу снова и снова, когда мост отбрасывает multicast-трафик.

Для Docker-хостов используйте опубликованный URL Gateway, Tailscale или wide-area DNS-SD. Задавайте OPENCLAW_DISABLE_BONJOUR=0 только при запуске с host networking, macvlan или другой сетью, где multicast mDNS заведомо работает.

О подводных камнях и устранении неполадок см. обнаружение Bonjour.

Хранилище и сохранение данных

Docker Compose монтирует bind-mount OPENCLAW_CONFIG_DIR в /home/node/.openclaw, OPENCLAW_WORKSPACE_DIR в /home/node/.openclaw/workspace и OPENCLAW_AUTH_PROFILE_SECRET_DIR в /home/node/.config/openclaw, поэтому эти пути сохраняются при замене контейнера. Если какая-либо переменная не задана, встроенный docker-compose.yml использует запасной путь внутри ${HOME} или /tmp, если сам HOME также отсутствует. Это не дает docker compose up вывести спецификацию тома с пустым источником в минимальных окружениях.

В этом смонтированном каталоге конфигурации OpenClaw хранит:

• openclaw.json для конфигурации поведения
• agents/<agentId>/agent/auth-profiles.json для сохраненной OAuth/API-key-аутентификации провайдера
• .env для runtime-секретов из переменных окружения, таких как OPENCLAW_GATEWAY_TOKEN

Каталог секретного ключа auth-profile хранит локальный ключ шифрования, используемый для материала токенов профиля аутентификации на основе OAuth. Храните его вместе с состоянием вашего Docker-хоста, но отдельно от OPENCLAW_CONFIG_DIR.

Установленные загружаемые plugins хранят состояние своих пакетов в смонтированном домашнем каталоге OpenClaw, поэтому записи об установке plugin и корни пакетов сохраняются при замене контейнера. Запуск Gateway не создает деревья зависимостей bundled-plugin.

Полные сведения о сохранении данных в развертываниях VM см. в Среда выполнения Docker VM — что и где сохраняется.

Очаги роста диска: следите за media/, JSONL-файлами сессий, общей базой данных состояния SQLite, корнями пакетов установленных plugin и ротационными файловыми логами в /tmp/openclaw/.

Вспомогательные shell-скрипты (необязательно)

Для более удобного повседневного управления Docker установите ClawDock:

mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/clawdock/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.shecho 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc

Если вы установили ClawDock из старого raw-пути scripts/shell-helpers/clawdock-helpers.sh, повторно выполните приведенную выше команду установки, чтобы ваш локальный файл помощника отслеживал новое расположение.

Затем используйте clawdock-start, clawdock-stop, clawdock-dashboard и т. д. Выполните clawdock-help, чтобы увидеть все команды. Полное руководство по помощнику см. в ClawDock.

export OPENCLAW_SANDBOX=1./scripts/docker/setup.sh

export OPENCLAW_SANDBOX=1export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock./scripts/docker/setup.sh

docker compose run -T --rm openclaw-cli gateway probedocker compose run -T --rm openclaw-cli devices list --json

printf '%s\n' \  'services:' \  '  openclaw-cli:' \  '    cap_drop: !reset []' \  > docker-compose.cli-no-dropped-caps.local.yml docker compose -f docker-compose.yml -f docker-compose.cli-no-dropped-caps.local.yml run --rm openclaw-cli plugins install <package>

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

FROM node:24-bookwormRUN curl -fsSL https://bun.sh/install | bashENV PATH="/root/.bun/bin:${PATH}"RUN corepack enableWORKDIR /appCOPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./COPY ui/package.json ./ui/package.jsonCOPY scripts ./scriptsRUN pnpm install --frozen-lockfileCOPY . .RUN pnpm buildRUN pnpm ui:installRUN pnpm ui:buildENV NODE_ENV=productionCMD ["node","dist/index.js"]

Запуск на VPS?

См. Hetzner (Docker VPS) и среду выполнения Docker VM для общих шагов развертывания VM, включая встраивание бинарных файлов, сохранение данных и обновления.

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

Когда agents.defaults.sandbox включен с бэкендом Docker, gateway запускает выполнение инструментов агента (shell, чтение/запись файлов и т. д.) внутри изолированных Docker-контейнеров, а сам gateway остается на хосте. Это дает жесткую границу вокруг недоверенных или многопользовательских сессий агентов без контейнеризации всего gateway.

Область песочницы может быть для каждого агента (по умолчанию), для каждой сессии или общей. Каждая область получает собственное рабочее пространство, смонтированное в /workspace. Также можно настроить политики разрешения/запрета инструментов, изоляцию сети, лимиты ресурсов и контейнеры браузера.

Полную конфигурацию, образы, заметки по безопасности и многоагентные профили см.:

• Песочница -- полный справочник по песочнице
• OpenShell -- интерактивный shell-доступ к контейнерам песочницы
• Многоагентная песочница и инструменты -- переопределения для каждого агента

Быстрое включение

{  agents: {    defaults: {      sandbox: {        mode: "non-main", // off | non-main | all        scope: "agent", // session | agent | shared      },    },  },}

Соберите стандартный образ песочницы (из checkout исходников):

scripts/sandbox-setup.sh

Для установок npm без checkout исходников см. Песочница § Образы и настройка для inline-команд docker build.

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

docker compose run --rm openclaw-cli dashboard --no-opendocker compose run --rm openclaw-cli devices listdocker compose run --rm openclaw-cli devices approve <requestId>

docker compose run --rm openclaw-cli config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"}]'docker compose run --rm openclaw-cli devices list --url ws://127.0.0.1:18789

Связанные материалы

• Обзор установки — все способы установки
• Podman — альтернатива Docker на базе Podman
• ClawDock — настройка Docker Compose от сообщества
• Обновление — поддержание OpenClaw в актуальном состоянии
• Конфигурация — конфигурация gateway после установки