Containers

Docker

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

Apakah Docker tepat untuk saya?

Ya: Anda menginginkan lingkungan Gateway yang terisolasi dan sekali pakai, atau ingin menjalankan OpenClaw di 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 ketika 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 di VPS/host publik, tinjau Penguatan keamanan untuk paparan jaringan, terutama kebijakan firewall Docker DOCKER-USER.

Gateway dalam kontainer

Build image

Dari root repo, jalankan skrip penyiapan:

bash

./scripts/docker/setup.sh

Ini mem-build image Gateway secara lokal. Untuk menggunakan image pra-build sebagai gantinya:

bash

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

Image pra-build pertama kali diterbitkan ke GitHub Container Registry. GHCR adalah registry utama untuk otomasi rilis, deployment yang dipin, dan pemeriksaan provenance. Workflow rilis yang sama juga menerbitkan mirror Docker Hub resmi di openclaw/openclaw untuk host yang lebih memilih Docker Hub:

bash

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

Gunakan ghcr.io/openclaw/openclaw atau openclaw/openclaw. Hindari mirror Docker Hub komunitas karena OpenClaw tidak mengontrol waktu rilis, rebuild, atau kebijakan retensinya. Tag resmi umum: main, latest, <version> (mis. 2026.2.26), dan versi beta seperti 2026.2.26-beta.1. Tag beta tidak memindahkan latest atau main.

Jalankan ulang airgapped

Pada host offline, transfer dan muat image terlebih dahulu:

bash

docker load -i openclaw-image.tarexport OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"./scripts/docker/setup.sh --offline

--offline memverifikasi bahwa OPENCLAW_IMAGE sudah ada secara lokal, menonaktifkan pull dan build Compose implisit, lalu menjalankan alur penyiapan normal seperti sinkronisasi .env, perbaikan izin, onboarding, sinkronisasi konfigurasi Gateway, dan startup Compose.

Jika OPENCLAW_SANDBOX=1, penyiapan offline juga memeriksa image sandbox default yang dikonfigurasi dan image sandbox per-agent aktif pada daemon di balik OPENCLAW_DOCKER_SOCKET. Image browser berbasis Docker juga harus membawa label kontrak browser OpenClaw saat ini. Ketika image yang diperlukan hilang atau tidak kompatibel, penyiapan keluar tanpa mengubah konfigurasi sandbox alih-alih melaporkan sukses dengan sandbox yang tidak dapat digunakan.

Selesaikan onboarding

Skrip penyiapan menjalankan onboarding secara otomatis. Skrip akan:

meminta kunci API provider
membuat token Gateway dan menulisnya ke .env
membuat direktori kunci rahasia auth-profile
memulai Gateway melalui Docker Compose

Selama penyiapan, onboarding pra-start dan penulisan konfigurasi berjalan langsung melalui openclaw-gateway. openclaw-cli digunakan untuk perintah yang Anda jalankan setelah kontainer Gateway sudah ada.

Buka Control UI

Buka http://127.0.0.1:18789/ di browser Anda dan tempel rahasia bersama yang dikonfigurasi ke Settings. Skrip penyiapan menulis token ke .env secara default; jika Anda mengalihkan konfigurasi kontainer ke autentikasi password, gunakan password tersebut sebagai gantinya.

Perlu URL-nya lagi?

bash

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

Konfigurasikan channel (opsional)

Gunakan kontainer CLI untuk menambahkan channel pesan:

bash

# WhatsApp (QR)docker compose run --rm openclaw-cli channels login # Telegramdocker compose run --rm openclaw-cli channels add --channel telegram --token "<token>" # Discorddocker compose run --rm openclaw-cli channels add --channel discord --token "<token>"

Dokumentasi: WhatsApp, Telegram, Discord

Alur manual

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

bash

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-daemondocker 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:

