Docker

Docker є необов’язковим. Використовуйте його лише якщо вам потрібен контейнеризований gateway або потрібно перевірити Docker flow.

Чи підходить мені Docker?

• Так: вам потрібне ізольоване одноразове середовище gateway або запуск OpenClaw на хості без локальних інсталяцій.
• Ні: ви запускаєте на власній машині й хочете лише найшвидший dev loop. Натомість використовуйте звичайний процес інсталяції.
• Примітка щодо 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>"

Ручний flow

Якщо ви віддаєте перевагу запускати кожен крок самостійно замість використання setup script:

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

Змінні середовища

Setup script приймає такі необов’язкові змінні середовища:

Офіційний Docker image не постачається з Homebrew. Під час onboarding OpenClaw приховує інсталятори залежностей Skills, доступні лише через brew, коли він працює в Linux container без brew; ці залежності мають бути надані custom image або встановлені вручну. Для залежностей, доступних із пакетів Debian, використовуйте OPENCLAW_IMAGE_APT_PACKAGES під час збирання образу. Legacy-назва OPENCLAW_DOCKER_APT_PACKAGES досі приймається. Для Python-залежностей використовуйте OPENCLAW_IMAGE_PIP_PACKAGES. Це запускає python3 -m pip install --break-system-packages під час збирання образу, тому закріплюйте версії пакетів і використовуйте лише індекси пакетів, яким довіряєте. Source builds встановлюють OPENCLAW_DOCKER_BUILD_NODE_OPTIONS за замовчуванням на --max-old-space-size=8192 і залишають OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB невстановленою, щоб wrapper tsdown міг враховувати memory limits контейнера. Вони також встановлюють OPENCLAW_DOCKER_BUILD_SKIP_DTS=1 за замовчуванням, оскільки runtime images видаляють declaration files після build. Якщо 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 можуть тестувати вихідний код bundled 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 є outbound із контейнера Gateway до вашого OTLP collector. Він не потребує опублікованого Docker port. Якщо ви локально збираєте образ і хочете, щоб bundled 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 collector налаштовуються через diagnostics.otel.headers, а не через змінні середовища Docker.

Prometheus metrics використовують уже опублікований порт Gateway. Встановіть clawhub:@openclaw/diagnostics-prometheus, увімкніть plugin diagnostics-prometheus, а потім scrape:

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

Route захищено автентифікацією Gateway. Не відкривайте окремий публічний порт /metrics або unauthenticated reverse-proxy path. Див. Prometheus metrics.

Health checks

Container probe endpoints (автентифікація не потрібна):

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 із 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, пісочницю та налаштування пропуску онбордингу. Згенероване накладання монтує домашній том і для openclaw-gateway, і для openclaw-cli.

Запускайте решту команд зі згенерованим накладанням 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 bridge зазвичай ненадійно пересилає multicast Bonjour/mDNS (224.0.0.251:5353). Тому вбудоване налаштування Compose за замовчуванням встановлює OPENCLAW_DISABLE_BONJOUR=1, щоб Gateway не потрапляв у цикл аварійних перезапусків і не перезапускав рекламування повторно, коли bridge відкидає multicast-трафік.

Використовуйте опублікований URL Gateway, Tailscale або wide-area DNS-SD для хостів Docker. Встановлюйте OPENCLAW_DISABLE_BONJOUR=0 лише під час запуску з host networking, macvlan або іншою мережею, де відомо, що multicast mDNS працює.

Підводні камені та усунення несправностей див. у виявленні Bonjour.

Сховище та збереження

Docker Compose bind-монтує 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, щоб дізнатися про спільні кроки розгортання 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 — альтернатива Podman для Docker
• ClawDock — спільнотне налаштування Docker Compose
• Оновлення — підтримання OpenClaw в актуальному стані
• Конфігурація — конфігурація Gateway після встановлення