Docker (opsional)

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, sekali pakai, atau ingin menjalankan OpenClaw pada host tanpa instalasi lokal.
Tidak: Anda menjalankan di mesin Anda sendiri dan hanya menginginkan loop pengembangan tercepat. Gunakan alur instalasi normal sebagai gantinya.
Catatan sandboxing: sandboxing agen juga menggunakan Docker, tetapi itu tidak mengharuskan seluruh gateway berjalan di Docker. Lihat Sandboxing.

Prasyarat

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

Gateway dalam container

Build image

Dari root repo, jalankan skrip penyiapan:

./scripts/docker/setup.sh

Ini membangun image gateway secara lokal. Untuk menggunakan image yang sudah dibangun sebelumnya:

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

Image yang sudah dibangun sebelumnya dipublikasikan di GitHub Container Registry. Tag umum: main, latest, <version> (misalnya 2026.2.26).

Selesaikan onboarding

Skrip penyiapan menjalankan onboarding secara otomatis. Skrip ini akan:

meminta API key provider
menghasilkan token gateway dan menuliskannya ke .env
memulai gateway melalui Docker Compose

Selama penyiapan, onboarding pra-start dan penulisan config saat setup dijalankan melalui openclaw-gateway secara langsung. openclaw-cli digunakan untuk perintah yang Anda jalankan setelah container gateway sudah ada.

Buka UI Control

Buka http://127.0.0.1:18789/ di browser Anda dan tempelkan shared secret yang telah dikonfigurasi ke Settings. Skrip penyiapan menulis token ke .env secara default; jika Anda mengubah config container ke autentikasi kata sandi, gunakan kata sandi tersebut.Perlu URL-nya lagi?

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

Konfigurasikan channel (opsional)

Gunakan container CLI untuk menambahkan channel pesan:

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

Docs: WhatsApp, Telegram, Discord

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

Jalankan docker compose dari root repo. Jika Anda mengaktifkan OPENCLAW_EXTRA_MOUNTS atau OPENCLAW_HOME_VOLUME, skrip penyiapan akan menulis docker-compose.extra.yml; sertakan dengan -f docker-compose.yml -f docker-compose.extra.yml.

Karena openclaw-cli berbagi namespace jaringan milik openclaw-gateway, ini adalah alat pasca-start. Sebelum docker compose up -d openclaw-gateway, jalankan onboarding dan penulisan config saat setup melalui openclaw-gateway dengan --no-deps --entrypoint node.

Variabel lingkungan

Skrip penyiapan menerima variabel lingkungan opsional berikut:

Variabel	Tujuan
`OPENCLAW_IMAGE`	Gunakan image remote alih-alih build secara lokal
`OPENCLAW_DOCKER_APT_PACKAGES`	Instal paket apt tambahan selama build (dipisahkan spasi)
`OPENCLAW_EXTENSIONS`	Pra-instal dependensi extension saat build (nama dipisahkan spasi)
`OPENCLAW_EXTRA_MOUNTS`	Bind mount host tambahan (dipisahkan koma `source:target[:opts]`)
`OPENCLAW_HOME_VOLUME`	Pertahankan `/home/node` dalam volume Docker bernama
`OPENCLAW_SANDBOX`	Opt in ke bootstrap sandbox (`1`, `true`, `yes`, `on`)
`OPENCLAW_DOCKER_SOCKET`	Override path socket Docker

Health check

Endpoint probe container (tidak memerlukan auth):

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 deep health yang diautentikasi:

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

LAN vs loopback

scripts/docker/setup.sh secara default menggunakan 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 mencapai port gateway yang dipublikasikan.
loopback: hanya proses di dalam namespace jaringan container yang dapat mencapai gateway secara langsung.

Gunakan nilai mode bind di gateway.bind (lan / loopback / custom / tailnet / auto), bukan alias host seperti 0.0.0.0 atau 127.0.0.1.

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 ada saat container diganti. Direktori config yang di-mount itulah tempat OpenClaw menyimpan:

openclaw.json untuk config perilaku
agents/<agentId>/agent/auth-profiles.json untuk auth OAuth/API key provider yang tersimpan
.env untuk secret runtime berbasis env seperti OPENCLAW_GATEWAY_TOKEN

