Docker

Docker — необов’язковий. Використовуйте його для ізольованого, тимчасового середовища Gateway або на хості без локально встановлених компонентів. Якщо розробка вже ведеться на власному комп’ютері, натомість використовуйте звичайний процес установлення.

Стандартний бекенд пісочниці використовує Docker, коли ввімкнено agents.defaults.sandbox, але пісочницю стандартно вимкнено, і для неї не потрібно, щоб сам Gateway працював у Docker. Також доступні бекенди пісочниці SSH і OpenShell; див. Пісочниця.

Розміщуєте кількох користувачів? Модель з однією коміркою на кожного орендаря описано в розділі Багатоорендне розміщення.

Передумови

• Docker Desktop (або Docker Engine) + Docker Compose v2
• Щонайменше 2 ГБ оперативної пам’яті для збирання образу (pnpm install може бути завершено через нестачу пам’яті на хостах із 1 ГБ із кодом виходу 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 перед переходом у стан готовності виконує безпечні для запуску міграції оновлення та узгодження plugins. Для звичайного оновлення образу не має бути потрібен окремий прохід 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 або налагоджувальному pod, змонтованому до того самого 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

Образи, зібрані з вихідного коду, з вибраними plugins

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>

Ці образи призначені для автономних gateway на основі OCI та звичайних користувачів Docker. Gateway під керуванням Crabhelm їх не використовують: цей шлях доставки створює окремий архів пристрою x86_64, що містить tarball 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 із gateway хоста в 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

Офіційний образ не містить попередньо встановленого 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 "Привіт із Docker Claude CLI"

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 гарантовано працює).

В інших випадках використовуйте опубліковану URL-адресу Gateway, Tailscale або глобальний DNS-SD для хостів Docker. Особливості та способи усунення несправностей див. у розділі Виявлення 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", // вимкнено | неосновний | усі        scope: "agent", // сеанс | агент | спільна      },    },  },}

Зберіть стандартний образ пісочниці (з вихідного робочого дерева):

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 після встановлення