Sandbox CLI

Quản lý các container sandbox dựa trên Docker để chạy Agent trong môi trường cô lập.

Tổng quan

OpenClaw có thể chạy các Agent trong các container Docker cô lập để đảm bảo bảo mật. Các lệnh sandbox giúp các bạn quản lý các container này, đặc biệt sau khi cập nhật hoặc thay đổi cấu hình.

Các lệnh

openclaw sandbox explain

Kiểm tra chế độ/phạm vi/quyền truy cập Workspace hiệu lực của Sandbox, chính sách công cụ sandbox, và các cổng nâng cao (kèm đường dẫn config key để sửa).

openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json

openclaw sandbox list

Liệt kê tất cả các container sandbox với trạng thái và cấu hình của chúng.

openclaw sandbox list
openclaw sandbox list --browser  # Chỉ liệt kê browser containers
openclaw sandbox list --json     # Xuất ra JSON

Thông tin hiển thị:

  • Tên container và trạng thái (running/stopped)
  • Docker image và có khớp với config không
  • Tuổi (thời gian từ khi tạo)
  • Thời gian idle (thời gian từ lần dùng cuối)
  • Session/Agent liên kết

openclaw sandbox recreate

Xóa các container sandbox để buộc tạo lại với image/config đã cập nhật.

openclaw sandbox recreate --all                # Tạo lại tất cả containers
openclaw sandbox recreate --session main       # Session cụ thể
openclaw sandbox recreate --agent mybot        # Agent cụ thể
openclaw sandbox recreate --browser            # Chỉ browser containers
openclaw sandbox recreate --all --force        # Bỏ qua xác nhận

Tùy chọn:

  • --all: Tạo lại tất cả sandbox containers
  • --session <key>: Tạo lại container cho session cụ thể
  • --agent <id>: Tạo lại containers cho agent cụ thể
  • --browser: Chỉ tạo lại browser containers
  • --force: Bỏ qua prompt xác nhận

Quan trọng: Các container sẽ tự động được tạo lại khi Agent được sử dụng lần tiếp theo.

Các trường hợp sử dụng

Sau khi cập nhật Docker images

# Pull image mới
docker pull openclaw-sandbox:latest
docker tag openclaw-sandbox:latest openclaw-sandbox:bookworm-slim

# Cập nhật config để dùng image mới
# Sửa config: agents.defaults.sandbox.docker.image (hoặc agents.list[].sandbox.docker.image)

# Tạo lại containers
openclaw sandbox recreate --all

Sau khi thay đổi cấu hình sandbox

# Sửa config: agents.defaults.sandbox.* (hoặc agents.list[].sandbox.*)

# Tạo lại để áp dụng config mới
openclaw sandbox recreate --all

Sau khi thay đổi setupCommand

openclaw sandbox recreate --all
# hoặc chỉ một agent:
openclaw sandbox recreate --agent family

Chỉ cho một agent cụ thể

# Chỉ cập nhật containers của một agent
openclaw sandbox recreate --agent alfred

Tại sao cần lệnh này?

Vấn đề: Khi các bạn cập nhật Docker images hoặc cấu hình sandbox:

  • Các container hiện tại vẫn tiếp tục chạy với cài đặt cũ
  • Containers chỉ được dọn dẹp sau 24 giờ không hoạt động
  • Các Agent được dùng thường xuyên sẽ giữ container cũ chạy mãi

Giải pháp: Dùng openclaw sandbox recreate để buộc xóa các container cũ. Chúng sẽ tự động được tạo lại với cài đặt hiện tại khi cần dùng lần sau.

Mẹo: nên dùng openclaw sandbox recreate thay vì docker rm thủ công. Lệnh này sử dụng cách đặt tên container của Gateway và tránh lỗi không khớp khi scope/session keys thay đổi.

Cấu hình

Các cài đặt Sandbox nằm trong ~/.openclaw/openclaw.json ở mục agents.defaults.sandbox (ghi đè cho từng agent thì đặt trong agents.list[].sandbox):

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all", // off, non-main, all
        "scope": "agent", // session, agent, shared
        "docker": {
          "image": "openclaw-sandbox:bookworm-slim",
          "containerPrefix": "openclaw-sbx-",
          // ... thêm các tùy chọn Docker khác
        },
        "prune": {
          "idleHours": 24, // Tự động dọn sau 24h idle
          "maxAgeDays": 7, // Tự động dọn sau 7 ngày
        },
      },
    },
  },
}

Xem thêm