openclaw/docs

Fork 0

openclaw-docs-i18n[bot] 4e153e86e1 chore(i18n): refresh id translations

2026-04-23 09:31:08 +00:00

16 KiB

Raw Blame History

read_when

summary

title

x-i18n

Anda ingin gateway dalam container alih-alih instalasi lokal

Anda sedang memvalidasi alur Docker

Penyiapan dan onboarding berbasis Docker opsional untuk OpenClaw

Docker

generated_at	model	provider	source_hash	source_path	workflow
2026-04-23T09:22:37Z	gpt-5.4	openai	60a874ff7a3c5405ba4437a1d6746f0d9268ba7bd4faf3e20cee6079d5fb68d3	install/docker.md	15

Docker (opsional)

Docker bersifat opsional. Gunakan hanya jika Anda menginginkan gateway dalam container atau untuk memvalidasi alur Docker.

Apakah Docker cocok untuk saya?

Ya: Anda menginginkan environment gateway yang terisolasi dan sekali pakai atau ingin menjalankan OpenClaw di host tanpa instalasi lokal.
Tidak: Anda menjalankannya di mesin Anda sendiri dan hanya menginginkan loop dev 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
Setidaknya 2 GB RAM untuk build image (pnpm install dapat dibunuh 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 container

Dari root repo, jalankan skrip penyiapan:

```bash
./scripts/docker/setup.sh
```

Ini membangun image gateway secara lokal. Untuk menggunakan image pra-build:

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

Image pra-build dipublikasikan di
[GitHub Container Registry](https://github.com/openclaw/openclaw/pkgs/container/openclaw).
Tag umum: `main`, `latest`, `<version>` (mis. `2026.2.26`).

Skrip penyiapan menjalankan onboarding secara otomatis. Skrip ini akan:

- meminta API key provider
- menghasilkan token gateway dan menulisnya ke `.env`
- memulai gateway melalui Docker Compose

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

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 mengganti config container ke auth berbasis password, gunakan password itu sebagai gantinya.

Perlu URL-nya lagi?

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

Gunakan container CLI untuk menambahkan channel perpesanan:

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

Dokumen: [WhatsApp](/id/channels/whatsapp), [Telegram](/id/channels/telegram), [Discord](/id/channels/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 menulis `docker-compose.extra.yml`; sertakan dengan `-f docker-compose.yml -f docker-compose.extra.yml`. Karena `openclaw-cli` berbagi namespace jaringan `openclaw-gateway`, ini adalah tool pasca-start. Sebelum `docker compose up -d openclaw-gateway`, jalankan onboarding dan penulisan config saat penyiapan melalui `openclaw-gateway` dengan `--no-deps --entrypoint node`.

Variabel environment

Skrip penyiapan menerima variabel environment opsional berikut:

Variabel	Tujuan
`OPENCLAW_IMAGE`	Gunakan image remote alih-alih build lokal
`OPENCLAW_DOCKER_APT_PACKAGES`	Instal package apt tambahan selama build (dipisahkan spasi)
`OPENCLAW_EXTENSIONS`	Pra-instal dependensi plugin saat build (nama dipisahkan spasi)
`OPENCLAW_EXTRA_MOUNTS`	Bind mount host tambahan (dipisahkan koma `source:target[:opts]`)
`OPENCLAW_HOME_VOLUME`	Persist `/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 (tanpa 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 me-restart atau menggantinya.

Snapshot kesehatan mendalam dengan auth:

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 menjangkau port gateway yang dipublikasikan.
loopback: hanya proses di dalam namespace jaringan container 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`.

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 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 penuh pada deployment VM, lihat Docker VM Runtime - Apa yang persisten di mana.

Hotspot pertumbuhan disk: pantau media/, file JSONL sesi, cron/runs/*.jsonl, dan log file bergulir 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 mentah 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.

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

Path socket kustom (misalnya Docker rootless):

```bash
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 terpenuhi. Jika
penyiapan sandbox tidak dapat diselesaikan, skrip akan mereset `agents.defaults.sandbox.mode`
ke `off`.

Nonaktifkan alokasi pseudo-TTY Compose dengan `-T`:

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

`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`. 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
```

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

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

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

1. **Persist `/home/node`**: `export OPENCLAW_HOME_VOLUME="openclaw_home"`
2. **Bake dependensi sistem**: `export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"`
3. **Instal browser Playwright**:
   ```bash
   docker compose run --rm openclaw-cli \
     node /app/node_modules/playwright-core/cli.js install chromium
   ```
4. **Persist unduhan browser**: atur
   `PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright` dan gunakan
   `OPENCLAW_HOME_VOLUME` atau `OPENCLAW_EXTRA_MOUNTS`.

Jika Anda memilih OpenAI Codex OAuth di wizard, wizard akan membuka URL browser. Dalam Docker atau penyiapan headless, salin URL redirect lengkap tempat Anda mendarat dan tempelkan kembali ke wizard untuk menyelesaikan auth. 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](https://github.com/opencontainers/image-spec/blob/main/annotations.md).

Menjalankan di VPS?

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

Sandbox Agen

Saat agents.defaults.sandbox diaktifkan dengan backend Docker, gateway menjalankan eksekusi tool agen (shell, baca/tulis file, dll.) di dalam container Docker terisolasi sementara gateway sendiri tetap berada di host. Ini memberi Anda dinding keras di sekitar sesi agen yang tidak tepercaya atau multi-tenant tanpa harus meng-container-kan seluruh gateway.

Cakupan sandbox bisa per-agen (default), per-sesi, atau bersama. Setiap cakupan memiliki workspace sendiri yang di-mount di /workspace. Anda juga dapat mengonfigurasi kebijakan allow/deny tool, 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 Tool 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

Build image sandbox dengan [`scripts/sandbox-setup.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/sandbox-setup.sh) atau atur `agents.defaults.sandbox.docker.image` ke image kustom Anda. Container dibuat otomatis per sesi sesuai kebutuhan. Atur `docker.user` ke UID:GID yang cocok dengan kepemilikan workspace yang Anda mount, atau lakukan chown pada folder workspace. OpenClaw menjalankan perintah dengan `sh -lc` (login shell), yang melakukan source pada `/etc/profile` dan dapat mereset PATH. Atur `docker.env.PATH` untuk menambahkan path tool kustom Anda di depan, atau tambahkan skrip di bawah `/etc/profile.d/` di Dockerfile Anda. VM memerlukan setidaknya 2 GB RAM. Gunakan kelas mesin yang lebih besar lalu coba lagi. Ambil tautan dashboard baru dan setujui perangkat browser:

```bash
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](/id/web/dashboard), [Devices](/id/cli/devices).

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

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

16 KiB Raw Blame History