Docker bersifat opsional. Gunakan hanya jika Anda menginginkan Gateway berbasis kontainer atau ingin memvalidasi alur Docker.Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
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 installdapat 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
Pengerasan keamanan untuk eksposur jaringan,
terutama kebijakan firewall Docker
DOCKER-USER.
Gateway berbasis kontainer
Build image
Dari root repo, jalankan skrip setup:Ini membangun image Gateway secara lokal. Untuk menggunakan image yang sudah dibuat sebagai gantinya:Image yang sudah dibuat diterbitkan di
GitHub Container Registry.
Tag umum:
main, latest, <version> (mis. 2026.2.26).Selesaikan onboarding
Skrip setup menjalankan onboarding secara otomatis. Skrip ini akan:
- meminta kunci API penyedia
- menghasilkan token Gateway dan menulisnya ke
.env - membuat direktori kunci rahasia auth-profile
- memulai Gateway melalui Docker Compose
openclaw-gateway. openclaw-cli digunakan untuk perintah yang Anda jalankan setelah
kontainer Gateway sudah ada.Buka UI Kontrol
Buka
http://127.0.0.1:18789/ di browser Anda dan tempelkan rahasia bersama yang dikonfigurasi
ke Settings. Skrip setup menulis token ke .env secara default; jika Anda mengganti konfigurasi
kontainer ke autentikasi kata sandi, gunakan kata sandi tersebut sebagai gantinya.Perlu URL-nya lagi?Alur manual
Jika Anda lebih memilih menjalankan setiap langkah sendiri alih-alih menggunakan skrip setup:Jalankan
docker compose dari root repo. Jika Anda mengaktifkan OPENCLAW_EXTRA_MOUNTS
atau OPENCLAW_HOME_VOLUME, skrip setup 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, alat ini adalah
alat pasca-start. Sebelum docker compose up -d openclaw-gateway, jalankan onboarding
dan penulisan konfigurasi saat setup melalui openclaw-gateway dengan
--no-deps --entrypoint node.Variabel lingkungan
Skrip setup menerima variabel lingkungan opsional berikut:| Variabel | Tujuan |
|---|---|
OPENCLAW_IMAGE | Menggunakan image jarak jauh alih-alih membangun secara lokal |
OPENCLAW_DOCKER_APT_PACKAGES | Menginstal paket apt tambahan selama build (dipisahkan spasi) |
OPENCLAW_EXTENSIONS | Menyertakan pembantu plugin bawaan tertentu saat build |
OPENCLAW_EXTRA_MOUNTS | Bind mount host tambahan (source:target[:opts] dipisahkan koma) |
OPENCLAW_HOME_VOLUME | Mempertahankan /home/node dalam volume Docker bernama |
OPENCLAW_SANDBOX | Mengaktifkan bootstrap sandbox (1, true, yes, on) |
OPENCLAW_SKIP_ONBOARDING | Melewati langkah onboarding interaktif (1, true, yes, on) |
OPENCLAW_DOCKER_SOCKET | Mengganti path soket Docker |
OPENCLAW_DISABLE_BONJOUR | Menonaktifkan iklan Bonjour/mDNS (default 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 spesifik 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 | Mengaktifkan atribut semantik GenAI eksperimental terbaru |
OPENCLAW_OTEL_PRELOADED | Melewati pemulaian SDK OpenTelemetry kedua saat sudah dipramuat |
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.
Observabilitas
Ekspor OpenTelemetry bersifat outbound dari kontainer 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:@openclaw/diagnostics-otel dari ClawHub dalam
instalasi Docker terpaket sebelum mengaktifkan ekspor. Image kustom yang dibuat 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:
/metrics terpisah atau path reverse-proxy tanpa autentikasi. Lihat
Metrik Prometheus.
Pemeriksaan kesehatan
Endpoint probe kontainer (tanpa autentikasi):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 yang terautentikasi:
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 kontainer yang dapat menjangkau 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.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 setup 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 |
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:
docker run sendiri, tambahkan mapping 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, setup Compose bawaan menetapkan default
OPENCLAW_DISABLE_BONJOUR=1 sehingga 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-mountOPENCLAW_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
bertahan setelah penggantian kontainer. Saat variabel apa pun tidak disetel, file
docker-compose.yml bawaan melakukan fallback ke bawah ${HOME}, atau /tmp saat HOME sendiri
juga tidak ada. Ini mencegah docker compose up memancarkan spesifikasi volume
dengan sumber kosong pada lingkungan polos.
Direktori konfigurasi yang dipasang itu adalah tempat OpenClaw menyimpan:
openclaw.jsonuntuk konfigurasi perilakuagents/<agentId>/agent/auth-profiles.jsonuntuk autentikasi OAuth/kunci API penyedia yang tersimpan.envuntuk rahasia runtime berbasis env sepertiOPENCLAW_GATEWAY_TOKEN
OPENCLAW_CONFIG_DIR.
Plugin unduhan yang terinstal menyimpan status paketnya di bawah home
OpenClaw yang dipasang, sehingga catatan instalasi plugin dan akar paket tetap
bertahan setelah penggantian kontainer. Startup Gateway tidak menghasilkan pohon
dependensi plugin bawaan.
Untuk detail persistensi lengkap pada deployment VM, lihat
Runtime VM Docker - Apa yang tetap ada di mana.
Hotspot pertumbuhan disk: pantau media/, file JSONL sesi,
cron/runs/*.jsonl, akar paket plugin yang terinstal, dan log file bergulir
di bawah /tmp/openclaw/.
Pembantu shell (opsional)
Untuk manajemen Docker sehari-hari yang lebih mudah, instalClawDock:
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.
Enable agent sandbox for Docker gateway
Enable agent sandbox for Docker gateway
docker.sock 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 Codex
workspace-write saat sandbox OpenClaw aktif; jangan pasang
socket Docker host ke dalam kontainer sandbox agent.Automation / CI (non-interactive)
Automation / CI (non-interactive)
Nonaktifkan alokasi pseudo-TTY Compose dengan
-T:Shared-network security note
Shared-network security note
Docker Desktop DNS failures in openclaw-cli
Docker Desktop DNS failures in openclaw-cli
Beberapa penyiapan Docker Desktop gagal melakukan lookup DNS dari sidecar
Jika Anda sudah membuat kontainer
openclaw-cli jaringan bersama setelah NET_RAW dihapus, yang muncul sebagai
EAI_AGAIN selama perintah berbasis npm seperti openclaw plugins install.
Pertahankan file compose terkeras default 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 pakai yang membutuhkan akses registry paket, bukan sebagai invocation
Compose default Anda: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.Permissions and EACCES
Permissions and EACCES
Image berjalan sebagai Ketidakcocokan yang sama dapat muncul sebagai peringatan plugin seperti
node (uid 1000). Jika Anda melihat error izin pada
/home/node/.openclaw, pastikan bind mount host Anda dimiliki oleh uid 1000: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 cocok. Utamakan 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 untuk jangka panjang.Faster rebuilds
Faster rebuilds
Urutkan Dockerfile Anda agar layer dependensi di-cache. Ini menghindari menjalankan ulang
pnpm install kecuali lockfile berubah:Power-user container options
Power-user container options
Image default mengutamakan keamanan dan berjalan sebagai
node non-root. Untuk kontainer yang lebih
lengkap fiturnya:- Persistenkan
/home/node:export OPENCLAW_HOME_VOLUME="openclaw_home" - Paketkan deps sistem:
export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq" - Paketkan Playwright Chromium:
export OPENCLAW_INSTALL_BROWSER=1 - Atau instal browser Playwright ke volume persisten:
- Persistenkan unduhan browser: gunakan
OPENCLAW_HOME_VOLUMEatauOPENCLAW_EXTRA_MOUNTS. OpenClaw mendeteksi otomatis Chromium yang dikelola Playwright dari image Docker di Linux.
OpenAI Codex OAuth (headless Docker)
OpenAI Codex OAuth (headless Docker)
Jika Anda memilih OpenAI Codex OAuth di wizard, URL browser akan dibuka. Dalam
penyiapan Docker atau headless, salin URL redirect lengkap tempat Anda berakhir dan tempelkan
kembali ke wizard untuk menyelesaikan auth.
Base image metadata
Base image metadata
Image runtime Docker utama menggunakan
node:24-bookworm-slim dan menyertakan tini sebagai proses init entrypoint (PID 1) untuk memastikan proses zombie dipanen dan sinyal ditangani dengan benar dalam kontainer yang berjalan lama. Image ini menerbitkan anotasi base-image OCI termasuk org.opencontainers.image.base.name,
org.opencontainers.image.source, dan lainnya. Digest base Node
diperbarui melalui PR base-image Docker Dependabot; build rilis tidak menjalankan
layer upgrade distro. Lihat
Anotasi image OCI.Berjalan di VPS?
Lihat Hetzner (Docker VPS) dan Runtime VM Docker untuk langkah deployment VM bersama termasuk pemaketan binary, persistensi, dan pembaruan.Sandbox agent
Saatagents.defaults.sandbox diaktifkan dengan backend Docker, gateway
menjalankan eksekusi alat agent (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 agent yang tidak tepercaya atau multi-tenant tanpa mengontainerisasi seluruh
gateway.
Cakupan sandbox dapat per-agent (default), per-session, atau bersama. Setiap cakupan
mendapat workspace sendiri yang dipasang di /workspace. Anda juga dapat mengonfigurasi
kebijakan allow/deny alat, isolasi jaringan, batas sumber daya, dan kontainer
browser.
Untuk konfigurasi lengkap, image, catatan keamanan, dan profil multi-agent, lihat:
- Sandboxing — referensi sandbox lengkap
- OpenShell — akses shell interaktif ke kontainer sandbox
- Sandbox dan Alat Multi-Agent — override per-agent
Aktifkan cepat
docker build inline.
Pemecahan masalah
Image missing or sandbox container not starting
Image missing or sandbox container not starting
Build image sandbox dengan
scripts/sandbox-setup.sh
(checkout sumber) atau perintah docker build inline dari Sandboxing § Image dan penyiapan (instal npm),
atau set agents.defaults.sandbox.docker.image ke image kustom Anda.
Kontainer dibuat otomatis per sesi sesuai permintaan.Permission errors in sandbox
Permission errors in sandbox
Set
docker.user ke UID:GID yang cocok dengan kepemilikan workspace yang dipasang,
atau chown folder workspace.Custom tools not found in sandbox
Custom tools not found in sandbox
OpenClaw menjalankan perintah dengan
sh -lc (shell login), yang mengambil sumber
/etc/profile dan dapat mereset PATH. Set docker.env.PATH untuk menambahkan path
alat kustom Anda di awal, atau tambahkan skrip di bawah /etc/profile.d/ dalam Dockerfile Anda.OOM-killed during image build (exit 137)
OOM-killed during image build (exit 137)
VM membutuhkan RAM minimal 2 GB. Gunakan kelas mesin yang lebih besar dan coba lagi.
Unauthorized or pairing required in Control UI
Unauthorized or pairing required in Control UI
Gateway target shows ws://172.x.x.x or pairing errors from Docker CLI
Gateway target shows ws://172.x.x.x or pairing errors from Docker CLI
Reset mode gateway dan bind:
Terkait
- Ikhtisar Instalasi — semua metode instalasi
- Podman — alternatif Podman untuk Docker
- ClawDock — penyiapan komunitas Docker Compose
- Memperbarui — menjaga OpenClaw tetap terbaru
- Konfigurasi — konfigurasi gateway setelah instalasi