Docker

Docker bersifat opsional. Gunakan untuk lingkungan Gateway yang terisolasi dan sekali pakai atau host tanpa instalasi lokal. Jika Anda sudah melakukan pengembangan di mesin sendiri, gunakan alur instalasi normal sebagai gantinya.

Backend sandbox default menggunakan Docker saat agents.defaults.sandbox diaktifkan, tetapi sandbox dinonaktifkan secara default dan tidak mengharuskan Gateway itu sendiri berjalan di Docker. Backend sandbox SSH dan OpenShell juga tersedia; lihat Sandboxing.

Meng-host beberapa pengguna? Lihat Hosting multi-tenant untuk model satu sel per tenant.

Prasyarat

• Docker Desktop (atau Docker Engine) + Docker Compose v2
• RAM minimal 2 GB untuk membangun image (pnpm install dapat dihentikan karena OOM pada host dengan RAM 1 GB dan keluar dengan kode 137)
• Ruang disk yang cukup untuk image dan log
• Pada VPS/host publik, tinjau Penguatan keamanan untuk paparan jaringan, khususnya rantai firewall Docker DOCKER-USER

Gateway dalam kontainer

./scripts/docker/setup.sh

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

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

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

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

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

Alur manual

BUILD_GIT_COMMIT="$(git rev-parse HEAD)"BUILD_TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"docker build \  --build-arg "GIT_COMMIT=${BUILD_GIT_COMMIT}" \  --build-arg "OPENCLAW_BUILD_TIMESTAMP=${BUILD_TIMESTAMP}" \  -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

Konteks Docker mengecualikan .git. Teruskan identitas sumber sebagai argumen build seperti ditunjukkan di atas agar layar Tentang pada image melaporkan commit yang di-checkout dan satu stempel waktu build. scripts/docker/setup.sh menentukan dan meneruskan kedua nilai tersebut secara otomatis.

Meningkatkan versi image kontainer

Saat Anda mengganti image OpenClaw tetapi mempertahankan state/konfigurasi terpasang yang sama, Gateway baru menjalankan migrasi peningkatan versi yang aman saat startup dan konvergensi plugin sebelum siap. Peningkatan versi image rutin seharusnya tidak memerlukan proses openclaw doctor --fix terpisah.

Jika startup tidak dapat menyelesaikan perbaikan tersebut dengan aman, Gateway akan berhenti alih-alih melaporkan status sehat. Dengan kebijakan restart, Docker, Podman, atau Kubernetes mungkin menampilkan kontainer Gateway yang terus dimulai ulang. Pertahankan volume state yang terpasang, lalu jalankan image yang sama sekali dengan openclaw doctor --fix sebagai perintah kontainer, menggunakan mount state/konfigurasi yang sama dengan yang digunakan Gateway:

docker run --rm -v <openclaw-state>:/home/node/.openclaw <image> openclaw doctor --fixpodman run --rm -v <openclaw-state>:/home/node/.openclaw <image> openclaw doctor --fix

Setelah doctor selesai, mulai ulang kontainer Gateway dengan perintah default-nya. Di Kubernetes, jalankan perintah yang sama dalam Job sekali jalan atau pod debug yang dipasang ke PVC yang sama, lalu mulai ulang Deployment atau StatefulSet.

Variabel lingkungan

Variabel opsional yang diterima oleh scripts/docker/setup.sh (dan, untuk kontainer Gateway, langsung oleh docker-compose.yml):

Image resmi tidak menyertakan Homebrew. Selama onboarding, OpenClaw menyembunyikan penginstal dependensi skill khusus brew dalam kontainer Linux tanpa brew; sediakan dependensi tersebut melalui image khusus atau instal secara manual. Gunakan OPENCLAW_IMAGE_APT_PACKAGES untuk dependensi yang dikemas Debian dan OPENCLAW_IMAGE_PIP_PACKAGES untuk dependensi Python (menjalankan python3 -m pip install --break-system-packages pada waktu build, jadi patok versinya dan hanya gunakan indeks yang Anda percayai).

Jika Docker melaporkan ResourceExhausted, cannot allocate memory, atau berhenti selama tsdown, tingkatkan batas memori builder Docker atau coba lagi dengan heap eksplisit yang lebih kecil:

