Docker

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

Стандартный бэкенд песочницы использует Docker, когда включён agents.defaults.sandbox, но по умолчанию песочница отключена, и для неё не требуется запускать сам Gateway в Docker. Также доступны бэкенды песочницы SSH и OpenShell; см. раздел Песочница.

Размещаете нескольких пользователей? Модель с одной изолированной средой на арендатора описана в разделе Мультитенантный хостинг.

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

• Docker Desktop (или Docker Engine) + Docker Compose v2
• Не менее 2 GB ОЗУ для сборки образа (pnpm install может быть завершён системой из-за нехватки памяти на хостах с 1 GB ОЗУ с кодом выхода 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>"

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

BUILD_GIT_COMMIT="$(git rev-parse HEAD)"BUILD_TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"docker build \  --build-arg "GIT_COMMIT=${BUILD_GIT_COMMIT}" \  --build-arg "OPENCLAW_BUILD_TIMESTAMP=${BUILD_TIMESTAMP}" \  -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 исключает .git. Передайте сведения об исходном коде в аргументах сборки, как показано выше, чтобы на экране «О программе» образа отображались зафиксированный коммит и одна временная метка сборки. scripts/docker/setup.sh определяет и передаёт оба значения автоматически.

Обновление образов контейнеров

Когда вы заменяете образ OpenClaw, но сохраняете те же подключённые состояние и конфигурацию, новый Gateway перед переходом в состояние готовности выполняет безопасные для запуска миграции обновления и согласование плагинов. Для обычных обновлений образа не должен требоваться отдельный запуск openclaw doctor --fix.

Если при запуске невозможно безопасно выполнить эти исправления, Gateway завершается вместо того, чтобы сообщать о работоспособности. При наличии политики перезапуска Docker, Podman или Kubernetes могут показывать, что контейнер Gateway перезапускается. Сохраните подключённый том состояния, а затем один раз запустите тот же образ с openclaw doctor --fix в качестве команды контейнера, используя те же подключения состояния и конфигурации, что и Gateway:

docker run --rm -v <openclaw-state>:/home/node/.openclaw <image> openclaw doctor --fixpodman run --rm -v <openclaw-state>:/home/node/.openclaw <image> openclaw doctor --fix

После завершения работы doctor перезапустите контейнер Gateway с его стандартной командой. В Kubernetes выполните ту же команду в одноразовом Job или отладочном поде с подключением к тому же PVC, а затем перезапустите Deployment или StatefulSet.

Переменные среды

Необязательные переменные, принимаемые scripts/docker/setup.sh (а для контейнера Gateway — непосредственно docker-compose.yml):

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

Если Docker сообщает ResourceExhausted, cannot allocate memory или прерывает работу во время tsdown, увеличьте ограничение памяти сборщика Docker или повторите попытку с меньшими явно заданными размерами кучи:

OPENCLAW_DOCKER_BUILD_NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB=4096

Образы, собранные из исходного кода с выбранными плагинами

OPENCLAW_EXTENSIONS выбирает идентификаторы манифестов плагинов из исходного дерева; также принимаются существующие имена каталогов исходного кода, если они отличаются. При сборке Docker выбранные элементы однократно сопоставляются с каталогами исходного кода, устанавливаются рабочие зависимости, а если выбранный плагин публикуется отдельно с openclaw.build.bundledDist: false, его среда выполнения компилируется в корневой комплектный dist. Эта упаковка, используемая только в Docker, не изменяет контракт артефактов npm или ClawHub плагина. Неизвестные, недопустимые или неоднозначные идентификаторы приводят к сбою сборки образа. Известные идентификаторы, предназначенные только для зависимостей или исходного кода, сохраняют существующую подготовку исходного кода и зависимостей без добавления скомпилированной записи в корневой dist. Выбранный плагин с унифицированными точками сборки должен успешно компилироваться; исходный код и выходные данные среды выполнения невыбранных внешних плагинов удаляются.

Например, эти команды собирают отдельные автономные многоархитектурные образы Gateway FakeCo для ClickClack, Slack и Microsoft Teams. ClawRouter уже входит в корневую среду выполнения OpenClaw, поэтому образ ClickClack выбирает только clickclack. Явно заданный пустой аргумент браузера позволяет не включать Chromium в образ по умолчанию:

SOURCE_SHA="$(git rev-parse HEAD)"BUILD_TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"REGISTRY="registry.example.com/fakeco" build_gateway_image() {  gateway="$1"  selected_plugin="$2"  docker buildx build \    --platform linux/amd64,linux/arm64 \    --build-arg "GIT_COMMIT=${SOURCE_SHA}" \    --build-arg "OPENCLAW_BUILD_TIMESTAMP=${BUILD_TIMESTAMP}" \    --build-arg "OPENCLAW_EXTENSIONS=${selected_plugin}" \    --build-arg OPENCLAW_INSTALL_BROWSER= \    --provenance=mode=max \    --sbom=true \    --tag "${REGISTRY}/openclaw-${gateway}:${SOURCE_SHA}" \    --push \    .} build_gateway_image clickclack clickclackbuild_gateway_image slack slackbuild_gateway_image teams msteams

Используйте --platform linux/arm64 --load или --platform linux/amd64 --load для одной нативной локальной сборки. Для многоплатформенных выходных данных и прикреплённых SBOM/данных о происхождении требуется реестр или другой выход Buildx, сохраняющий аттестации. После отправки проверьте манифест и развёртывайте неизменяемый дайджест, а не изменяемый тег SHA исходного кода:

docker buildx imagetools inspect \  "${REGISTRY}/openclaw-clickclack:${SOURCE_SHA}"# Развёртывание: registry.example.com/fakeco/openclaw-clickclack@sha256:<manifest-digest>

Эти образы предназначены для автономных шлюзов на основе OCI и обычных пользователей Docker. Шлюзы под управлением Crabhelm их не используют: этот путь доставки создаёт отдельный архив устройства x86_64, содержащий tar-архив npm OpenClaw, и фиксирует дайджесты Node, архива и манифеста. Собирайте это устройство отдельно из того же принятого исходного кода OpenClaw.

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

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

Экспорт OpenTelemetry выполняется из контейнера Gateway во внешний коллектор OTLP; для него не требуется публиковать порт Docker. Чтобы включить комплектный экспортёр в локально собранный образ:

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

Официальные готовые образы уже включают diagnostics-otel; устанавливайте clawhub:@openclaw/diagnostics-otel самостоятельно, только если вы его удалили. Чтобы включить экспорт, разрешите и включите плагин diagnostics-otel в конфигурации, затем задайте diagnostics.otel.enabled=true (полный пример см. в разделе Экспорт OpenTelemetry). Заголовки аутентификации коллектора передаются через diagnostics.otel.headers, а не через переменные среды Docker.

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

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

Маршрут защищён аутентификацией Gateway; не публикуйте отдельный общедоступный порт /metrics и не создавайте маршрут обратного прокси без аутентификации. См. раздел Метрики Prometheus.

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

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

curl -fsS http://127.0.0.1:18789/healthz   # работоспособностьcurl -fsS http://127.0.0.1:18789/readyz     # готовность

Встроенная в образ проверка HEALTHCHECK опрашивает /healthz; повторяющиеся сбои помечают контейнер как 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 могут только процессы внутри сетевого пространства имён контейнера.

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

Внутри контейнера 127.0.0.1 обозначает сам контейнер, а не хост. Для провайдеров, работающих на хосте, используйте host.docker.internal:

Комплектная настройка использует эти URL как значения по умолчанию при первоначальной настройке LM Studio/Ollama, а docker-compose.yml сопоставляет host.docker.internal со шлюзом хоста в Docker Engine для Linux (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

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

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

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

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

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

Если .env содержит значения, которые оболочка не может загрузить, сначала вручную повторно экспортируйте используемые значения (OPENCLAW_IMAGE, порты, режим привязки, пользовательские пути, OPENCLAW_EXTRA_MOUNTS, песочницу, пропуск первоначальной настройки). Созданный слой монтирует домашний том для openclaw-gateway и openclaw-cli; выполняйте остальные команды с этим слоем (и сначала с docker-compose.override.yml, если вы его используете):

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 "Передай привет из Claude CLI в Docker"

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

Bonjour / mDNS

Мостовая сеть Docker обычно не обеспечивает надёжную передачу многоадресного трафика Bonjour/mDNS (224.0.0.251:5353). Когда OPENCLAW_DISABLE_BONJOUR не задан, комплектный плагин Bonjour автоматически отключает объявления в LAN после обнаружения запуска в контейнере, чтобы не попадать в цикл аварийных перезапусков из-за повторных попыток отправить многоадресный трафик, отбрасываемый мостом. Задайте OPENCLAW_DISABLE_BONJOUR=1, чтобы принудительно отключить его независимо от результата обнаружения, или 0, чтобы принудительно включить его (только при использовании сети хоста, macvlan или другой сети, в которой многоадресный трафик mDNS гарантированно работает).

В остальных случаях для хостов Docker используйте опубликованный URL Gateway, Tailscale или глобальный DNS-SD. Особенности и сведения об устранении неполадок см. в разделе Обнаружение Bonjour.

Хранение и постоянство данных

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

Этот смонтированный каталог конфигурации содержит:

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

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

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

Подробные сведения о постоянстве данных виртуальной машины см. в разделе Среда выполнения виртуальной машины Docker — где сохраняются данные.

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

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

Для более коротких повседневных команд установите 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

Если вы устанавливали через старый путь scripts/shell-helpers/clawdock-helpers.sh, повторно выполните приведённую выше команду, чтобы локальный вспомогательный инструмент отслеживал текущее расположение. Затем используйте clawdock-start, clawdock-stop, clawdock-dashboard и т. д. (выполните clawdock-help, чтобы получить полный список).

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.

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

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

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

Полное описание конфигурации, образов, мер безопасности и профилей нескольких агентов:

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

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

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

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

scripts/sandbox-setup.sh

Для установки через npm без рабочей копии исходного кода см. встроенные команды 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 после установки