Docker

Docker bersifat opsional. Gunakan hanya jika Anda menginginkan Gateway dalam container atau ingin memvalidasi alur Docker.

# Apakah Docker tepat untuk saya?

• Ya: Anda menginginkan lingkungan Gateway yang terisolasi dan sekali pakai, atau ingin menjalankan OpenClaw pada host tanpa instalasi lokal.
• Tidak: Anda menjalankan di mesin sendiri dan hanya menginginkan loop pengembangan tercepat. Gunakan alur instalasi normal sebagai gantinya.
• Catatan sandboxing: backend sandbox default menggunakan Docker saat sandboxing diaktifkan, tetapi sandboxing nonaktif secara default dan tidak mengharuskan seluruh Gateway berjalan di Docker. Backend sandbox SSH dan OpenShell juga tersedia. Lihat Sandboxing.

# Prasyarat

• Docker Desktop (atau Docker Engine) + Docker Compose v2
• RAM minimal 2 GB untuk build image (pnpm install dapat dihentikan karena OOM pada host 1 GB dengan exit 137)
• Ruang disk yang cukup untuk image dan log
• Jika berjalan pada VPS/host publik, tinjau Penguatan keamanan untuk paparan jaringan, terutama kebijakan firewall Docker DOCKER-USER.

# Gateway dalam container

./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>"

# Alur manual

Jika Anda lebih suka menjalankan setiap langkah sendiri alih-alih menggunakan skrip penyiapan:

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

# Variabel lingkungan

Skrip penyiapan menerima variabel lingkungan opsional berikut:

Maintainer dapat menguji sumber Plugin bawaan terhadap image terpaket dengan memasang satu direktori sumber Plugin di atas path sumber terpaketnya, misalnya OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro. Direktori sumber yang dipasang tersebut menimpa bundle /app/dist/extensions/synology-chat yang dikompilasi dan cocok untuk id Plugin yang sama.

# Observabilitas

Ekspor OpenTelemetry bersifat keluar dari container Gateway ke kolektor OTLP Anda. Ini tidak memerlukan port Docker yang dipublikasikan. Jika Anda membangun image secara lokal dan ingin eksportir OpenTelemetry bawaan tersedia di dalam image, sertakan dependensi runtime-nya:

export OPENCLAW_EXTENSIONS="diagnostics-otel"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4318"
export OTEL_SERVICE_NAME="openclaw-gateway"
./scripts/docker/setup.sh

Instal Plugin resmi @openclaw/diagnostics-otel dari ClawHub dalam instalasi Docker terpaket sebelum mengaktifkan ekspor. Image custom yang dibangun dari sumber tetap dapat menyertakan sumber Plugin lokal dengan OPENCLAW_EXTENSIONS=diagnostics-otel. Untuk mengaktifkan ekspor, izinkan dan aktifkan Plugin diagnostics-otel dalam konfigurasi, lalu setel diagnostics.otel.enabled=true atau gunakan contoh konfigurasi di Ekspor OpenTelemetry . Header autentikasi kolektor dikonfigurasi melalui diagnostics.otel.headers, bukan melalui variabel lingkungan Docker.

Metrik Prometheus menggunakan port Gateway yang sudah dipublikasikan. Instal clawhub:@openclaw/diagnostics-prometheus, aktifkan Plugin diagnostics-prometheus, lalu scrape:

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

Rute ini dilindungi oleh autentikasi Gateway. Jangan mengekspos port publik /metrics terpisah atau path reverse-proxy tanpa autentikasi. Lihat Metrik Prometheus.

# Health check

Endpoint probe container (tidak memerlukan autentikasi):

curl -fsS http://127.0.0.1:18789/healthz   # liveness
curl -fsS http://127.0.0.1:18789/readyz     # readiness

Image Docker menyertakan HEALTHCHECK bawaan yang melakukan ping ke /healthz. Jika pemeriksaan terus gagal, Docker menandai container sebagai unhealthy dan sistem orkestrasi dapat memulai ulang atau menggantinya.

Snapshot kesehatan mendalam yang terautentikasi:

docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"

# LAN vs loopback

scripts/docker/setup.sh menetapkan default OPENCLAW_GATEWAY_BIND=lan sehingga akses host ke http://127.0.0.1:18789 berfungsi dengan publikasi port Docker.

• lan (default): browser host dan CLI host dapat menjangkau port Gateway yang dipublikasikan.
• loopback: hanya proses di dalam namespace jaringan container yang dapat menjangkau Gateway secara langsung.

# Penyedia Lokal Host

Saat OpenClaw berjalan di Docker, 127.0.0.1 di dalam container adalah container itu sendiri, bukan mesin host Anda. Gunakan host.docker.internal untuk penyedia AI yang berjalan di host:

Penyiapan Docker bawaan menggunakan URL host tersebut sebagai default onboarding LM Studio dan Ollama, dan docker-compose.yml memetakan host.docker.internal ke Gateway host Docker untuk Docker Engine Linux. Docker Desktop sudah menyediakan hostname yang sama di macOS dan Windows.

Layanan host juga harus mendengarkan pada alamat yang dapat dijangkau dari Docker:

lms server start --port 1234 --bind 0.0.0.0
OLLAMA_HOST=0.0.0.0:11434 ollama serve

Jika Anda menggunakan file Compose sendiri atau perintah docker run, tambahkan pemetaan host yang sama sendiri, misalnya --add-host=host.docker.internal:host-gateway.

# Bonjour / mDNS

Jaringan bridge Docker biasanya tidak meneruskan multicast Bonjour/mDNS (224.0.0.251:5353) secara andal. Karena itu, penyiapan Compose bawaan menetapkan default OPENCLAW_DISABLE_BONJOUR=1 agar Gateway tidak crash-loop atau berulang kali memulai ulang iklan saat bridge menjatuhkan lalu lintas multicast.

Gunakan URL Gateway yang dipublikasikan, Tailscale, atau DNS-SD area luas untuk host Docker. Setel OPENCLAW_DISABLE_BONJOUR=0 hanya saat berjalan dengan jaringan host, macvlan, atau jaringan lain tempat multicast mDNS diketahui berfungsi.

Untuk hal-hal yang perlu diperhatikan dan pemecahan masalah, lihat Penemuan Bonjour.

# Penyimpanan dan persistensi

Docker Compose melakukan bind-mount OPENCLAW_CONFIG_DIR ke /home/node/.openclaw dan OPENCLAW_WORKSPACE_DIR ke /home/node/.openclaw/workspace, sehingga path tersebut tetap bertahan setelah container diganti. Saat salah satu variabel tidak disetel, docker-compose.yml bawaan fallback ke ${HOME}/.openclaw (dan ${HOME}/.openclaw/workspace untuk mount workspace), atau /tmp/.openclaw saat HOME sendiri juga tidak ada. Ini mencegah docker compose up menghasilkan spesifikasi volume dengan sumber kosong pada lingkungan minimal.

Direktori konfigurasi yang dipasang tersebut adalah tempat OpenClaw menyimpan:

• openclaw.json untuk konfigurasi perilaku
• agents/<agentId>/agent/auth-profiles.json untuk autentikasi OAuth/kunci API penyedia yang disimpan
• .env untuk secret runtime berbasis env seperti OPENCLAW_GATEWAY_TOKEN

Plugin unduhan yang diinstal menyimpan status paketnya di bawah home OpenClaw yang dipasang, sehingga catatan instalasi Plugin dan root paket tetap bertahan setelah container diganti. Startup Gateway tidak membuat pohon dependensi Plugin bawaan.

Untuk detail persistensi penuh pada deployment VM, lihat Docker VM Runtime - Apa yang bertahan di mana.

Hotspot pertumbuhan disk: pantau media/, file JSONL sesi, cron/runs/*.jsonl, root paket Plugin yang terpasang, dan log file bergulir di bawah /tmp/openclaw/.

# Pembantu shell (opsional)

Untuk mempermudah pengelolaan Docker harian, instal 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

Jika Anda memasang ClawDock dari path raw lama scripts/shell-helpers/clawdock-helpers.sh, jalankan ulang perintah instalasi di atas agar file pembantu lokal Anda mengikuti lokasi baru.

Lalu gunakan clawdock-start, clawdock-stop, clawdock-dashboard, dll. Jalankan clawdock-help untuk melihat semua perintah. Lihat ClawDock untuk panduan pembantu lengkap.

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"]

# Menjalankan di VPS?

Lihat Hetzner (Docker VPS) dan Runtime VM Docker untuk langkah deployment VM bersama termasuk memasukkan biner ke image, persistensi, dan pembaruan.

# Sandbox agen

Ketika agents.defaults.sandbox diaktifkan dengan backend Docker, Gateway menjalankan eksekusi alat agen (shell, baca/tulis file, dll.) di dalam kontainer Docker terisolasi sementara Gateway itu sendiri tetap berada di host. Ini memberi Anda dinding keras di sekitar sesi agen yang tidak tepercaya atau multi-tenant tanpa mengontainerkan seluruh Gateway.

Cakupan sandbox dapat per agen (default), per sesi, atau bersama. Setiap cakupan mendapat workspace sendiri yang dipasang di /workspace. Anda juga dapat mengonfigurasi kebijakan alat izinkan/tolak, isolasi jaringan, batas sumber daya, dan kontainer browser.

Untuk konfigurasi lengkap, image, catatan keamanan, dan profil multi-agen, lihat:

• Sandboxing -- referensi sandbox lengkap
• OpenShell -- akses shell interaktif ke kontainer sandbox
• Sandbox dan Alat Multi-Agen -- override per agen

# Aktifkan cepat

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

Build image sandbox default (dari checkout sumber):

scripts/sandbox-setup.sh

Untuk instalasi npm tanpa checkout sumber, lihat Sandboxing § Image dan penyiapan untuk perintah inline docker build.

# Pemecahan masalah

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

# Terkait

• Ringkasan Instalasi — semua metode instalasi
• Podman — alternatif Podman untuk Docker
• ClawDock — penyiapan komunitas Docker Compose
• Memperbarui — menjaga OpenClaw tetap terbaru
• Konfigurasi — konfigurasi Gateway setelah instalasi