Skip to main content
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

1

Зберіть образ

З кореня репозиторію:
Ця команда локально збирає образ Gateway як openclaw:local. Щоб натомість використати попередньо зібраний образ:
Попередньо зібрані образи спочатку публікуються в GitHub Container Registry. GHCR — основний реєстр для автоматизації випусків, розгортань із закріпленими версіями та перевірок походження. Той самий випуск публікує дзеркало Docker Hub у 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 під час першого запуску.
2

Повторний запуск без доступу до мережі

На хостах без доступу до мережі спочатку перенесіть і завантажте образ:
--offline перевіряє, що OPENCLAW_IMAGE уже існує локально, вимикає неявне завантаження та збирання через Compose, а потім виконує звичайний процес: синхронізацію .env, виправлення дозволів, початкове налаштування, синхронізацію конфігурації Gateway і запуск Compose.Якщо OPENCLAW_SANDBOX=1, автономне налаштування також перевіряє налаштовані стандартні й окремі для кожного агента образи пісочниці в демоні за OPENCLAW_DOCKER_SOCKET, зокрема мітку контракту браузера на образах браузера на основі Docker. Якщо потрібний образ відсутній або застарілий, налаштування завершується без зміни конфігурації пісочниці, замість того щоб помилково повідомляти про успіх.
3

Завершіть початкове налаштування

Скрипт налаштування автоматично виконує початкове налаштування:
  • запитує API-ключі постачальника
  • генерує токен Gateway і записує його до .env
  • створює каталог секретного ключа профілю автентифікації
  • запускає Gateway через Docker Compose
Початкове налаштування та запис конфігурації перед запуском виконуються безпосередньо через openclaw-gateway--no-deps --entrypoint node), оскільки openclaw-cli використовує спільний із Gateway простір імен мережі та працює лише після створення контейнера Gateway.
4

Відкрийте інтерфейс керування

Відкрийте http://127.0.0.1:18789/ і вставте токен, записаний до .env, у Settings. Якщо контейнер переведено на автентифікацію за паролем, натомість використовуйте цей пароль.Знову потрібна URL-адреса?
5

Налаштуйте канали (необов’язково)

Документація: WhatsApp, Telegram, Discord

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

Контекст Docker виключає .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:
Після завершення роботи 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 або повторіть спробу з меншими явно заданими розмірами купи:

Образи, зібрані з вихідного коду, з вибраними 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 вихідного коду:
Ці образи призначені для автономних 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. Щоб включити комплектний експортер до локально зібраного образу:
Офіційні готові образи вже містять 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, а потім опитуйте:
Маршрут захищено автентифікацією Gateway; не відкривайте окремий загальнодоступний порт /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 для провайдерів, запущених на хості: Комплектне налаштування використовує ці URL-адреси як стандартні значення початкового налаштування LM Studio/Ollama, а docker-compose.yml зіставляє host.docker.internal із gateway хоста в Linux Docker Engine (Docker Desktop надає такий самий псевдонім у macOS/Windows). Служби хоста мають прослуховувати адресу, доступну для Docker:
Використовуєте власний файл Compose або 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 в обох службах.
Для спільної автоматизації у робочому середовищі або передбачуваної тарифікації Anthropic віддавайте перевагу шляху з ключем API Anthropic. Повторне використання Claude CLI залежить від установленої версії Claude Code, входу в обліковий запис, тарифікації та поведінки оновлень.

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:
Якщо ви встановлювали зі старішого шляху scripts/shell-helpers/clawdock-helpers.sh, повторно виконайте наведену вище команду, щоб локальний допоміжний засіб відстежував поточне розташування. Потім використовуйте clawdock-start, clawdock-stop, clawdock-dashboard тощо (виконайте clawdock-help, щоб переглянути повний список).
Власний шлях до сокета (наприклад, Docker без прав root):
Скрипт монтує docker.sock лише після успішної перевірки передумов пісочниці. Якщо налаштування пісочниці неможливо завершити, він скидає agents.defaults.sandbox.mode до off. Режим коду Codex вимкнено для запитів, під час яких активна пісочниця OpenClaw (див. Пісочниця § Серверна частина Docker); ніколи не монтуйте сокет Docker хоста в контейнери пісочниці агента.
Вимкніть виділення псевдотермінала Compose за допомогою -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.
У деяких конфігураціях Docker Desktop DNS-пошук із допоміжного контейнера спільної мережі openclaw-cli перестає працювати після вилучення NET_RAW, що проявляється як EAI_AGAIN під час команд із використанням npm, як-от openclaw plugins install. Для звичайної роботи залиште стандартний захищений файл Compose. Наведене нижче перевизначення відновлює стандартні можливості лише для контейнера openclaw-cli — використовуйте його для одноразової команди, якій потрібен доступ до реєстру, а не як стандартний спосіб запуску:
Якщо ви вже створили довготривалий контейнер openclaw-cli, створіть його заново з тим самим перевизначенням — docker compose exec/docker exec не можуть змінити можливості Linux у вже створеному контейнері.
Образ працює від імені 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.
Упорядкуйте Dockerfile так, щоб шари залежностей кешувалися й повторний запуск pnpm install не відбувався без змін у файлах блокування:
Стандартний образ насамперед орієнтований на безпеку та працює від імені непривілейованого користувача node. Для контейнера з ширшими можливостями:
  1. Зберігайте /home/node: export OPENCLAW_HOME_VOLUME="openclaw_home"
  2. Вбудовуйте системні залежності: export OPENCLAW_IMAGE_APT_PACKAGES="git curl jq"
  3. Вбудовуйте залежності Python: export OPENCLAW_IMAGE_PIP_PACKAGES="requests==2.32.5 humanize==4.14.0"
  4. Вбудовуйте Playwright Chromium: export OPENCLAW_INSTALL_BROWSER=1 або використовуйте офіційний тег образу -browser
  5. Або встановіть браузери Playwright у постійний том:
  6. Зберігайте завантаження браузера: використовуйте OPENCLAW_HOME_VOLUME або OPENCLAW_EXTRA_MOUNTS. OpenClaw автоматично виявляє керований Playwright Chromium з образу в Linux.
Якщо в майстрі вибрано OpenAI Codex OAuth, він відкриває URL-адресу в браузері. У Docker або середовищах без графічного інтерфейсу скопіюйте повну URL-адресу переспрямування, на яку ви потрапите, і вставте її назад у майстер, щоб завершити автентифікацію.
Образ середовища виконання використовує 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. Також можна налаштувати політики дозволу й заборони інструментів, ізоляцію мережі, обмеження ресурсів і контейнери браузера. Повна конфігурація, образи, примітки щодо безпеки та профілі для кількох агентів:

Швидке ввімкнення

Зберіть стандартний образ пісочниці (з вихідного робочого дерева):
Для встановлень через npm без вихідного робочого дерева див. вбудовані команди docker build у розділі Пісочниця § Образи та налаштування.

Усунення несправностей

Зберіть образ пісочниці за допомогою scripts/sandbox-setup.sh (вихідне робоче дерево) або вбудованої команди docker build із розділу Пісочниця § Образи та налаштування (встановлення через npm), або задайте власний образ у agents.defaults.sandbox.docker.image. Контейнери автоматично створюються для кожного сеансу за потреби.
Задайте в docker.user UID:GID, що відповідає власнику змонтованого робочого простору, або змініть власника папки робочого простору.
OpenClaw запускає команди через sh -lc (оболонку входу), яка завантажує /etc/profile і може скинути PATH. Задайте docker.env.PATH, щоб додати шляхи до власних інструментів на початок, або додайте скрипт у /etc/profile.d/ у Dockerfile.
Віртуальній машині потрібно щонайменше 2 GB оперативної пам’яті. Використайте потужніший клас машини та повторіть спробу.
Отримайте нове посилання на панель керування та схваліть пристрій браузера:
Докладніше: Панель керування, Пристрої.
Скиньте режим і прив’язку gateway:

Пов’язані матеріали