Variabel	Tujuan
`OPENCLAW_IMAGE`	Menggunakan image jarak jauh alih-alih mem-build secara lokal
`OPENCLAW_IMAGE_APT_PACKAGES`	Menginstal paket apt tambahan selama build (dipisahkan spasi)
`OPENCLAW_IMAGE_PIP_PACKAGES`	Menginstal paket Python tambahan selama build (dipisahkan spasi)
`OPENCLAW_EXTENSIONS`	Menginstal dependensi Plugin saat build (nama dipisahkan spasi)
`OPENCLAW_DOCKER_BUILD_NODE_OPTIONS`	Menimpa opsi Node build sumber lokal
`OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB`	Menimpa heap tsdown build sumber lokal dalam MB
`OPENCLAW_DOCKER_BUILD_SKIP_DTS`	Melewati output deklarasi selama build image lokal khusus runtime
`OPENCLAW_EXTRA_MOUNTS`	Bind mount host tambahan (`source:target[:opts]` dipisahkan koma)
`OPENCLAW_HOME_VOLUME`	Mempertahankan `/home/node` dalam volume Docker bernama
`OPENCLAW_SANDBOX`	Ikut serta dalam bootstrap sandbox (`1`, `true`, `yes`, `on`)
`OPENCLAW_SKIP_ONBOARDING`	Melewati langkah onboarding interaktif (`1`, `true`, `yes`, `on`)
`OPENCLAW_DOCKER_SOCKET`	Menimpa jalur socket Docker
`OPENCLAW_DISABLE_BONJOUR`	Menonaktifkan iklan Bonjour/mDNS (default ke `1` untuk Docker)
`OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS`	Menonaktifkan overlay bind-mount sumber Plugin bawaan
`OTEL_EXPORTER_OTLP_ENDPOINT`	Endpoint kolektor OTLP/HTTP bersama untuk ekspor OpenTelemetry
`OTEL_EXPORTER_OTLP_*_ENDPOINT`	Endpoint OTLP khusus sinyal untuk trace, metrik, atau log
`OTEL_EXPORTER_OTLP_PROTOCOL`	Override protokol OTLP. Saat ini hanya `http/protobuf` yang didukung
`OTEL_SERVICE_NAME`	Nama layanan yang digunakan untuk resource OpenTelemetry
`OTEL_SEMCONV_STABILITY_OPT_IN`	Ikut serta dalam atribut semantik GenAI eksperimental terbaru
`OPENCLAW_OTEL_PRELOADED`	Melewati startup SDK OpenTelemetry kedua ketika satu sudah dipreload

Image Docker resmi tidak menyertakan Homebrew. Selama onboarding, OpenClaw menyembunyikan installer dependensi skill khusus brew ketika berjalan dalam kontainer Linux tanpa brew; dependensi tersebut harus disediakan oleh image kustom atau diinstal secara manual. Untuk dependensi yang tersedia dari paket Debian, gunakan OPENCLAW_IMAGE_APT_PACKAGES selama build image. Nama lama OPENCLAW_DOCKER_APT_PACKAGES masih diterima. Untuk dependensi Python, gunakan OPENCLAW_IMAGE_PIP_PACKAGES. Ini menjalankan python3 -m pip install --break-system-packages selama build image, jadi pin versi paket dan gunakan hanya indeks paket yang Anda percaya. Build sumber menetapkan default OPENCLAW_DOCKER_BUILD_NODE_OPTIONS ke --max-old-space-size=8192 dan membiarkan OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB tidak disetel agar wrapper tsdown dapat menghormati batas memori kontainer. Build tersebut juga menetapkan default OPENCLAW_DOCKER_BUILD_SKIP_DTS=1 karena image runtime memangkas file deklarasi setelah build. Jika Docker melaporkan ResourceExhausted, cannot allocate memory, atau berhenti selama tsdown, tingkatkan batas memori builder Docker atau coba ulang dengan heap eksplisit yang lebih kecil, misalnya OPENCLAW_DOCKER_BUILD_NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB=4096.

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

Observability

Ekspor OpenTelemetry bersifat outbound dari kontainer Gateway ke kolektor OTLP Anda. Ini tidak memerlukan port Docker yang dipublikasikan. Jika Anda mem-build image secara lokal dan ingin exporter OpenTelemetry bawaan tersedia di dalam image, sertakan dependensi runtime-nya:

bash

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 kustom yang dibuild dari sumber masih 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 auth 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:

text

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

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

Health check

Endpoint probe kontainer (tidak perlu auth):

bash

curl -fsS http://127.0.0.1:18789/healthz   # livenesscurl -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 kontainer sebagai unhealthy dan sistem orkestrasi dapat memulai ulang atau menggantinya.

Snapshot kesehatan mendalam terautentikasi:

bash

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 penerbitan port Docker.

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

Penyedia Lokal Host

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

Penyedia	URL default host	URL penyiapan Docker
LM Studio	`http://127.0.0.1:1234`	`http://host.docker.internal:1234`
Ollama	`http://127.0.0.1:11434`	`http://host.docker.internal:11434`

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 nama host yang sama di macOS dan Windows.

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

bash

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

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

Backend Claude CLI di Docker

Image Docker resmi OpenClaw tidak memasang Claude Code sebelumnya. Pasang dan masuk ke Claude Code di dalam pengguna kontainer yang menjalankan OpenClaw, lalu persistensikan home kontainer tersebut agar peningkatan image tidak menghapus biner atau status auth Claude.

Untuk instalasi Docker baru, aktifkan volume /home/node yang persisten sebelum menjalankan penyiapan:

bash

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

Untuk instalasi Docker yang sudah ada, hentikan stack terlebih dahulu dan muat ulang nilai Docker .env saat ini sebelum menjalankan ulang penyiapan. Skrip penyiapan tidak membaca .env sendiri; skrip tersebut menulis ulang .env dari shell saat ini dan default. Untuk .env yang dihasilkan, jalankan:

bash

set -a. ./.envset +aexport OPENCLAW_HOME_VOLUME="${OPENCLAW_HOME_VOLUME:-openclaw_home}"./scripts/docker/setup.sh

Jika .env Anda berisi nilai yang tidak dapat di-source oleh shell Anda, ekspor ulang secara manual nilai yang sudah ada dan Anda andalkan terlebih dahulu, seperti OPENCLAW_IMAGE, port, mode bind, path khusus, OPENCLAW_EXTRA_MOUNTS, sandbox, dan pengaturan lewati-onboarding. Overlay yang dihasilkan memasang volume home untuk openclaw-gateway dan openclaw-cli.

Jalankan perintah berikutnya dengan overlay Compose yang dihasilkan agar kedua layanan memasang home yang dipersistensikan. Jika penyiapan Anda juga menggunakan docker-compose.override.yml, sertakan sebelum docker-compose.extra.yml.

Pasang Claude Code di home yang dipersistensikan tersebut:

bash

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint sh openclaw-cli -lc \  'curl -fsSL https://claude.ai/install.sh | bash'

Installer native menulis biner claude di bawah /home/node/.local/bin/claude. Beri tahu OpenClaw untuk menggunakan path kontainer tersebut:

bash

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli config set \  agents.defaults.cliBackends.claude-cli.command \  /home/node/.local/bin/claude

Masuk dan verifikasi dari dalam home kontainer persisten yang sama:

bash

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint /home/node/.local/bin/claude openclaw-cli auth logindocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint /home/node/.local/bin/claude openclaw-cli auth status --textdocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli models auth login \  --provider anthropic --method cli --set-defaultdocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli models list --provider anthropic

Setelah itu, Anda dapat menggunakan backend claude-cli bawaan:

bash

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli agent \  --agent main \  --model claude-cli/claude-sonnet-4-6 \  --message "Say hello from Docker Claude CLI"

OPENCLAW_HOME_VOLUME mempertahankan instalasi Claude Code native di bawah /home/node/.local/bin dan /home/node/.local/share/claude, ditambah pengaturan Claude Code dan status auth di bawah /home/node/.claude dan /home/node/.claude.json. Mempertahankan hanya /home/node/.openclaw tidak cukup untuk penggunaan ulang Claude CLI. Jika Anda menggunakan OPENCLAW_EXTRA_MOUNTS alih-alih volume home, pasang semua path Claude tersebut ke kedua layanan Docker.

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 mengalami crash-loop atau berulang kali memulai ulang iklan saat bridge menjatuhkan lalu lintas multicast.

Gunakan URL Gateway yang diterbitkan, Tailscale, atau DNS-SD area luas untuk host Docker. Tetapkan 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, OPENCLAW_WORKSPACE_DIR ke /home/node/.openclaw/workspace, dan OPENCLAW_AUTH_PROFILE_SECRET_DIR ke /home/node/.config/openclaw, sehingga path tersebut tetap ada setelah kontainer diganti. Saat variabel apa pun tidak disetel, docker-compose.yml bawaan melakukan fallback di bawah ${HOME}, atau /tmp saat HOME sendiri juga tidak ada. Ini mencegah docker compose up memunculkan spesifikasi volume sumber kosong di lingkungan bare.

