Docker (tùy chọn)

Docker là tùy chọn. Chỉ dùng nếu các bạn muốn chạy gateway trong container hoặc để kiểm tra quy trình Docker.

Docker có phù hợp với mình không?

  • Có: Các bạn muốn một môi trường gateway độc lập, có thể xóa bỏ dễ dàng, hoặc chạy OpenClaw trên máy chủ mà không cần cài đặt trực tiếp.
  • Không: Các bạn đang chạy trên máy của mình và chỉ muốn dev nhanh nhất. Dùng quy trình cài đặt thông thường thay vì Docker.
  • Lưu ý về Sandbox: Agent sandboxing cũng dùng Docker, nhưng không yêu cầu toàn bộ gateway phải chạy trong Docker. Xem Sandboxing.

Hướng dẫn này bao gồm:

  • Containerized Gateway (chạy toàn bộ OpenClaw trong Docker)
  • Per-session Agent Sandbox (gateway chạy trên host + các công cụ agent được cách ly trong Docker)

Chi tiết về Sandboxing: Sandboxing

Yêu cầu

  • Docker Desktop (hoặc Docker Engine) + Docker Compose v2
  • Đủ dung lượng đĩa cho images và logs

Containerized Gateway (Docker Compose)

Khởi động nhanh (khuyên dùng)

Từ thư mục gốc của repo:

./docker-setup.sh

Script này sẽ:

  • build gateway image
  • chạy wizard thiết lập ban đầu
  • hiển thị gợi ý cấu hình provider (tùy chọn)
  • khởi động gateway qua Docker Compose
  • tạo gateway token và ghi vào file .env

Các biến môi trường tùy chọn:

  • OPENCLAW_DOCKER_APT_PACKAGES — cài thêm các gói apt trong quá trình build
  • OPENCLAW_EXTRA_MOUNTS — thêm các bind mount từ host
  • OPENCLAW_HOME_VOLUME — lưu trữ /home/node trong named volume

Sau khi hoàn tất:

  • Mở http://127.0.0.1:18789/ trong trình duyệt.
  • Dán token vào Control UI (Settings → token).

Script sẽ ghi config/workspace trên host tại:

  • ~/.openclaw/
  • ~/.openclaw/workspace

Đang chạy trên VPS? Xem Hetzner (Docker VPS).

Quy trình thủ công (compose)

docker build -t openclaw:local -f Dockerfile .
docker compose run --rm openclaw-cli onboard
docker compose up -d openclaw-gateway

Thêm mount (tùy chọn)

Nếu các bạn muốn mount thêm các thư mục từ host vào container, hãy đặt OPENCLAW_EXTRA_MOUNTS trước khi chạy docker-setup.sh. Biến này nhận danh sách các Docker bind mount phân cách bằng dấu phẩy và áp dụng chúng cho cả openclaw-gateway và openclaw-cli bằng cách tạo file docker-compose.extra.yml.

Ví dụ:

export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh

Lưu ý:

  • Các đường dẫn phải được chia sẻ với Docker Desktop trên macOS/Windows.
  • Nếu các bạn sửa OPENCLAW_EXTRA_MOUNTS, chạy lại docker-setup.sh để tạo lại file compose bổ sung.
  • docker-compose.extra.yml được tạo tự động. Đừng sửa file này bằng tay.

Lưu trữ toàn bộ container home (tùy chọn)

Nếu các bạn muốn /home/node được lưu trữ khi tạo lại container, hãy đặt một named volume qua OPENCLAW_HOME_VOLUME. Điều này tạo một Docker volume và mount nó tại /home/node, đồng thời vẫn giữ các bind mount config/workspace tiêu chuẩn. Dùng named volume ở đây (không phải bind path); để dùng bind mount, hãy dùng OPENCLAW_EXTRA_MOUNTS.

Ví dụ:

export OPENCLAW_HOME_VOLUME="openclaw_home"
./docker-setup.sh

Các bạn có thể kết hợp với extra mounts:

export OPENCLAW_HOME_VOLUME="openclaw_home"
export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh

Lưu ý:

  • Nếu các bạn thay đổi OPENCLAW_HOME_VOLUME, chạy lại docker-setup.sh để tạo lại file compose bổ sung.
  • Named volume sẽ tồn tại cho đến khi xóa bằng docker volume rm <name>.

Cài thêm gói apt (tùy chọn)

Nếu các bạn cần các gói hệ thống trong image (ví dụ: build tools hoặc thư viện media), hãy đặt OPENCLAW_DOCKER_APT_PACKAGES trước khi chạy docker-setup.sh. Điều này cài các gói trong quá trình build image, nên chúng vẫn tồn tại ngay cả khi container bị xóa.

Ví dụ:

export OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg build-essential"
./docker-setup.sh