OPENCLAW_DOCKER_BUILD_NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB=4096

Image yang dibangun dari sumber dengan plugin terpilih

OPENCLAW_EXTENSIONS memilih id manifes plugin dari checkout sumber; nama direktori sumber yang ada juga diterima jika berbeda. Build Docker menetapkan pilihan ke direktori sumber satu kali, menginstal dependensi produksi, dan, ketika plugin yang dipilih diterbitkan secara terpisah dengan openclaw.build.bundledDist: false, mengompilasi runtime-nya ke dalam dist gabungan root. Pengemasan khusus Docker ini tidak mengubah kontrak artefak npm atau ClawHub plugin tersebut. Id yang tidak dikenal, tidak valid, atau ambigu menyebabkan build image gagal. Id khusus dependensi/sumber yang dikenal mempertahankan staging sumber dan dependensi yang ada tanpa memperoleh entri dist root terkompilasi. Plugin terpilih dengan entri build terpadu harus berhasil dikompilasi; sumber dan output runtime plugin eksternal yang tidak dipilih dipangkas.

Misalnya, perintah berikut membuat image gateway mandiri FakeCo multi-arsitektur yang terpisah untuk ClickClack, Slack, dan Microsoft Teams. ClawRouter sudah menjadi bagian dari runtime root OpenClaw, sehingga image ClickClack hanya memilih clickclack. Argumen browser kosong yang eksplisit menjaga image default tetap bebas dari Chromium:

SOURCE_SHA="$(git rev-parse HEAD)"BUILD_TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"REGISTRY="registry.example.com/fakeco" build_gateway_image() {  gateway="$1"  selected_plugin="$2"  docker buildx build \    --platform linux/amd64,linux/arm64 \    --build-arg "GIT_COMMIT=${SOURCE_SHA}" \    --build-arg "OPENCLAW_BUILD_TIMESTAMP=${BUILD_TIMESTAMP}" \    --build-arg "OPENCLAW_EXTENSIONS=${selected_plugin}" \    --build-arg OPENCLAW_INSTALL_BROWSER= \    --provenance=mode=max \    --sbom=true \    --tag "${REGISTRY}/openclaw-${gateway}:${SOURCE_SHA}" \    --push \    .} build_gateway_image clickclack clickclackbuild_gateway_image slack slackbuild_gateway_image teams msteams

Gunakan --platform linux/arm64 --load atau --platform linux/amd64 --load untuk satu build lokal native. Output multiplatform serta SBOM/provenance terlampir memerlukan registry atau output Buildx lain yang mempertahankan atestasi. Setelah melakukan push, periksa manifes dan terapkan digest yang tidak dapat diubah alih-alih tag SHA sumber yang dapat diubah:

docker buildx imagetools inspect \  "${REGISTRY}/openclaw-clickclack:${SOURCE_SHA}"# Terapkan: registry.example.com/fakeco/openclaw-clickclack@sha256:<manifest-digest>

Image ini ditujukan untuk gateway mandiri berbasis OCI dan pengguna Docker umum. Gateway yang dikelola Crabhelm tidak menggunakannya: jalur pengiriman tersebut membuat arsip appliance x86_64 terpisah yang berisi tarball npm OpenClaw dan mengunci digest Node, arsip, serta manifes. Build appliance tersebut secara terpisah dari sumber OpenClaw yang sama yang telah digabungkan.

Untuk menguji sumber plugin gabungan terhadap image terkemas, pasang satu direktori sumber plugin di atas jalur sumber terkemasnya, misalnya OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro. Ini menggantikan bundle /app/dist/extensions/synology-chat terkompilasi yang cocok untuk id plugin yang sama.

Observabilitas

Ekspor OpenTelemetry bersifat keluar dari kontainer Gateway menuju kolektor OTLP Anda; ini tidak memerlukan port Docker yang dipublikasikan. Untuk menyertakan eksportir gabungan dalam image yang dibuat secara lokal:

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

