Docker

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

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

• Так: вам потрібне ізольоване одноразове середовище Gateway або запуск OpenClaw на хості без локальних інсталяцій.
• Ні: ви запускаєте на власній машині й просто хочете найшвидший цикл розробки. Натомість використовуйте звичайний потік інсталяції.
• Примітка про пісочницю: стандартний бекенд пісочниці використовує Docker, коли пісочницю ввімкнено, але пісочниця вимкнена за замовчуванням і не вимагає запуску всього Gateway у Docker. Також доступні бекенди пісочниці SSH і OpenShell. Див. Пісочниця.

# Передумови

• Docker Desktop (або Docker Engine) + Docker Compose v2
• Щонайменше 2 ГБ RAM для складання образу (pnpm install може бути завершено через OOM на хостах з 1 ГБ із кодом виходу 137)
• Достатньо дискового простору для образів і журналів
• Якщо запускаєте на VPS/публічному хості, перегляньте Посилення безпеки для мережевого доступу, особливо політику брандмауера Docker DOCKER-USER.

# Контейнеризований Gateway

./scripts/docker/setup.sh

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh

docker compose run --rm openclaw-cli dashboard --no-open

# WhatsApp (QR)
docker compose run --rm openclaw-cli channels login

# Telegram
docker compose run --rm openclaw-cli channels add --channel telegram --token "<token>"

# Discord
docker 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-daemon
docker 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

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

Скрипт налаштування приймає ці необов’язкові змінні середовища:

Мейнтейнери можуть тестувати джерело bundled Plugin проти упакованого образу, монтувавши один каталог джерела Plugin поверх його упакованого шляху джерела, наприклад OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro. Цей змонтований каталог джерела перевизначає відповідний скомпільований пакет /app/dist/extensions/synology-chat для того самого ідентифікатора Plugin.

# Спостережуваність

Експорт OpenTelemetry є вихідним з контейнера Gateway до вашого колектора OTLP. Він не потребує опублікованого порту Docker. Якщо ви збираєте образ локально й хочете, щоб bundled експортер OpenTelemetry був доступний усередині образу, додайте його runtime-залежності:

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 у упакованих інсталяціях Docker перед увімкненням експорту. Власні образи, зібрані з джерел, усе ще можуть додавати локальне джерело Plugin за допомогою OPENCLAW_EXTENSIONS=diagnostics-otel. Щоб увімкнути експорт, дозвольте й увімкніть Plugin diagnostics-otel у конфігурації, потім установіть diagnostics.otel.enabled=true або використайте приклад конфігурації в Експорт OpenTelemetry. Заголовки автентифікації колектора налаштовуються через diagnostics.otel.headers, а не через змінні середовища Docker.

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

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

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

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

Кінцеві точки перевірок контейнера (автентифікація не потрібна):

curl -fsS http://127.0.0.1:18789/healthz   # liveness
curl -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-провайдерів, які працюють на хості:

Bundled Docker setup використовує ці 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.0
OLLAMA_HOST=0.0.0.0:11434 ollama serve

Якщо ви використовуєте власний Compose-файл або команду docker run, додайте таке саме зіставлення хоста самостійно, наприклад --add-host=host.docker.internal:host-gateway.

# Bonjour / mDNS

Мережа мосту Docker зазвичай не пересилає multicast Bonjour/mDNS (224.0.0.251:5353) надійно. Тому bundled Compose setup за замовчуванням установлює OPENCLAW_DISABLE_BONJOUR=1, щоб Gateway не потрапляв у цикл падіння або багаторазово не перезапускав оголошення, коли міст відкидає multicast-трафік.

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

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

# Сховище та сталість

Docker Compose bind-mount-ить OPENCLAW_CONFIG_DIR до /home/node/.openclaw і OPENCLAW_WORKSPACE_DIR до /home/node/.openclaw/workspace, тому ці шляхи зберігаються після заміни контейнера. Коли будь-яка зі змінних не задана, bundled docker-compose.yml повертається до ${HOME}/.openclaw (і ${HOME}/.openclaw/workspace для монтування workspace) або до /tmp/.openclaw, коли самого HOME також немає. Це не дає docker compose up видавати специфікацію тому з порожнім джерелом у мінімальних середовищах.

У цьому змонтованому каталозі конфігурації OpenClaw зберігає:

• openclaw.json для конфігурації поведінки
• agents/<agentId>/agent/auth-profiles.json для збереженої автентифікації OAuth/API-key провайдерів
• .env для runtime-секретів на основі env, таких як OPENCLAW_GATEWAY_TOKEN

Установлені завантажувані Plugin зберігають стан своїх пакетів у змонтованому домашньому каталозі OpenClaw, тому записи встановлення Plugin і корені пакетів зберігаються після заміни контейнера. Запуск Gateway не генерує дерева залежностей bundled Plugin.

Повні відомості про сталість у VM-розгортаннях див. у Docker VM Runtime - Що де зберігається.

Гарячі точки зростання диска: стежте за media/, файлами JSONL сесій, cron/runs/*.jsonl, коренями встановлених пакетів plugin і rolling file logs у /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.sh
echo '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=1
export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock
./scripts/docker/setup.sh

docker compose run -T --rm openclaw-cli gateway probe
docker compose run -T --rm openclaw-cli devices list --json

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

FROM node:24-bookworm
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"
RUN corepack enable
WORKDIR /app
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY scripts ./scripts
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build
ENV NODE_ENV=production
CMD ["node","dist/index.js"]

# Запуск на VPS?

Див. Hetzner (Docker VPS) і Docker VM Runtime, щоб отримати кроки розгортання на спільній VM, зокрема вбудовування бінарного файлу, сталість даних і оновлення.

# Sandbox агента

Коли agents.defaults.sandbox увімкнено з бекендом Docker, Gateway запускає виконання інструментів агента (оболонка, читання/запис файлів тощо) всередині ізольованих Docker контейнерів, тоді як сам Gateway залишається на хості. Це дає жорстку межу навколо недовірених або multi-tenant сесій агентів без контейнеризації всього Gateway.

Область sandbox може бути для кожного агента (типово), для кожної сесії або спільною. Кожна область отримує власний робочий простір, змонтований у /workspace. Ви також можете налаштувати політики дозволу/заборони інструментів, ізоляцію мережі, ліміти ресурсів і браузерні контейнери.

Повну конфігурацію, образи, примітки щодо безпеки й профілі multi-agent див. тут:

• Sandboxing -- повний довідник із sandbox
• OpenShell -- інтерактивний доступ оболонки до контейнерів sandbox
• Multi-Agent Sandbox and Tools -- перевизначення для кожного агента

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

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared
      },
    },
  },
}

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

scripts/sandbox-setup.sh

Для npm-встановлень без вихідного checkout див. Sandboxing § Images and setup щодо inline-команд docker build.

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

docker compose run --rm openclaw-cli dashboard --no-open
docker compose run --rm openclaw-cli devices list
docker 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 після встановлення