Lưu ý:

  • Biến này nhận danh sách tên gói apt phân cách bằng khoảng trắng.
  • Nếu các bạn thay đổi OPENCLAW_DOCKER_APT_PACKAGES, chạy lại docker-setup.sh để rebuild image.

Build nhanh hơn (khuyên dùng)

Để tăng tốc rebuild, sắp xếp Dockerfile sao cho các layer dependency được cache. Điều này tránh chạy lại pnpm install trừ khi lockfile thay đổi:

FROM node:22-bookworm

# Install Bun (required for build scripts)
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"

RUN corepack enable

WORKDIR /app

# Cache dependencies unless package metadata changes
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"]

Thiết lập Channel (tùy chọn)

Dùng CLI container để cấu hình các channel, sau đó khởi động lại gateway nếu cần.

WhatsApp (QR):

docker compose run --rm openclaw-cli channels login

Telegram (bot token):

docker compose run --rm openclaw-cli channels add --channel telegram --token "<token>"

Discord (bot token):

docker compose run --rm openclaw-cli channels add --channel discord --token "<token>"

Tài liệu: WhatsApp, Telegram, Discord

Kiểm tra sức khỏe

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

E2E smoke test (Docker)

scripts/e2e/onboard-docker.sh

QR import smoke test (Docker)

pnpm test:docker:qr

Lưu ý

  • Gateway bind mặc định là lan khi dùng container.
  • Gateway container là nguồn chính thống cho các session (~/.openclaw/agents/<agentId>/sessions/).

Agent Sandbox (host gateway + Docker tools)

Tìm hiểu sâu: Sandboxing

Nó làm gì

