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

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

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

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

Это руководство охватывает:

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

Детали песочниц: Песочницы

Требования

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

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

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

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

./docker-setup.sh

Этот скрипт:

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

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

  • OPENCLAW_DOCKER_APT_PACKAGES — установить дополнительные apt пакеты во время сборки
  • OPENCLAW_EXTRA_MOUNTS — добавить дополнительные bind mount с хоста
  • OPENCLAW_HOME_VOLUME — сохранить /home/node в именованном volume

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

  • Откройте http://127.0.0.1:18789/ в браузере.
  • Вставьте токен в Control UI (Settings → token).

Он записывает config/workspace на хосте:

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

Работаете на VPS? См. Hetzner (Docker VPS).

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

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

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

Если вы хотите смонтировать дополнительные каталоги хоста в контейнеры, установите OPENCLAW_EXTRA_MOUNTS перед запуском docker-setup.sh. Это принимает список bind mount Docker через запятую и применяет их к обоим 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.
  • Если вы редактируете OPENCLAW_EXTRA_MOUNTS, перезапустите docker-setup.sh для регенерации extra compose файла.
  • docker-compose.extra.yml генерируется. Не редактируйте его вручную.

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

Если вы хотите, чтобы /home/node сохранялся между пересозданиями контейнера, установите именованный volume через OPENCLAW_HOME_VOLUME. Это создаёт Docker volume и монтирует его в /home/node, сохраняя стандартные bind mount для config/workspace. Используйте именованный volume здесь (не bind путь); для bind mount используйте 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

Примечания:

  • Если вы меняете OPENCLAW_HOME_VOLUME, перезапустите docker-setup.sh для регенерации extra compose файла.
  • Именованный 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 для пересборки образа.

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

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

FROM node:22-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 (токен бота):

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

Discord (токен бота):

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

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

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

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

E2E smoke test (Docker)

scripts/e2e/onboard-docker.sh

QR import smoke test (Docker)

pnpm test:docker:qr

Примечания

  • Gateway bind по умолчанию lan для использования контейнера.
  • Контейнер шлюза — источник истины для сессий (~/.openclaw/agents/<agentId>/sessions/).

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

Глубокое погружение: Песочницы

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

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

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

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

Профили песочниц для каждого агента (мульти-агент)

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

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

См. Песочницы и инструменты мульти-агента для примеров, приоритетов и устранения неполадок.

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

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

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

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

  • docker.network по умолчанию "none" (нет egress).
  • 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 по умолчанию)
        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 отключает очистку idle
          maxAgeDays: 7  // 0 отключает очистку max-age
        }
      }
    }
  },
  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"]
      }
    }
  }
}

Настройки усиления находятся под agents.defaults.sandbox.docker: network, user, pidsLimit, memory, memorySwap, cpus, ulimits, seccompProfile, apparmorProfile, dns, extraHosts.

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

Сборка образа песочницы по умолчанию

scripts/sandbox-setup.sh

Это собирает openclaw-sandbox:bookworm-slim используя Dockerfile.sandbox.

Общий образ песочницы (опционально)

Если вы хотите образ песочницы с общими инструментами сборки (Node, Go, Rust и т.д.), соберите общий образ:

scripts/sandbox-common-setup.sh

Это собирает openclaw-sandbox-common:bookworm-slim. Чтобы использовать его:

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

Образ браузера песочницы

Чтобы запустить инструмент браузера внутри песочницы, соберите образ браузера:

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 предоставляет дисплей.

Используйте конфигурацию:

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

Пользовательский образ браузера:

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

Когда включено, агент получает:

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

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

Пользовательский образ песочницы

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

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 в песочнице нарушает изоляцию (браузер запускается на хосте).

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

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