agents.defaults.sandbox, але пісочницю стандартно вимкнено, і для неї не потрібно, щоб сам Gateway працював у Docker. Також доступні бекенди пісочниці SSH і OpenShell; див. Пісочниця.
Розміщуєте кількох користувачів? Модель з однією коміркою на кожного орендаря описано в розділі Багатоорендне розміщення.
Передумови
- Docker Desktop (або Docker Engine) + Docker Compose v2
- Щонайменше 2 ГБ оперативної пам’яті для збирання образу (
pnpm installможе бути завершено через нестачу пам’яті на хостах із 1 ГБ із кодом виходу 137) - Достатньо місця на диску для образів і журналів
- На VPS або загальнодоступному хості ознайомтеся з розділом Посилення безпеки в разі доступності через мережу, особливо з ланцюжком брандмауера Docker
DOCKER-USER
Контейнеризований Gateway
Зберіть образ
openclaw:local. Щоб натомість використати попередньо зібраний образ:openclaw/openclaw:ghcr.io/openclaw/openclaw або openclaw/openclaw та уникайте неофіційних дзеркал, які не дотримуються графіка випусків або політики зберігання OpenClaw. Офіційні теги: main, latest, <version> (наприклад, 2026.2.26), а також бета-теги на кшталт 2026.2.26-beta.1 (бета-версії ніколи не переміщують latest/main). Стандартний образ main/latest/<version> містить plugins codex і diagnostics-otel. Варіант -browser (наприклад, latest-browser) також постачається із вбудованим Chromium, що зручно для інструмента браузера в пісочниці без установлення Playwright під час першого запуску.Повторний запуск без доступу до мережі
--offline перевіряє, що OPENCLAW_IMAGE уже існує локально, вимикає неявне завантаження та збирання через Compose, а потім виконує звичайний процес: синхронізацію .env, виправлення дозволів, початкове налаштування, синхронізацію конфігурації Gateway і запуск Compose.Якщо OPENCLAW_SANDBOX=1, автономне налаштування також перевіряє налаштовані стандартні й окремі для кожного агента образи пісочниці в демоні за OPENCLAW_DOCKER_SOCKET, зокрема мітку контракту браузера на образах браузера на основі Docker. Якщо потрібний образ відсутній або застарілий, налаштування завершується без зміни конфігурації пісочниці, замість того щоб помилково повідомляти про успіх.Завершіть початкове налаштування
- запитує API-ключі постачальника
- генерує токен Gateway і записує його до
.env - створює каталог секретного ключа профілю автентифікації
- запускає Gateway через Docker Compose
openclaw-gateway (з --no-deps --entrypoint node), оскільки openclaw-cli використовує спільний із Gateway простір імен мережі та працює лише після створення контейнера Gateway.Відкрийте інтерфейс керування
http://127.0.0.1:18789/ і вставте токен, записаний до .env, у Settings. Якщо контейнер переведено на автентифікацію за паролем, натомість використовуйте цей пароль.Знову потрібна URL-адреса?Ручний процес
.git. Передайте ідентифікатор вихідного коду як аргументи збирання,
як показано вище, щоб на екрані «Про програму» образу відображалися коміт із поточної робочої копії та
одна часова позначка збирання. scripts/docker/setup.sh визначає та передає обидва значення
автоматично.
docker compose з кореня репозиторію. Якщо ввімкнено OPENCLAW_EXTRA_MOUNTS або OPENCLAW_HOME_VOLUME, скрипт налаштування записує docker-compose.extra.yml; додайте його після будь-якого docker-compose.override.yml, який підтримується самостійно, наприклад -f docker-compose.yml -f docker-compose.override.yml -f docker-compose.extra.yml.Оновлення образів контейнерів
Коли образ OpenClaw замінюється, але зберігається той самий змонтований стан і конфігурація, новий Gateway перед переходом у стан готовності виконує безпечні для запуску міграції оновлення та узгодження plugins. Для звичайного оновлення образу не має бути потрібен окремий прохідopenclaw doctor --fix.
Якщо під час запуску ці виправлення неможливо безпечно завершити, Gateway завершує роботу, а не
повідомляє про справний стан. За наявності політики перезапуску Docker, Podman або Kubernetes може показувати,
що контейнер Gateway перезапускається. Збережіть змонтований том стану, а потім один раз запустіть
той самий образ із openclaw doctor --fix як командою контейнера, використовуючи
ті самі монтування стану й конфігурації, що й Gateway:
Змінні середовища
Необов’язкові змінні, які приймаєscripts/docker/setup.sh (а для контейнера Gateway — безпосередньо docker-compose.yml):
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 або повторіть спробу з меншими явно заданими розмірами купи:
Образи, зібрані з вихідного коду, з вибраними plugins
OPENCLAW_EXTENSIONS вибирає ідентифікатори маніфестів плагінів із вихідного дерева;
також приймаються наявні назви каталогів із вихідним кодом, якщо вони відрізняються. Під час
збирання Docker вибрані значення один раз зіставляються з каталогами вихідного коду,
встановлюються робочі залежності, а коли вибраний плагін публікується окремо з
openclaw.build.bundledDist: false, його середовище виконання компілюється до кореневого комплектного
dist. Це пакування лише для Docker не змінює контракт артефактів плагіна в npm або ClawHub.
Невідомі, недійсні чи неоднозначні ідентифікатори спричиняють помилку збирання образу.
Відомі ідентифікатори лише залежностей або вихідного коду зберігають наявне проміжне
розміщення вихідного коду й залежностей без додавання скомпільованого запису до кореневого
dist. Вибраний плагін з уніфікованими записами збирання має успішно компілюватися;
вихідний код і результати середовища виконання невибраних зовнішніх плагінів видаляються.
Наприклад, ці команди збирають окремі багатоархітектурні автономні
образи gateway FakeCo для ClickClack, Slack і Microsoft Teams. ClawRouter уже
є частиною кореневого середовища виконання OpenClaw, тому образ ClickClack вибирає лише
clickclack. Явно порожній аргумент браузера дає змогу не включати
Chromium до стандартного образу:
--platform linux/arm64 --load або --platform linux/amd64 --load для
одного локального нативного збирання. Багатоплатформовий результат і прикріплені SBOM/дані
про походження потребують реєстру або іншого виведення Buildx, що зберігає атестації. Після
надсилання перевірте маніфест і розгорніть незмінний дайджест замість
змінного тегу SHA вихідного коду:
OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro. Це замінить відповідний скомпільований комплект /app/dist/extensions/synology-chat для того самого ідентифікатора плагіна.
Спостережуваність
Експорт OpenTelemetry здійснюється назовні з контейнера Gateway до вашого збирача OTLP; для нього не потрібно публікувати порт Docker. Щоб включити комплектний експортер до локально зібраного образу: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, а потім опитуйте:
/metrics або неавтентифікований шлях зворотного проксі. Див. Метрики Prometheus.
Перевірки працездатності
Кінцеві точки перевірки контейнера (автентифікація не потрібна):HEALTHCHECK опитує /healthz; повторні невдалі перевірки позначають контейнер як unhealthy, щоб оркестратори могли перезапустити або замінити його.
Автентифікований розширений знімок стану:
LAN і loopback
scripts/docker/setup.sh типово встановлює OPENCLAW_GATEWAY_BIND=lan, щоб http://127.0.0.1:18789 на хості працював із публікацією портів Docker.
lan(типово): браузер і CLI на хості можуть отримати доступ до опублікованого порту gateway.loopback: лише процеси всередині мережевого простору імен контейнера можуть безпосередньо отримати доступ до gateway.
gateway.bind (lan / loopback / custom / tailnet / auto), а не псевдоніми хоста на кшталт 0.0.0.0 або 127.0.0.1.Локальні провайдери хоста
Усередині контейнера127.0.0.1 означає сам контейнер, а не хост. Використовуйте host.docker.internal для провайдерів, запущених на хості:
docker-compose.yml зіставляє host.docker.internal із gateway хоста в Linux Docker Engine (Docker Desktop надає такий самий псевдонім у macOS/Windows). Служби хоста мають прослуховувати адресу, доступну для Docker:
docker run? Додайте таке саме зіставлення самостійно, наприклад --add-host=host.docker.internal:host-gateway.
Бекенд Claude CLI у Docker
Офіційний образ не містить попередньо встановленого Claude Code. Установіть його та ввійдіть у систему всередині користувачаnode контейнера, а потім забезпечте постійне зберігання домашнього каталогу контейнера, щоб оновлення образу не видаляли виконуваний файл або стан автентифікації.
Для нового встановлення ввімкніть постійний том /home/node перед запуском налаштування:
.env — сценарій налаштування завжди перезаписує .env на основі поточної оболонки та стандартних значень і не читає файл самостійно:
.env містить значення, які ваша оболонка не може підключити, спочатку вручну повторно експортуйте потрібні значення (OPENCLAW_IMAGE, порти, режим прив’язки, власні шляхи, OPENCLAW_EXTRA_MOUNTS, пісочницю, пропуск початкового налаштування). Згенерований файл перевизначень монтує домашній том для openclaw-gateway і openclaw-cli; виконуйте решту команд із цим файлом перевизначень (і спочатку з docker-compose.override.yml, якщо ви його використовуєте):
claude до /home/node/.local/bin/claude. Укажіть OpenClaw цей шлях:
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
OPENCLAW_CONFIG_DIR.
Установлені завантажувані плагіни зберігають стан пакетів у змонтованому домашньому каталозі OpenClaw, тому записи про встановлення та кореневі каталоги пакетів зберігаються після заміни контейнера; запуск gateway не створює повторно дерева залежностей комплектних плагінів.
Докладні відомості про постійність віртуальної машини див. у розділі Середовище виконання віртуальної машини Docker — що й де зберігається.
Основні джерела зростання використання диска: media/, окремі бази даних SQLite для агентів, застарілі JSONL-транскрипти сеансів, спільна база даних стану SQLite, кореневі каталоги пакетів установлених плагінів і циклічні файлові журнали в /tmp/openclaw/.
Допоміжні засоби оболонки (необов’язково)
Для коротших повсякденних команд установіть ClawDock:scripts/shell-helpers/clawdock-helpers.sh, повторно виконайте наведену вище команду, щоб локальний допоміжний засіб відстежував поточне розташування. Потім використовуйте clawdock-start, clawdock-stop, clawdock-dashboard тощо (виконайте clawdock-help, щоб переглянути повний список).
Увімкнення пісочниці агента для Docker gateway
Увімкнення пісочниці агента для Docker gateway
docker.sock лише після успішної перевірки передумов пісочниці. Якщо налаштування пісочниці неможливо завершити, він скидає agents.defaults.sandbox.mode до off. Режим коду Codex вимкнено для запитів, під час яких активна пісочниця OpenClaw (див. Пісочниця § Серверна частина Docker); ніколи не монтуйте сокет Docker хоста в контейнери пісочниці агента.Автоматизація / CI (неінтерактивний режим)
Автоматизація / CI (неінтерактивний режим)
-T:Примітка щодо безпеки спільної мережі
Примітка щодо безпеки спільної мережі
openclaw-cli використовує network_mode: "service:openclaw-gateway", щоб команди CLI могли звертатися до gateway через 127.0.0.1. Вважайте це спільною межею довіри. Конфігурація Compose вилучає NET_RAW/NET_ADMIN та вмикає no-new-privileges для openclaw-gateway і openclaw-cli.Помилки DNS Docker Desktop в openclaw-cli
Помилки DNS Docker Desktop в openclaw-cli
openclaw-cli перестає працювати після вилучення NET_RAW, що проявляється як EAI_AGAIN під час команд із використанням npm, як-от openclaw plugins install. Для звичайної роботи залиште стандартний захищений файл Compose. Наведене нижче перевизначення відновлює стандартні можливості лише для контейнера openclaw-cli — використовуйте його для одноразової команди, якій потрібен доступ до реєстру, а не як стандартний спосіб запуску:openclaw-cli, створіть його заново з тим самим перевизначенням — docker compose exec/docker exec не можуть змінити можливості Linux у вже створеному контейнері.Дозволи та EACCES
Дозволи та EACCES
node (uid 1000). Якщо виникають помилки дозволів для /home/node/.openclaw, переконайтеся, що прив’язані монтування хоста належать uid 1000:blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root), після чого з’являється plugin present but blocked — uid процесу та власник змонтованого каталогу плагіна не збігаються. Рекомендовано запускати процес зі стандартним uid 1000 і виправити власника прив’язаного монтування. Змінюйте власника /path/to/openclaw-config/npm на root:root лише тоді, коли свідомо плануєте довгостроково запускати OpenClaw від імені root.Швидше повторне збирання
Швидше повторне збирання
pnpm install не відбувався без змін у файлах блокування:Параметри контейнера для досвідчених користувачів
Параметри контейнера для досвідчених користувачів
node. Для контейнера з ширшими можливостями:- Зберігайте
/home/node:export OPENCLAW_HOME_VOLUME="openclaw_home" - Вбудовуйте системні залежності:
export OPENCLAW_IMAGE_APT_PACKAGES="git curl jq" - Вбудовуйте залежності Python:
export OPENCLAW_IMAGE_PIP_PACKAGES="requests==2.32.5 humanize==4.14.0" - Вбудовуйте Playwright Chromium:
export OPENCLAW_INSTALL_BROWSER=1або використовуйте офіційний тег образу-browser - Або встановіть браузери Playwright у постійний том:
- Зберігайте завантаження браузера: використовуйте
OPENCLAW_HOME_VOLUMEабоOPENCLAW_EXTRA_MOUNTS. OpenClaw автоматично виявляє керований Playwright Chromium з образу в Linux.
OpenAI Codex OAuth (Docker без графічного інтерфейсу)
OpenAI Codex OAuth (Docker без графічного інтерфейсу)
Метадані базового образу
Метадані базового образу
node:24-bookworm-slim і запускає tini як PID 1, щоб завершені дочірні процеси прибиралися, а сигнали правильно оброблялися в довготривалих контейнерах. Він публікує анотації базового образу OCI, зокрема org.opencontainers.image.base.name і org.opencontainers.image.source. Dependabot оновлює зафіксований дайджест базового образу Node; під час випускних збірок окремий шар оновлення дистрибутива не запускається. Див. Анотації образів OCI.Запуск на VPS?
Див. Hetzner (Docker VPS) і Середовище виконання Docker VM, щоб ознайомитися з етапами розгортання на спільній віртуальній машині, зокрема вбудовуванням бінарних файлів, постійним зберіганням та оновленнями.Пісочниця агента
Колиagents.defaults.sandbox увімкнено із серверною частиною Docker, gateway виконує інструменти агента (оболонку, читання й запис файлів тощо) в ізольованих контейнерах Docker, тоді як сам gateway залишається на хості — це створює надійну межу навколо ненадійних або багатокористувацьких сеансів агента без контейнеризації всього gateway.
Область пісочниці може бути окремою для кожного агента (стандартно), сеансу або спільною; кожна область отримує власний робочий простір, змонтований у /workspace. Також можна налаштувати політики дозволу й заборони інструментів, ізоляцію мережі, обмеження ресурсів і контейнери браузера.
Повна конфігурація, образи, примітки щодо безпеки та профілі для кількох агентів:
- Пісочниця — повний довідник із пісочниці
- OpenShell — інтерактивний доступ до оболонки контейнерів пісочниці
- Пісочниця та інструменти для кількох агентів — перевизначення для окремих агентів
Швидке ввімкнення
docker build у розділі Пісочниця § Образи та налаштування.
Усунення несправностей
Образ відсутній або контейнер пісочниці не запускається
Образ відсутній або контейнер пісочниці не запускається
scripts/sandbox-setup.sh (вихідне робоче дерево) або вбудованої команди docker build із розділу Пісочниця § Образи та налаштування (встановлення через npm), або задайте власний образ у agents.defaults.sandbox.docker.image. Контейнери автоматично створюються для кожного сеансу за потреби.Помилки дозволів у пісочниці
Помилки дозволів у пісочниці
docker.user UID:GID, що відповідає власнику змонтованого робочого простору, або змініть власника папки робочого простору.Власні інструменти не знайдено в пісочниці
Власні інструменти не знайдено в пісочниці
sh -lc (оболонку входу), яка завантажує /etc/profile і може скинути PATH. Задайте docker.env.PATH, щоб додати шляхи до власних інструментів на початок, або додайте скрипт у /etc/profile.d/ у Dockerfile.Процес завершено через нестачу пам’яті під час збирання образу (код виходу 137)
Процес завершено через нестачу пам’яті під час збирання образу (код виходу 137)
Немає авторизації або потрібне сполучення в інтерфейсі керування
Немає авторизації або потрібне сполучення в інтерфейсі керування
Ціль Gateway показує ws://172.x.x.x або Docker CLI повідомляє про помилки сполучення
Ціль Gateway показує ws://172.x.x.x або Docker CLI повідомляє про помилки сполучення
Пов’язані матеріали
- Огляд встановлення — усі способи встановлення
- Podman — альтернатива Docker на основі Podman
- ClawDock — конфігурація Docker Compose від спільноти
- Оновлення — підтримання OpenClaw в актуальному стані
- Конфігурація — конфігурація gateway після встановлення