Image bawaan resmi sudah menyertakan diagnostics-otel; instal sendiri clawhub:@openclaw/diagnostics-otel hanya jika Anda menghapusnya. Untuk mengaktifkan ekspor, izinkan dan aktifkan plugin diagnostics-otel dalam konfigurasi, lalu tetapkan diagnostics.otel.enabled=true (lihat contoh lengkap di Ekspor OpenTelemetry). Header autentikasi kolektor diteruskan melalui diagnostics.otel.headers, bukan variabel lingkungan Docker.

Metrik Prometheus menggunakan kembali port Gateway yang sudah dipublikasikan. Instal clawhub:@openclaw/diagnostics-prometheus, aktifkan plugin diagnostics-prometheus, lalu lakukan scraping:

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

Rute tersebut dilindungi oleh autentikasi Gateway; jangan ekspos port publik /metrics terpisah atau jalur reverse proxy tanpa autentikasi. Lihat Metrik Prometheus.

Pemeriksaan kesehatan

Endpoint probe kontainer (tidak memerlukan autentikasi):

curl -fsS http://127.0.0.1:18789/healthz   # keaktifancurl -fsS http://127.0.0.1:18789/readyz     # kesiapan

HEALTHCHECK bawaan image melakukan ping ke /healthz; kegagalan berulang menandai kontainer sebagai unhealthy agar orkestrator dapat memulai ulang atau menggantinya.

Snapshot kesehatan mendalam yang diautentikasi:

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

LAN vs loopback

scripts/docker/setup.sh menetapkan OPENCLAW_GATEWAY_BIND=lan secara default agar http://127.0.0.1:18789 pada host berfungsi dengan publikasi port Docker.

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

Penyedia lokal host

Di dalam kontainer, 127.0.0.1 adalah kontainer itu sendiri, bukan host. Gunakan host.docker.internal untuk penyedia yang berjalan pada host:

Penyiapan gabungan menggunakan URL tersebut sebagai default onboarding LM Studio/Ollama, dan docker-compose.yml memetakan host.docker.internal ke gateway host pada Docker Engine Linux (Docker Desktop menyediakan alias yang sama pada macOS/Windows). Layanan host harus mendengarkan pada alamat yang dapat dijangkau Docker:

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

Menggunakan file Compose Anda sendiri atau docker run? Tambahkan sendiri pemetaan yang sama, misalnya --add-host=host.docker.internal:host-gateway.

Backend Claude CLI di Docker

Image resmi tidak menginstal Claude Code sebelumnya. Instal dan masuk di dalam pengguna node kontainer, lalu persistensikan home kontainer tersebut agar peningkatan image tidak menghapus biner atau status autentikasi.

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

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

Untuk instalasi yang sudah ada, hentikan stack dan muat ulang nilai .env saat ini terlebih dahulu — skrip penyiapan selalu menulis ulang .env dari shell dan default saat ini, skrip tersebut tidak membaca file itu sendiri:

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

Jika .env berisi nilai yang tidak dapat dimuat oleh shell Anda, ekspor ulang secara manual terlebih dahulu nilai yang Anda andalkan (OPENCLAW_IMAGE, port, mode bind, jalur khusus, OPENCLAW_EXTRA_MOUNTS, sandbox, lewati onboarding). Overlay yang dihasilkan memasang volume home untuk openclaw-gateway dan openclaw-cli; jalankan perintah yang tersisa dengan overlay tersebut (dan docker-compose.override.yml terlebih dahulu, jika Anda menggunakannya):

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'

Penginstal native menulis claude ke /home/node/.local/bin/claude. Arahkan OpenClaw ke jalur tersebut:

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 home persisten yang sama:

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

Kemudian gunakan backend claude-cli gabungan:

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 "Sampaikan salam dari Docker Claude CLI"

OPENCLAW_HOME_VOLUME mempertahankan instalasi native di bawah /home/node/.local/bin dan /home/node/.local/share/claude, serta pengaturan/autentikasi Claude Code di bawah /home/node/.claude dan /home/node/.claude.json. Mempertahankan hanya /home/node/.openclaw tidaklah cukup; jika Anda menggunakan OPENCLAW_EXTRA_MOUNTS alih-alih volume home, pasang semua jalur Claude tersebut ke kedua layanan.

Bonjour / mDNS

