Docker (опционально)

Docker — опциональный способ. Используйте его, только если хотите контейнерный шлюз или проверить Docker-процесс.

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

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

В этом руководстве:

  • Контейнерный шлюз (полный OpenClaw в Docker)
  • Sandbox агентов для сессий (шлюз на хосте + изолированные инструменты агентов в Docker)

Подробнее о песочнице: Sandboxing

Требования

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

Контейнерный шлюз (Docker Compose)

Быстрый старт (рекомендуется)

Примечание: Здесь Docker по умолчанию использует режимы привязки (lan/loopback), а не псевдонимы хостов. Указывайте режимы привязки в gateway.bind (например, lan или loopback), а не псевдонимы вроде 0.0.0.0 или localhost.

Из корня репозитория:

./docker-setup.sh

Скрипт:

  • собирает образ шлюза локально (или скачивает удалённый образ, если задан OPENCLAW_IMAGE)
  • запускает мастер настройки
  • выводит подсказки по настройке провайдеров
  • запускает шлюз через Docker Compose
  • генерирует токен шлюза и записывает его в .env

Опциональные переменные окружения:

  • OPENCLAW_IMAGE — использовать удалённый образ вместо локальной сборки (например, ghcr.io/openclaw/openclaw:latest)
  • OPENCLAW_DOCKER_APT_PACKAGES — установить дополнительные apt-пакеты при сборке
  • OPENCLAW_EXTENSIONS — предустановить зависимости расширений при сборке (через пробел, например diagnostics-otel matrix)
  • OPENCLAW_EXTRA_MOUNTS — добавить дополнительные bind-монтирования хоста
  • OPENCLAW_HOME_VOLUME — сохранить /home/node в именованном volume
  • OPENCLAW_SANDBOX — включить bootstrap sandbox для Docker-шлюза. Только явные истинные значения: 1, true, yes, on
  • OPENCLAW_INSTALL_DOCKER_CLI — build arg для локальных сборок (1 устанавливает Docker CLI в образ). docker-setup.sh устанавливает это автоматически при OPENCLAW_SANDBOX=1 для локальных сборок.
  • OPENCLAW_DOCKER_SOCKET — переопределить путь к Docker-сокету (по умолчанию: DOCKER_HOST=unix://... или /var/run/docker.sock)
  • OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 — аварийный флаг: разрешить доверенные ws:// цели в частной сети для CLI/onboarding (по умолчанию только loopback)
  • OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 — отключить флаги hardening для браузера в контейнере --disable-3d-apis, --disable-software-rasterizer, --disable-gpu, когда нужна совместимость с WebGL/3D.
  • OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 — оставить расширения включёнными, если браузерные процессы требуют их (по умолчанию расширения отключены в sandbox-браузере).
  • OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N> — ограничение числа процессов рендеринга Chromium; 0 пропускает флаг, используя поведение Chromium по умолчанию.

После завершения:

  • Откройте http://127.0.0.1:18789/ в браузере.
  • Вставьте токен в Control UI (Настройки → токен).
  • Нужен URL повторно? Выполните docker compose run --rm openclaw-cli dashboard --no-open.

Включение sandbox агентов для Docker-шлюза (opt-in)

docker-setup.sh также может настроить agents.defaults.sandbox.* для Docker-развёртываний.

Включение:

export OPENCLAW_SANDBOX=1
./docker-setup.sh

Нестандартный путь к сокету (например, rootless Docker):

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

Замечания:

  • Скрипт монтирует docker.sock только после прохождения проверок sandbox.
  • Если настройка sandbox не завершена, скрипт сбрасывает agents.defaults.sandbox.mode в off, чтобы избежать устаревшей/неработающей конфигурации.
  • Если Dockerfile.sandbox отсутствует, скрипт выводит предупреждение и продолжает; при необходимости соберите openclaw-sandbox:bookworm-slim скриптом scripts/sandbox-setup.sh.
  • Для удалённых значений OPENCLAW_IMAGE образ должен уже содержать Docker CLI.

Автоматизация/CI (неинтерактивный режим, без TTY)

Для скриптов и CI отключите выделение pseudo-TTY в Compose флагом -T:

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

Если в автоматизации не экспортированы переменные Claude-сессии, они теперь по умолчанию разрешаются в пустые значения в docker-compose.yml, чтобы избежать предупреждений «variable is not set».

Безопасность общей сети (CLI + шлюз)

openclaw-cli использует network_mode: "service:openclaw-gateway", чтобы CLI-команды надёжно достигали шлюза через 127.0.0.1 в Docker.

Считайте это общей границей доверия: привязка к loopback не обеспечивает изоляцию между этими двумя контейнерами. Если нужна более строгая изоляция, запускайте команды из отдельного контейнера/хостовой сети вместо встроенного сервиса openclaw-cli.

Для снижения последствий компрометации CLI-процесса конфигурация compose убирает NET_RAW/NET_ADMIN и включает no-new-privileges для openclaw-cli.

Записываемые данные на хосте:

  • ~/.openclaw/
  • ~/.openclaw/workspace

Запускаете на VPS? См. Hetzner (Docker VPS).

Использование удалённого образа (без локальной сборки)

Официальные готовые образы публикуются в:

Используйте образ ghcr.io/openclaw/openclaw (не одноимённые образы на Docker Hub).

Основные теги:

  • main — последняя сборка из main
  • <version> — сборки по тегу релиза (например, 2026.2.26)
  • latest — последний стабильный релиз

Метаданные базового образа

Основной Docker-образ сейчас использует:

  • node:24-bookworm

Образ публикует OCI-аннотации базового образа (sha256 — пример, указывает на закреплённый мультиархитектурный manifest):

  • org.opencontainers.image.base.name=docker.io/library/node:24-bookworm
  • org.opencontainers.image.base.digest=sha256:3a09aa6354567619221ef6c45a5051b671f953f0a1924d1f819ffb236e520e6b
  • org.opencontainers.image.source=https://github.com/openclaw/openclaw
  • org.opencontainers.image.url=https://openclaw.ai
  • org.opencontainers.image.documentation=https://docs.openclaw.ai/install/docker
  • org.opencontainers.image.licenses=MIT
  • org.opencontainers.image.title=OpenClaw
  • org.opencontainers.image.description=OpenClaw gateway and CLI runtime container image
  • org.opencontainers.image.revision=<git-sha>
  • org.opencontainers.image.version=<tag-or-main>
  • org.opencontainers.image.created=<rfc3339 timestamp>

Справка: OCI image annotations

Контекст: в истории тегов этого репозитория Bookworm используется уже с v2026.2.22 и более ранних тегов 2026 года (например, v2026.2.21, v2026.2.9).

По умолчанию скрипт собирает образ из исходников. Чтобы скачать готовый образ, задайте OPENCLAW_IMAGE перед запуском скрипта:

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

Скрипт определяет, что OPENCLAW_IMAGE не является openclaw:local по умолчанию, и выполняет docker pull вместо docker build. Всё остальное (настройка, запуск шлюза, генерация токена) работает так же.

docker-setup.sh запускается из корня репозитория, так как использует локальные docker-compose.yml и вспомогательные файлы. OPENCLAW_IMAGE пропускает локальную сборку; он не заменяет весь compose/setup-процесс.

Shell-хелперы (опционально)

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

mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/shell-helpers/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh

Добавьте в конфигурацию оболочки (zsh):

echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc

Далее используйте clawdock-start, clawdock-stop, clawdock-dashboard и т.д. Все команды — clawdock-help.

Подробнее — ClawDock Helper README.

Ручной процесс (compose)

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

Запускайте docker compose ... из корня репозитория. Если вы использовали OPENCLAW_EXTRA_MOUNTS или OPENCLAW_HOME_VOLUME, скрипт создаёт docker-compose.extra.yml; подключайте его при запуске Compose:

docker compose -f docker-compose.yml -f docker-compose.extra.yml <command>

Токен Control UI + сопряжение (Docker)

Если видите «unauthorized» или «disconnected (1008): pairing required», получите свежую ссылку на dashboard и подтвердите браузерное устройство:

docker compose run --rm openclaw-cli dashboard --no-open
docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>

Подробнее: Dashboard, Devices.

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

Чтобы смонтировать дополнительные хостовые директории в контейнеры, задайте OPENCLAW_EXTRA_MOUNTS перед запуском docker-setup.sh. Принимает список Docker bind-монтирований через запятую, которые применяются к openclaw-gateway и openclaw-cli через генерацию docker-compose.extra.yml.

Пример:

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

Замечания:

  • Пути должны быть расшарены в Docker Desktop на macOS/Windows.
  • Каждая запись — source:target[:options] без пробелов, табуляций и переносов строк.
  • При изменении OPENCLAW_EXTRA_MOUNTS перезапустите docker-setup.sh для пересоздания extra compose-файла.
  • docker-compose.extra.yml генерируется автоматически. Не редактируйте его вручную.

Сохранение домашней директории контейнера (опционально)

Чтобы /home/node сохранялся при пересоздании контейнера, задайте именованный volume через OPENCLAW_HOME_VOLUME. Это создаёт Docker volume и монтирует его в /home/node, сохраняя стандартные bind-монтирования config/workspace. Используйте именованный volume (не bind-путь); для bind-монтирований используйте OPENCLAW_EXTRA_MOUNTS.

Пример:

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

Можно комбинировать с дополнительными монтированиями:

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

Замечания:

  • Имена volume должны соответствовать ^[A-Za-z0-9][A-Za-z0-9_.-]*$.
  • При изменении OPENCLAW_HOME_VOLUME перезапустите docker-setup.sh.
  • Именованный volume сохраняется до удаления через docker volume rm <name>.

Установка дополнительных apt-пакетов (опционально)

Если нужны системные пакеты внутри образа (например, инструменты сборки или медиа-библиотеки), задайте OPENCLAW_DOCKER_APT_PACKAGES перед запуском docker-setup.sh. Пакеты устанавливаются при сборке образа и сохраняются при удалении контейнера.

Пример:

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

Замечания:

  • Принимает список apt-пакетов через пробел.
  • При изменении OPENCLAW_DOCKER_APT_PACKAGES перезапустите docker-setup.sh для пересборки образа.

Предустановка зависимостей расширений (опционально)

Расширения с собственным package.json (например, diagnostics-otel, matrix, msteams) устанавливают npm-зависимости при первой загрузке. Чтобы включить зависимости в образ, задайте OPENCLAW_EXTENSIONS перед запуском docker-setup.sh:

export OPENCLAW_EXTENSIONS="diagnostics-otel matrix"
./docker-setup.sh

Или при сборке напрямую:

docker build --build-arg OPENCLAW_EXTENSIONS="diagnostics-otel matrix" .

Замечания:

  • Принимает список директорий расширений через пробел (из extensions/).
  • Затрагиваются только расширения с package.json; лёгкие плагины без него игнорируются.
  • При изменении OPENCLAW_EXTENSIONS перезапустите docker-setup.sh для пересборки.

Продвинутый / полнофункциональный контейнер (opt-in)

Docker-образ по умолчанию ориентирован на безопасность и работает от непривилегированного пользователя node. Это минимизирует поверхность атаки, но означает:

  • нельзя устанавливать системные пакеты в runtime
  • нет Homebrew по умолчанию
  • нет встроенных браузеров Chromium/Playwright

Для более функционального контейнера используйте opt-in настройки:

  1. Сохранение /home/node — чтобы загруженные браузеры и кеши инструментов сохранялись:
export OPENCLAW_HOME_VOLUME="openclaw_home"
./docker-setup.sh
  1. Встраивание системных зависимостей в образ (воспроизводимо и постоянно):
export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"
./docker-setup.sh
  1. Установка браузеров Playwright без npx (избежание конфликтов npm override):
docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium

Если Playwright нужно установить системные зависимости, пересоберите образ с OPENCLAW_DOCKER_APT_PACKAGES вместо использования --with-deps в runtime.

  1. Сохранение загруженных браузеров Playwright:
  • Задайте PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright в docker-compose.yml.
  • Убедитесь, что /home/node сохраняется через OPENCLAW_HOME_VOLUME, или смонтируйте /home/node/.cache/ms-playwright через OPENCLAW_EXTRA_MOUNTS.

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

Образ работает от пользователя node (uid 1000). Если видите ошибки прав доступа к /home/node/.openclaw, убедитесь, что хостовые bind-монтирования принадлежат uid 1000.

Пример (Linux-хост):

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

Если решите запускать от root — вы принимаете на себя риски безопасности.

Ускорение пересборки (рекомендуется)

Для ускорения пересборок упорядочьте Dockerfile так, чтобы слои зависимостей кешировались. Это позволяет не перезапускать pnpm install при неизменных lockfile:

FROM node:24-bookworm

# Установка Bun (требуется для скриптов сборки)
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"

RUN corepack enable

WORKDIR /app

# Кеширование зависимостей, пока не изменились метаданные пакетов
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY scripts ./scripts

RUN pnpm install --frozen-lockfile

COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build

ENV NODE_ENV=production

CMD ["node","dist/index.js"]

Настройка каналов (опционально)

Используйте CLI-контейнер для настройки каналов, затем при необходимости перезапустите шлюз.

WhatsApp (QR):

docker compose run --rm openclaw-cli channels login

Telegram (bot token):

docker compose run --rm openclaw-cli channels add --channel telegram --token "<token>"

Discord (bot token):

docker compose run --rm openclaw-cli channels add --channel discord --token "<token>"

Документация: WhatsApp, Telegram, Discord

OpenAI Codex OAuth (headless Docker)

Если в мастере настройки вы выбрали OpenAI Codex OAuth, он открывает URL в браузере и пытается получить callback на http://127.0.0.1:1455/auth/callback. В Docker или headless-окружениях callback может показать ошибку браузера. Скопируйте полный URL редиректа и вставьте его обратно в мастер для завершения авторизации.

Health checks

Эндпоинты проверки состояния контейнера (без авторизации):

curl -fsS http://127.0.0.1:18789/healthz
curl -fsS http://127.0.0.1:18789/readyz

Псевдонимы: /health и /ready.

/healthz — поверхностная проверка живости: «процесс шлюза запущен». /readyz остаётся в состоянии ready во время grace-периода запуска, затем возвращает 503, если обязательные управляемые каналы всё ещё не подключены или отключились позже.

Docker-образ включает встроенный HEALTHCHECK, который в фоне проверяет /healthz. Простыми словами: Docker периодически проверяет, отвечает ли OpenClaw. Если проверки постоянно не проходят, Docker помечает контейнер как unhealthy, и системы оркестрации (Docker Compose restart policy, Swarm, Kubernetes и др.) могут автоматически перезапустить его.

Аутентифицированный глубокий health-снапшот (шлюз + каналы):

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

E2E smoke-тест (Docker)

scripts/e2e/onboard-docker.sh

Smoke-тест импорта QR (Docker)

pnpm test:docker:qr

LAN vs loopback (Docker Compose)

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

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

Скрипт также закрепляет gateway.mode=local после настройки, чтобы Docker CLI-команды по умолчанию использовали локальный loopback.

Замечание о legacy-конфигурации: используйте режимы привязки в gateway.bind (lan / loopback / custom / tailnet / auto), а не псевдонимы хостов (0.0.0.0, 127.0.0.1, localhost, ::, ::1).

Если видите Gateway target: ws://172.x.x.x:18789 или повторяющиеся ошибки pairing required от Docker CLI-команд, выполните:

docker compose run --rm openclaw-cli config set gateway.mode local
docker compose run --rm openclaw-cli config set gateway.bind lan
docker compose run --rm openclaw-cli devices list --url ws://127.0.0.1:18789

Замечания

  • Привязка шлюза по умолчанию — lan для контейнерного использования (OPENCLAW_GATEWAY_BIND).
  • Dockerfile CMD использует --allow-unconfigured; смонтированный конфиг с gateway.mode не local всё равно запустится. Переопределите CMD для принудительной проверки.
  • Контейнер шлюза — источник истины для сессий (~/.openclaw/agents/<agentId>/sessions/).

Модель хранения

  • Постоянные данные хоста: Docker Compose bind-монтирует OPENCLAW_CONFIG_DIR в /home/node/.openclaw и OPENCLAW_WORKSPACE_DIR в /home/node/.openclaw/workspace, так что эти данные переживают замену контейнера.
  • Эфемерный tmpfs sandbox: при включённом agents.defaults.sandbox sandbox-контейнеры используют tmpfs для /tmp, /var/tmp и /run. Эти монтирования отделены от основного Compose-стека и исчезают вместе с sandbox-контейнером.
  • Точки роста диска: следите за media/, agents/<agentId>/sessions/sessions.json, JSONL-файлами транскриптов, cron/runs/*.jsonl и ротируемыми лог-файлами в /tmp/openclaw/ (или заданном logging.file). Если вы также запускаете macOS-приложение вне Docker, его логи хранятся отдельно: ~/.openclaw/logs/gateway.log, ~/.openclaw/logs/gateway.err.log и /tmp/openclaw/openclaw-gateway.log.

Sandbox агентов (шлюз на хосте + инструменты в Docker)

Подробнее: Sandboxing

Что это делает

Когда agents.defaults.sandbox включён, неосновные сессии запускают инструменты внутри Docker-контейнера. Шлюз остаётся на хосте, но выполнение инструментов изолировано:

  • scope: "agent" по умолчанию (один контейнер + workspace на агента)
  • scope: "session" — изоляция на уровне сессий
  • workspace каждого scope монтируется в /workspace
  • опциональный доступ к workspace агента (agents.defaults.sandbox.workspaceAccess)
  • политика allow/deny для инструментов (deny имеет приоритет)
  • входящие медиа копируются в workspace активного sandbox (media/inbound/*), чтобы инструменты могли их читать (при workspaceAccess: "rw" данные попадают в workspace агента)

Предупреждение: scope: "shared" отключает межсессионную изоляцию. Все сессии используют один контейнер и один workspace.

Профили sandbox для отдельных агентов (multi-agent)

При использовании мультиагентной маршрутизации каждый агент может переопределить настройки sandbox и инструментов: agents.list[].sandbox и agents.list[].tools (плюс agents.list[].tools.sandbox.tools). Это позволяет использовать разные уровни доступа в одном шлюзе:

  • Полный доступ (личный агент)
  • Инструменты только на чтение + workspace только на чтение (семейный/рабочий агент)
  • Без инструментов файловой системы/shell (публичный агент)

Подробнее — Multi-Agent Sandbox & Tools.

Поведение по умолчанию

  • Образ: openclaw-sandbox:bookworm-slim
  • Один контейнер на агента
  • Доступ к workspace агента: workspaceAccess: "none" (по умолчанию) использует ~/.openclaw/sandboxes
    • "ro" — sandbox-workspace в /workspace, workspace агента монтируется только на чтение в /agent (отключает write/edit/apply_patch)
    • "rw" — workspace агента монтируется с доступом на запись в /workspace
  • Автоочистка: неактивен > 24ч ИЛИ возраст > 7 дней
  • Сеть: none по умолчанию (явный opt-in для egress)
    • host заблокирован.
    • container:<id> заблокирован по умолчанию (риск namespace-join).
  • Allow по умолчанию: exec, process, read, write, edit, sessions_list, sessions_history, sessions_send, sessions_spawn, session_status
  • Deny по умолчанию: browser, canvas, nodes, cron, discord, gateway

Включение песочницы

Если планируете устанавливать пакеты в setupCommand, учтите:

  • docker.network по умолчанию "none" (нет egress).
  • docker.network: "host" заблокирован.
  • docker.network: "container:<id>" заблокирован по умолчанию.
  • Аварийный флаг: agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true.
  • readOnlyRoot: true блокирует установку пакетов.
  • user должен быть root для apt-get (не задавайте user или укажите user: "0:0"). OpenClaw автоматически пересоздаёт контейнеры при изменении setupCommand (или конфигурации docker), если контейнер не был недавно использован (в течение ~5 минут). Горячие контейнеры выводят предупреждение с командой openclaw sandbox recreate ....
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared (agent is default)
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256,
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "openclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
        },
        prune: {
          idleHours: 24, // 0 отключает очистку по простою
          maxAgeDays: 7, // 0 отключает очистку по возрасту
        },
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: [
          "exec",
          "process",
          "read",
          "write",
          "edit",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
        ],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
      },
    },
  },
}

Настройки hardening находятся в agents.defaults.sandbox.docker: network, user, pidsLimit, memory, memorySwap, cpus, ulimits, seccompProfile, apparmorProfile, dns, extraHosts, dangerouslyAllowContainerNamespaceJoin (только аварийный флаг).

Multi-agent: переопределяйте agents.defaults.sandbox.{docker,browser,prune}.* для каждого агента через agents.list[].sandbox.{docker,browser,prune}.* (игнорируется при agents.defaults.sandbox.scope / agents.list[].sandbox.scope равном "shared").

Сборка образа sandbox по умолчанию

scripts/sandbox-setup.sh

Собирает openclaw-sandbox:bookworm-slim из Dockerfile.sandbox.

Общий образ sandbox (опционально)

Если нужен образ sandbox с инструментами сборки (Node, Go, Rust и др.), соберите общий образ:

scripts/sandbox-common-setup.sh

Собирает openclaw-sandbox-common:bookworm-slim. Для использования:

{
  agents: {
    defaults: {
      sandbox: { docker: { image: "openclaw-sandbox-common:bookworm-slim" } },
    },
  },
}

Образ sandbox с браузером

Для запуска инструмента browser внутри sandbox соберите образ с браузером:

scripts/sandbox-browser-setup.sh

Собирает openclaw-sandbox-browser:bookworm-slim из Dockerfile.sandbox-browser. Контейнер запускает Chromium с включённым CDP и опциональным noVNC-наблюдателем (headful через Xvfb).

Замечания:

  • Headful (Xvfb) снижает вероятность блокировки ботами по сравнению с headless.
  • Headless можно использовать, задав agents.defaults.sandbox.browser.headless=true.
  • Полная десктопная среда (GNOME) не нужна; Xvfb предоставляет дисплей.
  • Контейнеры браузера по умолчанию используют выделенную Docker-сеть (openclaw-sandbox-browser) вместо глобального bridge.
  • Опциональный agents.defaults.sandbox.browser.cdpSourceRange ограничивает CDP-доступ к контейнеру по CIDR (например, 172.21.0.1/32).
  • Доступ noVNC-наблюдателя защищён паролем по умолчанию; OpenClaw предоставляет кратковременный URL с токеном наблюдателя, который отдаёт локальную bootstrap-страницу и хранит пароль во фрагменте URL (не в query).
  • Настройки запуска контейнера браузера по умолчанию консервативны для совместных/контейнерных рабочих нагрузок, включая:
    • --remote-debugging-address=127.0.0.1
    • --remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>
    • --user-data-dir=${HOME}/.chrome
    • --no-first-run
    • --no-default-browser-check
    • --disable-3d-apis
    • --disable-software-rasterizer
    • --disable-gpu
    • --disable-dev-shm-usage
    • --disable-background-networking
    • --disable-features=TranslateUI
    • --disable-breakpad
    • --disable-crash-reporter
    • --metrics-recording-only
    • --renderer-process-limit=2
    • --no-zygote
    • --disable-extensions
    • При включённом agents.defaults.sandbox.browser.noSandbox также добавляются --no-sandbox и --disable-setuid-sandbox.
    • Три флага hardening графики выше опциональны. Если рабочей нагрузке нужен WebGL/3D, задайте OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0.
    • Поведение расширений контролируется --disable-extensions и может быть отключено (расширения включаются) через OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0.
    • --renderer-process-limit=2 настраивается через OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT; 0 позволяет Chromium использовать лимит по умолчанию.

Настройки по умолчанию применяются в поставляемом образе. Если нужны другие флаги Chromium, используйте собственный образ браузера с собственной точкой входа.

Конфигурация использования:

{
  agents: {
    defaults: {
      sandbox: {
        browser: { enabled: true },
      },
    },
  },
}

Собственный образ браузера:

{
  agents: {
    defaults: {
      sandbox: { browser: { image: "my-openclaw-browser" } },
    },
  },
}

При включении агент получает:

  • URL управления sandbox-браузером (для инструмента browser)
  • URL noVNC (если включён и headless=false)

Помните: если используете allowlist для инструментов, добавьте browser (и уберите из deny), иначе инструмент останется заблокированным. Правила очистки (agents.defaults.sandbox.prune) распространяются и на контейнеры браузера.

Собственный образ sandbox

Соберите собственный образ и укажите его в конфигурации:

docker build -t my-openclaw-sbx -f Dockerfile.sandbox .
{
  agents: {
    defaults: {
      sandbox: { docker: { image: "my-openclaw-sbx" } },
    },
  },
}

Политика инструментов (allow/deny)

  • deny имеет приоритет над allow.
  • Если allow пуст: доступны все инструменты (кроме deny).
  • Если allow не пуст: доступны только инструменты из allow (за вычетом deny).

Стратегия очистки

Два параметра:

  • prune.idleHours: удалять контейнеры, не использовавшиеся X часов (0 = отключить)
  • prune.maxAgeDays: удалять контейнеры старше X дней (0 = отключить)

Примеры:

  • Сохранять активные сессии, но ограничить время жизни: idleHours: 24, maxAgeDays: 7
  • Никогда не очищать: idleHours: 0, maxAgeDays: 0

Безопасность

  • Жёсткая изоляция применяется только к инструментам (exec/read/write/edit/apply_patch).
  • Инструменты, работающие только на хосте (browser/camera/canvas), заблокированы по умолчанию.
  • Разрешение browser в sandbox нарушает изоляцию (браузер работает на хосте).

Решение проблем

  • Образ отсутствует: соберите через scripts/sandbox-setup.sh или задайте agents.defaults.sandbox.docker.image.
  • Контейнер не запущен: он автоматически создаётся при каждой сессии по запросу.
  • Ошибки прав в sandbox: задайте docker.user с UID:GID, соответствующим владельцу смонтированного workspace (или измените владельца папки workspace).
  • Пользовательские инструменты не найдены: OpenClaw выполняет команды через sh -lc (login shell), который загружает /etc/profile и может сбрасывать PATH. Задайте docker.env.PATH для добавления путей к инструментам (например, /custom/bin:/usr/local/share/npm-global/bin), или добавьте скрипт в /etc/profile.d/ в Dockerfile.
arrow_back
Назад
Installer
Далее
Podman
arrow_forward