Untuk detail persistensi lengkap pada deployment VM, lihat Runtime VM Docker - Apa yang dipertahankan di mana. Titik panas pertumbuhan disk: pantau media/, file JSONL sesi, cron/runs/*.jsonl, dan rolling file log di bawah /tmp/openclaw/.

Helper shell (opsional)

Untuk pengelolaan Docker sehari-hari yang lebih mudah, 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 menginstal ClawDock dari path raw lama scripts/shell-helpers/clawdock-helpers.sh, jalankan ulang perintah instalasi di atas agar file helper lokal Anda mengikuti lokasi baru. Lalu gunakan clawdock-start, clawdock-stop, clawdock-dashboard, dan seterusnya. Jalankan clawdock-help untuk semua perintah. Lihat ClawDock untuk panduan helper lengkap.

Aktifkan sandbox agen untuk gateway Docker

export OPENCLAW_SANDBOX=1
./scripts/docker/setup.sh

Path socket khusus (misalnya Docker rootless):

export OPENCLAW_SANDBOX=1
export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock
./scripts/docker/setup.sh

Skrip hanya me-mount docker.sock setelah prasyarat sandbox lolos. Jika penyiapan sandbox tidak dapat diselesaikan, skrip mereset agents.defaults.sandbox.mode ke off.

Otomatisasi / CI (non-interaktif)

Nonaktifkan alokasi pseudo-TTY Compose dengan -T:

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

Catatan keamanan jaringan bersama

openclaw-cli menggunakan network_mode: "service:openclaw-gateway" sehingga perintah CLI dapat menjangkau gateway melalui 127.0.0.1. Perlakukan ini sebagai batas kepercayaan bersama. Config compose menghapus NET_RAW/NET_ADMIN dan mengaktifkan no-new-privileges pada openclaw-cli.

Izin dan EACCES

Image berjalan sebagai node (uid 1000). Jika Anda melihat error izin pada /home/node/.openclaw, pastikan bind mount host Anda dimiliki oleh uid 1000:

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

Build ulang lebih cepat

Atur urutan Dockerfile Anda agar layer dependensi di-cache. Ini menghindari pengulangan pnpm install kecuali lockfile berubah:

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

Opsi container untuk power user

Image default berfokus pada keamanan dan berjalan sebagai node non-root. Untuk container yang lebih lengkap fiturnya:

Pertahankan /home/node: export OPENCLAW_HOME_VOLUME="openclaw_home"
Masukkan dependensi sistem: export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"

Instal browser Playwright:

docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium

Pertahankan unduhan browser: setel PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright dan gunakan OPENCLAW_HOME_VOLUME atau OPENCLAW_EXTRA_MOUNTS.

OAuth OpenAI Codex (Docker headless)

Jika Anda memilih OAuth OpenAI Codex di wizard, browser akan membuka URL. Pada Docker atau penyiapan headless, salin URL pengalihan lengkap tempat Anda mendarat lalu tempelkan kembali ke wizard untuk menyelesaikan auth.

Metadata image dasar

Image Docker utama menggunakan node:24-bookworm dan memublikasikan anotasi image dasar OCI termasuk org.opencontainers.image.base.name, org.opencontainers.image.source, dan lainnya. Lihat Anotasi image OCI.

Menjalankan di VPS?

Lihat Hetzner (Docker VPS) dan Runtime VM Docker untuk langkah deployment VM bersama termasuk binary baking, persistensi, dan pembaruan.

Sandbox Agen

Saat agents.defaults.sandbox diaktifkan, gateway menjalankan eksekusi alat agen (shell, baca/tulis file, dan sebagainya) di dalam container Docker yang 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 membuat seluruh gateway berada dalam container. Cakupan sandbox dapat per agen (default), per sesi, atau bersama. Setiap cakupan mendapat workspace sendiri yang di-mount di /workspace. Anda juga dapat mengonfigurasi kebijakan allow/deny alat, isolasi jaringan, batas resource, dan container browser. Untuk konfigurasi lengkap, image, catatan keamanan, dan profil multi-agen, lihat:

Sandboxing — referensi sandbox lengkap
OpenShell — akses shell interaktif ke container 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:

scripts/sandbox-setup.sh

Pemecahan masalah

Image hilang atau container sandbox tidak mau mulai

Build image sandbox dengan scripts/sandbox-setup.sh atau setel agents.defaults.sandbox.docker.image ke image khusus Anda. Container dibuat otomatis per sesi sesuai permintaan.

Error izin di sandbox

Setel docker.user ke UID:GID yang cocok dengan kepemilikan workspace yang Anda mount, atau jalankan chown pada folder workspace.

Alat khusus tidak ditemukan di sandbox

OpenClaw menjalankan perintah dengan sh -lc (login shell), yang memuat /etc/profile dan dapat mereset PATH. Setel docker.env.PATH untuk menambahkan path alat khusus Anda di depan, atau tambahkan skrip di bawah /etc/profile.d/ di Dockerfile Anda.

Dihentikan OOM selama build image (exit 137)

VM memerlukan setidaknya 2 GB RAM. Gunakan kelas mesin yang lebih besar dan coba lagi.

Unauthorized atau pairing diperlukan di UI Control

Ambil tautan dashboard yang baru dan setujui perangkat browser:

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>

Detail lebih lanjut: Dashboard, Devices.

Target gateway menampilkan ws://172.x.x.x atau error pairing dari Docker CLI

Reset mode dan bind gateway:

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

Ikhtisar Instalasi — semua metode instalasi
Podman — alternatif Podman untuk Docker
ClawDock — penyiapan komunitas Docker Compose
Updating — menjaga OpenClaw tetap mutakhir
Configuration — konfigurasi gateway setelah instalasi

Install overview

Containers

Hosting

Maintenance

Docker

Docker (opsional)

Apakah Docker tepat untuk saya?

Prasyarat

Gateway dalam container

Alur manual

Variabel lingkungan

Health check

LAN vs loopback

Penyimpanan dan persistensi

Helper shell (opsional)

Menjalankan di VPS?

Sandbox Agen

Aktifkan cepat

Pemecahan masalah

Terkait

Install overview

Containers

Hosting

Maintenance

​Docker (opsional)

​Apakah Docker tepat untuk saya?

​Prasyarat

​Gateway dalam container

​Alur manual

​Variabel lingkungan

​Health check

​LAN vs loopback

​Penyimpanan dan persistensi

​Helper shell (opsional)

​Menjalankan di VPS?

​Sandbox Agen

​Aktifkan cepat

​Pemecahan masalah

​Terkait

Docker (opsional)

Apakah Docker tepat untuk saya?

Prasyarat

Gateway dalam container

Alur manual

Variabel lingkungan

Health check

LAN vs loopback

Penyimpanan dan persistensi

Helper shell (opsional)

Menjalankan di VPS?

Sandbox Agen

Aktifkan cepat

Pemecahan masalah

Terkait