Jaringan bridge Docker biasanya tidak meneruskan multicast Bonjour/mDNS (224.0.0.251:5353) secara andal. Ketika OPENCLAW_DISABLE_BONJOUR tidak ditetapkan, plugin Bonjour gabungan otomatis menonaktifkan iklan LAN setelah mendeteksi bahwa plugin berjalan dalam kontainer, sehingga tidak akan mengalami crash loop saat berulang kali mencoba multicast yang dibuang bridge. Tetapkan OPENCLAW_DISABLE_BONJOUR=1 untuk memaksanya nonaktif terlepas dari hasil deteksi, atau 0 untuk memaksanya aktif (hanya pada jaringan host, macvlan, atau jaringan lain yang diketahui mendukung multicast mDNS).

Jika tidak, gunakan URL Gateway yang dipublikasikan, Tailscale, atau DNS-SD area luas untuk host Docker. Lihat Penemuan Bonjour untuk kendala dan pemecahan masalah.

Penyimpanan dan persistensi

Docker Compose memasang secara bind 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 jalur tersebut tetap bertahan setelah penggantian kontainer. Ketika suatu variabel tidak ditetapkan, docker-compose.yml kembali menggunakan lokasi di bawah ${HOME}, atau /tmp jika HOME sendiri tidak ada, sehingga docker compose up tidak pernah menghasilkan spesifikasi volume dengan sumber kosong pada lingkungan dasar.

Direktori konfigurasi yang dipasang tersebut menyimpan:

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

Direktori rahasia profil autentikasi menyimpan kunci enkripsi lokal untuk materi token profil autentikasi berbasis OAuth. Simpan bersama status host Docker Anda, tetapi pisahkan dari OPENCLAW_CONFIG_DIR.

Plugin unduhan yang diinstal menyimpan status paket di bawah home OpenClaw yang dipasang, sehingga catatan instalasi dan root paket tetap bertahan setelah penggantian kontainer; startup gateway tidak membuat ulang pohon dependensi plugin gabungan.

Untuk detail lengkap persistensi VM, lihat Runtime VM Docker - Apa yang dipertahankan di mana.

Titik utama pertumbuhan disk: media/, database SQLite per agen, transkrip JSONL sesi lama, database status SQLite bersama, root paket plugin yang diinstal, dan log file bergulir di bawah /tmp/openclaw/.

Pembantu shell (opsional)

Untuk perintah harian yang lebih singkat, instal ClawDock:

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 menginstal dari jalur scripts/shell-helpers/clawdock-helpers.sh yang lama, jalankan kembali perintah di atas agar helper lokal Anda mengikuti lokasi saat ini. Kemudian gunakan clawdock-start, clawdock-stop, clawdock-dashboard, dan seterusnya (jalankan clawdock-help untuk daftar lengkap).

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

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

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

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>

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

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

Berjalan di VPS?

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

Sandbox agen

Saat agents.defaults.sandbox diaktifkan dengan backend Docker, Gateway menjalankan eksekusi alat agen (shell, baca/tulis berkas, dan sebagainya) di dalam kontainer Docker terisolasi sementara Gateway itu sendiri tetap berada di host — batas tegas di sekitar sesi agen yang tidak tepercaya atau multitenan tanpa memasukkan seluruh Gateway ke dalam kontainer.

Cakupan sandbox dapat berupa per agen (default), per sesi, atau bersama; setiap cakupan mendapatkan ruang kerja 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 multiagen:

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

Aktivasi cepat

{  agents: {    defaults: {      sandbox: {        mode: "non-main", // nonaktif | non-main | semua        scope: "agent", // sesi | agen | bersama      },    },  },}

Build image sandbox default (dari checkout sumber):

scripts/sandbox-setup.sh

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

Pemecahan masalah

docker compose run --rm openclaw-cli dashboard --no-opendocker compose run --rm openclaw-cli devices listdocker 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

• Ikhtisar Instalasi — semua metode instalasi
• Podman — alternatif Podman untuk Docker
• ClawDock — penyiapan Docker Compose komunitas
• Pembaruan — menjaga OpenClaw tetap mutakhir
• Konfigurasi — konfigurasi Gateway setelah instalasi