Direktori konfigurasi yang dipasang tersebut adalah tempat OpenClaw menyimpan:

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

Direktori kunci rahasia profil auth menyimpan kunci enkripsi lokal yang digunakan untuk material token profil auth berbasis OAuth. Simpan bersama status host Docker Anda, tetapi pisahkan dari OPENCLAW_CONFIG_DIR.

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

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

Hotspot pertumbuhan disk: pantau media/, file JSONL sesi, database status SQLite bersama, root paket Plugin yang dipasang, dan log file bergulir di bawah /tmp/openclaw/.

Helper shell (opsional)

Untuk pengelolaan Docker sehari-hari yang lebih mudah, pasang ClawDock:

bash

mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/clawdock/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.shecho '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 helper lokal Anda mengikuti lokasi baru.

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

Aktifkan sandbox agent untuk Gateway Docker

bash

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

Path soket khusus (mis. Docker rootless):

bash

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

Skrip memasang docker.sock hanya setelah prasyarat sandbox lolos. Jika penyiapan sandbox tidak dapat selesai, skrip mereset agents.defaults.sandbox.mode ke off. Giliran mode kode Codex tetap dibatasi ke workspace-write Codex saat sandbox OpenClaw aktif; jangan pasang soket Docker host ke dalam kontainer sandbox agent.

Otomatisasi / CI (noninteraktif)

Nonaktifkan alokasi pseudo-TTY Compose dengan -T:

bash

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

Catatan keamanan jaringan bersama

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

Kegagalan DNS Docker Desktop di openclaw-cli

Beberapa penyiapan Docker Desktop gagal melakukan lookup DNS dari sidecar jaringan bersama openclaw-cli setelah NET_RAW dihapus, yang muncul sebagai EAI_AGAIN selama perintah berbasis npm seperti openclaw plugins install. Pertahankan file compose default yang diperkeras untuk operasi Gateway normal. Override lokal di bawah ini melonggarkan postur keamanan kontainer CLI dengan memulihkan kapabilitas default Docker, jadi gunakan hanya untuk perintah CLI sekali jalan yang membutuhkan akses registry paket, bukan sebagai pemanggilan Compose default Anda:

bash

printf '%s\n' \  'services:' \  '  openclaw-cli:' \  '    cap_drop: !reset []' \  > docker-compose.cli-no-dropped-caps.local.yml docker compose -f docker-compose.yml -f docker-compose.cli-no-dropped-caps.local.yml run --rm openclaw-cli plugins install <package>

Jika Anda sudah membuat kontainer openclaw-cli yang berjalan lama, buat ulang dengan override yang sama. docker compose exec dan docker exec tidak dapat mengubah kapabilitas Linux pada kontainer yang sudah dibuat.

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:

bash

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

Ketidakcocokan yang sama dapat muncul sebagai peringatan Plugin seperti blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) diikuti oleh plugin present but blocked. Itu berarti uid proses dan pemilik direktori Plugin yang dipasang tidak sesuai. Pilih menjalankan kontainer sebagai uid default 1000 dan memperbaiki kepemilikan bind mount. Hanya chown /path/to/openclaw-config/npm ke root:root jika Anda sengaja menjalankan OpenClaw sebagai root dalam jangka panjang.

Rebuild lebih cepat

Urutkan Dockerfile Anda agar layer dependensi di-cache. Ini menghindari menjalankan ulang pnpm install kecuali lockfile berubah:

dockerfile

FROM node:24-bookwormRUN curl -fsSL https://bun.sh/install | bashENV PATH="/root/.bun/bin:${PATH}"RUN corepack enableWORKDIR /appCOPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./COPY ui/package.json ./ui/package.jsonCOPY scripts ./scriptsRUN pnpm install --frozen-lockfileCOPY . .RUN pnpm buildRUN pnpm ui:installRUN pnpm ui:buildENV NODE_ENV=productionCMD ["node","dist/index.js"]

Opsi kontainer pengguna mahir

Image default mengutamakan keamanan dan berjalan sebagai node non-root. Untuk kontainer yang lebih lengkap fiturnya:

Pertahankan /home/node: export OPENCLAW_HOME_VOLUME="openclaw_home"
Tanam dependensi sistem: export OPENCLAW_IMAGE_APT_PACKAGES="git curl jq"
Tanam dependensi Python: export OPENCLAW_IMAGE_PIP_PACKAGES="requests==2.32.5 humanize==4.14.0"
Tanam Playwright Chromium: export OPENCLAW_INSTALL_BROWSER=1

Atau instal browser Playwright ke volume yang dipertahankan:

bash

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

Pertahankan unduhan browser: gunakan OPENCLAW_HOME_VOLUME atau OPENCLAW_EXTRA_MOUNTS. OpenClaw mendeteksi otomatis Chromium yang dikelola Playwright milik image Docker di Linux.

OpenAI Codex OAuth (Docker headless)

Jika Anda memilih OpenAI Codex OAuth di wizard, itu akan membuka URL browser. Dalam penyiapan Docker atau headless, salin URL pengalihan lengkap tempat Anda berakhir dan tempelkan kembali ke wizard untuk menyelesaikan autentikasi.

Metadata image dasar

Image runtime Docker utama menggunakan node:24-bookworm-slim dan menyertakan tini sebagai proses init entrypoint (PID 1) untuk memastikan proses zombi dipungut dan sinyal ditangani dengan benar dalam kontainer yang berjalan lama. Ini menerbitkan anotasi image dasar OCI termasuk org.opencontainers.image.base.name, org.opencontainers.image.source, dan lainnya. Digest dasar Node disegarkan melalui PR image dasar Docker Dependabot; build rilis tidak menjalankan lapisan upgrade distro. Lihat anotasi image OCI.

Menjalankan di VPS?

Lihat Hetzner (Docker VPS) dan Runtime VM Docker untuk langkah penerapan VM bersama termasuk penanaman biner, persistensi, dan pembaruan.

Sandbox agen

Saat 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 tidak tepercaya atau multi-tenant tanpa mengontainerkan seluruh Gateway.

Cakupan sandbox dapat berupa 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 -- penggantian per-agen

Aktifkan cepat

json5

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

Build image sandbox default (dari checkout sumber):

bash

scripts/sandbox-setup.sh

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

Pemecahan masalah

Image hilang atau kontainer sandbox tidak mulai

Build image sandbox dengan scripts/sandbox-setup.sh (checkout sumber) atau perintah docker build inline dari Sandboxing § Image dan penyiapan (instalasi npm), atau atur agents.defaults.sandbox.docker.image ke image kustom Anda. Kontainer dibuat otomatis per sesi sesuai permintaan.

Kesalahan izin di sandbox

Atur docker.user ke UID:GID yang cocok dengan kepemilikan workspace yang Anda pasang, atau chown folder workspace.

Alat kustom tidak ditemukan di sandbox

OpenClaw menjalankan perintah dengan sh -lc (login shell), yang memuat /etc/profile dan dapat mengatur ulang PATH. Atur docker.env.PATH untuk menambahkan path alat kustom Anda di awal, atau tambahkan skrip di bawah /etc/profile.d/ dalam Dockerfile Anda.

Terbunuh OOM saat build image (exit 137)

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

Tidak terotorisasi atau perlu pairing di Control UI

Ambil tautan dashboard baru dan setujui perangkat browser:

bash

docker compose run --rm openclaw-cli dashboard --no-opendocker compose run --rm openclaw-cli devices listdocker compose run --rm openclaw-cli devices approve <requestId>

Detail lebih lanjut: Dashboard, Perangkat.

Target Gateway menampilkan ws://172.x.x.x atau kesalahan pairing dari Docker CLI

Reset mode dan bind Gateway:

bash

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

Was this useful?

Docker

Apakah Docker tepat untuk saya?

Prasyarat

Gateway dalam kontainer

Build image

Jalankan ulang airgapped

Selesaikan onboarding

Buka Control UI

Konfigurasikan channel (opsional)

Alur manual

Variabel lingkungan

Observability

Health check

LAN vs loopback

Penyedia Lokal Host

Backend Claude CLI di Docker

Bonjour / mDNS

Penyimpanan dan persistensi

Helper shell (opsional)

Menjalankan di VPS?

Sandbox agen

Aktifkan cepat

Pemecahan masalah

Terkait

On this page

Molty