Khi agents.defaults.sandbox được bật, các session không phải main sẽ chạy các công cụ bên trong Docker container. Gateway vẫn ở trên host của các bạn, nhưng việc thực thi công cụ được cách ly:

  • scope: "agent" theo mặc định (một container + workspace cho mỗi agent)
  • scope: "session" để cách ly theo từng session
  • thư mục workspace theo scope được mount tại /workspace
  • truy cập agent workspace tùy chọn (agents.defaults.sandbox.workspaceAccess)
  • chính sách công cụ allow/deny (deny thắng)
  • media đầu vào được copy vào workspace sandbox đang hoạt động (media/inbound/*) để các công cụ có thể đọc (với workspaceAccess: "rw", nó sẽ nằm trong agent workspace)

Cảnh báo: scope: "shared" vô hiệu hóa cách ly giữa các session. Tất cả session dùng chung một container và một workspace.

Profile sandbox theo agent (multi-agent)

Nếu các bạn dùng multi-agent routing, mỗi agent có thể ghi đè cài đặt sandbox + tool: agents.list[].sandbox và agents.list[].tools (cộng với agents.list[].tools.sandbox.tools). Điều này cho phép các bạn chạy các mức truy cập khác nhau trong một gateway:

  • Truy cập đầy đủ (personal agent)
  • Công cụ chỉ đọc + workspace chỉ đọc (family/work agent)
  • Không có công cụ filesystem/shell (public agent)

Xem Multi-Agent Sandbox & Tools để biết ví dụ, thứ tự ưu tiên và cách khắc phục sự cố.

Hành vi mặc định

  • Image: openclaw-sandbox:bookworm-slim
  • Một container cho mỗi agent
  • Truy cập agent workspace: workspaceAccess: "none" (mặc định) dùng ~/.openclaw/sandboxes
    • "ro" giữ sandbox workspace tại /workspace và mount agent workspace ở chế độ chỉ đọc tại /agent (vô hiệu hóa write/edit/apply_patch)
    • "rw" mount agent workspace ở chế độ đọc/ghi tại /workspace
  • Tự động dọn dẹp: idle > 24h HOẶC tuổi > 7 ngày
  • Network: none theo mặc định (phải opt-in rõ ràng nếu cần egress)
  • Mặc định allow: exec, process, read, write, edit, sessions_list, sessions_history, sessions_send, sessions_spawn, session_status
  • Mặc định deny: browser, canvas, nodes, cron, discord, gateway

Bật sandboxing

Nếu các bạn định cài package trong setupCommand, lưu ý:

  • docker.network mặc định là "none" (không có egress).
  • readOnlyRoot: true chặn cài đặt package.
  • user phải là root cho apt-get (bỏ qua user hoặc đặt user: "0:0"). OpenClaw tự động tạo lại container khi setupCommand (hoặc docker config) thay đổi trừ khi container vừa được dùng (trong vòng ~5 phút). Các container đang hoạt động sẽ log cảnh báo với lệnh openclaw sandbox recreate ... chính xác.
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared (agent là mặc định)
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256,
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "openclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
        },
        prune: {
          idleHours: 24, // 0 vô hiệu hóa idle pruning
          maxAgeDays: 7, // 0 vô hiệu hóa max-age pruning
        },
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: [
          "exec",
          "process",
          "read",
          "write",
          "edit",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
        ],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
      },
    },
  },
}

Các tùy chọn bảo mật nằm trong agents.defaults.sandbox.docker: network, user, pidsLimit, memory, memorySwap, cpus, ulimits, seccompProfile, apparmorProfile, dns, extraHosts.

Multi-agent: ghi đè agents.defaults.sandbox.{docker,browser,prune}.* cho từng agent qua agents.list[].sandbox.{docker,browser,prune}.* (bị bỏ qua khi agents.defaults.sandbox.scope / agents.list[].sandbox.scope là "shared").

Build sandbox image mặc định

scripts/sandbox-setup.sh

Lệnh này build openclaw-sandbox:bookworm-slim dùng Dockerfile.sandbox.

Sandbox common image (tùy chọn)

Nếu các bạn muốn sandbox image với các công cụ build phổ biến (Node, Go, Rust, v.v.), hãy build common image:

scripts/sandbox-common-setup.sh

Lệnh này build openclaw-sandbox-common:bookworm-slim. Để dùng nó:

{
  agents: {
    defaults: {
      sandbox: { docker: { image: "openclaw-sandbox-common:bookworm-slim" } },
    },
  },
}

Sandbox browser image

Để chạy browser tool bên trong sandbox, hãy build browser image:

scripts/sandbox-browser-setup.sh

Lệnh này build openclaw-sandbox-browser:bookworm-slim dùng Dockerfile.sandbox-browser. Container chạy Chromium với CDP được bật và một noVNC observer tùy chọn (headful qua Xvfb).

Lưu ý:

  • Headful (Xvfb) giảm bot blocking so với headless.
  • Headless vẫn có thể dùng bằng cách đặt agents.defaults.sandbox.browser.headless=true.
  • Không cần môi trường desktop đầy đủ (GNOME); Xvfb cung cấp display.

Dùng config:

{
  agents: {
    defaults: {
      sandbox: {
        browser: { enabled: true },
      },
    },
  },
}

Browser image tùy chỉnh:

{
  agents: {
    defaults: {
      sandbox: { browser: { image: "my-openclaw-browser" } },
    },
  },
}

Khi được bật, agent nhận:

  • một URL điều khiển sandbox browser (cho công cụ browser)
  • một URL noVNC (nếu được bật và headless=false)

Nhớ là: nếu các bạn dùng allowlist cho tools, hãy thêm browser (và xóa nó khỏi deny) nếu không công cụ vẫn bị chặn. Quy tắc prune (agents.defaults.sandbox.prune) cũng áp dụng cho browser container.

Sandbox image tùy chỉnh

Build image của riêng các bạn và trỏ config đến nó:

docker build -t my-openclaw-sbx -f Dockerfile.sandbox .
{
  agents: {
    defaults: {
      sandbox: { docker: { image: "my-openclaw-sbx" } },
    },
  },
}

Chính sách công cụ (allow/deny)

  • deny thắng allow.
  • Nếu allow rỗng: tất cả công cụ (trừ deny) đều khả dụng.
  • Nếu allow không rỗng: chỉ các công cụ trong allow khả dụng (trừ deny).

Chiến lược dọn dẹp

Hai tùy chọn:

  • prune.idleHours: xóa container không dùng trong X giờ (0 = vô hiệu hóa)
  • prune.maxAgeDays: xóa container cũ hơn X ngày (0 = vô hiệu hóa)

Ví dụ:

  • Giữ session bận nhưng giới hạn thời gian sống: idleHours: 24, maxAgeDays: 7
  • Không bao giờ dọn dẹp: idleHours: 0, maxAgeDays: 0

Lưu ý bảo mật

  • Rào cản cứng chỉ áp dụng cho tools (exec/read/write/edit/apply_patch).
  • Các công cụ chỉ chạy trên host như browser/camera/canvas bị chặn theo mặc định.
  • Cho phép browser trong sandbox phá vỡ cách ly (browser chạy trên host).

Troubleshooting

  • Thiếu image: build bằng scripts/sandbox-setup.sh hoặc đặt agents.defaults.sandbox.docker.image.
  • Container không chạy: nó sẽ tự động tạo theo session khi cần.
  • Lỗi quyền trong sandbox: đặt docker.user thành UID:GID khớp với quyền sở hữu workspace được mount (hoặc chown thư mục workspace).
  • Không tìm thấy công cụ tùy chỉnh: OpenClaw chạy lệnh với sh -lc (login shell), cái này source /etc/profile và có thể reset PATH. Đặt docker.env.PATH để thêm đường dẫn công cụ tùy chỉnh vào đầu (ví dụ: /custom/bin:/usr/local/share/npm-global/bin), hoặc thêm một script trong /etc/profile.d/ trong Dockerfile của các bạn.