Docker

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

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

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

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

• Docker Desktop (или Docker Engine) + Docker Compose v2
• Минимум 2 ГБ RAM для сборки образа (pnpm install может быть завершен из-за OOM на хостах с 1 ГБ и кодом выхода 137)
• Достаточно места на диске для образов и логов
• Если запуск выполняется на VPS/публичном хосте, изучите усиление безопасности при сетевой доступности, особенно политику firewall 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 image не поставляется с Homebrew. Во время onboarding OpenClaw скрывает installers зависимостей Skills, доступные только через brew, когда он работает в Linux container без brew; эти зависимости должны предоставляться custom image или устанавливаться вручную. Для зависимостей, доступных из Debian packages, используйте OPENCLAW_IMAGE_APT_PACKAGES во время сборки образа. Устаревшее имя OPENCLAW_DOCKER_APT_PACKAGES все еще принимается. Для Python-зависимостей используйте OPENCLAW_IMAGE_PIP_PACKAGES. Это запускает python3 -m pip install --break-system-packages во время сборки образа, поэтому закрепляйте версии packages и используйте только package indexes, которым доверяете. Source builds по умолчанию задают OPENCLAW_DOCKER_BUILD_NODE_OPTIONS как --max-old-space-size=8192 и оставляют OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB не заданным, чтобы wrapper tsdown мог учитывать memory limits container. Они также по умолчанию задают OPENCLAW_DOCKER_BUILD_SKIP_DTS=1, потому что runtime images удаляют declaration files после сборки. Если Docker сообщает ResourceExhausted, cannot allocate memory или аварийно завершается во время tsdown, увеличьте memory limit Docker builder или повторите с меньшими явными heaps, например OPENCLAW_DOCKER_BUILD_NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB=4096.

Maintainers могут тестировать исходники встроенного Plugin с packaged image, смонтировав одну директорию исходников Plugin поверх его packaged source path, например OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro. Эта смонтированная директория исходников переопределяет соответствующий скомпилированный bundle /app/dist/extensions/synology-chat для того же plugin id.

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

Экспорт OpenTelemetry является исходящим из Gateway container в ваш OTLP collector. Он не требует опубликованного Docker port. Если вы собираете образ локально и хотите, чтобы встроенный OpenTelemetry exporter был доступен внутри образа, включите его runtime dependencies:

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 в packaged Docker installs перед включением экспорта. Custom source-built images все еще могут включать локальный исходник Plugin с OPENCLAW_EXTENSIONS=diagnostics-otel. Чтобы включить экспорт, разрешите и включите Plugin diagnostics-otel в конфигурации, затем задайте diagnostics.otel.enabled=true или используйте пример конфигурации в экспорте OpenTelemetry . Auth headers collector настраиваются через diagnostics.otel.headers, а не через переменные окружения Docker.

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

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

Route защищен authentication Gateway. Не открывайте отдельный публичный порт /metrics или unauthenticated reverse-proxy path. См. метрики Prometheus.

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

Endpoints container probe (аутентификация не требуется):

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, а docker-compose.yml сопоставляет host.docker.internal со шлюзом хоста 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 содержит значения, которые ваша оболочка не может загрузить через source, сначала вручную заново экспортируйте существующие значения, на которые вы полагаетесь, такие как OPENCLAW_IMAGE, порты, режим привязки, пользовательские пути, OPENCLAW_EXTRA_MOUNTS, песочница и настройки пропуска онбординга. Сгенерированный overlay монтирует домашний том и для openclaw-gateway, и для openclaw-cli.

Запускайте остальные команды со сгенерированным Compose overlay, чтобы оба сервиса монтировали постоянный домашний каталог. Если ваша настройка также использует 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-трафик.

Используйте опубликованный URL Gateway, Tailscale или wide-area DNS-SD для хостов Docker. Задавайте 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-секретов на основе env, таких как OPENCLAW_GATEWAY_TOKEN

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

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

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

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

Помощники оболочки (необязательно)

Для более простого повседневного управления 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 Runtime для общих шагов развертывания 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 исходного кода см. Песочница § Образы и настройка, где приведены встроенные команды 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 — альтернатива Podman для Docker
• ClawDock — настройка Docker Compose от сообщества
• Обновление — поддержание OpenClaw в актуальном состоянии
• Конфигурация — конфигурация Gateway после установки