Cơ chế cách ly

OpenClaw có thể chạy công cụ bên trong các backend hộp cát để giảm phạm vi ảnh hưởng. Điều này là tùy chọn và được kiểm soát bằng cấu hình (agents.defaults.sandbox hoặc agents.list[].sandbox). Nếu tắt hộp cát, công cụ chạy trên máy chủ. Gateway vẫn ở trên máy chủ; việc thực thi công cụ chạy trong một hộp cát cô lập khi được bật.

# Những gì được đưa vào hộp cát

• Thực thi công cụ (exec, read, write, edit, apply_patch, process, v.v.).
• Trình duyệt trong hộp cát tùy chọn (agents.defaults.sandbox.browser).

Không được đưa vào hộp cát:

• Chính tiến trình Gateway.
• Bất kỳ công cụ nào được cho phép rõ ràng để chạy bên ngoài hộp cát (ví dụ tools.elevated).
  • Elevated exec bỏ qua hộp cát và dùng đường thoát đã cấu hình (gateway theo mặc định, hoặc node khi đích exec là node).
  • Nếu tắt hộp cát, tools.elevated không thay đổi cách thực thi (vốn đã ở trên máy chủ). Xem Chế độ Elevated.

# Chế độ

agents.defaults.sandbox.mode kiểm soát khi nào hộp cát được dùng:

# Phạm vi

agents.defaults.sandbox.scope kiểm soát số lượng container được tạo:

• "agent" (mặc định): một container cho mỗi agent.
• "session": một container cho mỗi phiên.
• "shared": một container được chia sẻ bởi tất cả các phiên trong hộp cát.

# Backend

agents.defaults.sandbox.backend kiểm soát runtime nào cung cấp hộp cát:

• "docker" (mặc định khi bật hộp cát): runtime hộp cát cục bộ dựa trên Docker.
• "ssh": runtime hộp cát từ xa chung dựa trên SSH.
• "openshell": runtime hộp cát dựa trên OpenShell.

Cấu hình dành riêng cho SSH nằm dưới agents.defaults.sandbox.ssh. Cấu hình dành riêng cho OpenShell nằm dưới plugins.entries.openshell.config.

# Chọn backend

# Backend Docker

Hộp cát được tắt theo mặc định. Nếu bạn bật hộp cát và không chọn backend, OpenClaw dùng backend Docker. Nó thực thi công cụ và trình duyệt hộp cát cục bộ qua socket daemon Docker (/var/run/docker.sock). Mức cô lập container hộp cát được xác định bởi namespace của Docker.

Để đưa GPU của máy chủ vào các hộp cát Docker, đặt agents.defaults.sandbox.docker.gpus hoặc override theo từng agent agents.list[].sandbox.docker.gpus. Giá trị được truyền tới cờ --gpus của Docker dưới dạng một đối số riêng, ví dụ "all" hoặc "device=GPU-uuid", và yêu cầu runtime máy chủ tương thích như NVIDIA Container Toolkit.

# Backend SSH

Dùng backend: "ssh" khi bạn muốn OpenClaw đưa exec, công cụ tệp và lượt đọc media vào hộp cát trên một máy bất kỳ có thể truy cập qua SSH.

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "ssh",
        scope: "session",
        workspaceAccess: "rw",
        ssh: {
          target: "user@gateway-host:22",
          workspaceRoot: "/tmp/openclaw-sandboxes",
          strictHostKeyChecking: true,
          updateHostKeys: true,
          identityFile: "~/.ssh/id_ed25519",
          certificateFile: "~/.ssh/id_ed25519-cert.pub",
          knownHostsFile: "~/.ssh/known_hosts",
          // Or use SecretRefs / inline contents instead of local files:
          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
        },
      },
    },
  },
}

# Backend OpenShell

Dùng backend: "openshell" khi bạn muốn OpenClaw đưa công cụ vào hộp cát trong một môi trường từ xa do OpenShell quản lý. Để xem hướng dẫn thiết lập đầy đủ, tham chiếu cấu hình và so sánh chế độ workspace, xem trang OpenShell chuyên dụng.

OpenShell dùng lại cùng lõi truyền tải SSH và bridge hệ thống tệp từ xa như backend SSH chung, đồng thời thêm vòng đời dành riêng cho OpenShell (sandbox create/get/delete, sandbox ssh-config) cùng chế độ workspace mirror tùy chọn.

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "session",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote", // mirror | remote
          remoteWorkspaceDir: "/sandbox",
          remoteAgentWorkspaceDir: "/agent",
        },
      },
    },
  },
}

Chế độ OpenShell:

• mirror (mặc định): workspace cục bộ vẫn là canonical. OpenClaw đồng bộ tệp cục bộ vào OpenShell trước khi exec và đồng bộ workspace từ xa trở lại sau khi exec.
• remote: workspace OpenShell là canonical sau khi hộp cát được tạo. OpenClaw seed workspace từ xa một lần từ workspace cục bộ, sau đó công cụ tệp và exec chạy trực tiếp trên hộp cát từ xa mà không đồng bộ thay đổi trở lại.

# Chế độ workspace

OpenShell có hai mô hình workspace. Đây là phần quan trọng nhất trong thực tế.

Chọn mirror nếu bạn xem môi trường cô lập là môi trường thực thi tạm thời. Chọn remote nếu bạn xem môi trường cô lập là workspace thật.

# Vòng đời OpenShell

Môi trường cô lập OpenShell vẫn được quản lý thông qua vòng đời môi trường cô lập thông thường:

• openclaw sandbox list hiển thị runtime OpenShell cũng như runtime Docker
• openclaw sandbox recreate xóa runtime hiện tại và cho phép OpenClaw tạo lại ở lần dùng tiếp theo
• logic prune cũng nhận biết backend

Đối với chế độ remote, recreate đặc biệt quan trọng:

• recreate xóa workspace từ xa chính quy cho scope đó
• lần dùng tiếp theo seed một workspace từ xa mới từ workspace cục bộ

Đối với chế độ mirror, recreate chủ yếu đặt lại môi trường thực thi từ xa vì dù sao workspace cục bộ vẫn là nguồn chính quy.

# Quyền truy cập workspace

agents.defaults.sandbox.workspaceAccess kiểm soát môi trường cô lập có thể thấy gì:

Với backend OpenShell:

• chế độ mirror vẫn dùng workspace cục bộ làm nguồn chính quy giữa các lượt exec
• chế độ remote dùng workspace OpenShell từ xa làm nguồn chính quy sau lần seed ban đầu
• workspaceAccess: "ro" và "none" vẫn hạn chế hành vi ghi theo cùng cách

Media đi vào được sao chép vào workspace môi trường cô lập đang hoạt động (media/inbound/*).

# Bind mount tùy chỉnh

agents.defaults.sandbox.docker.binds gắn thêm các thư mục máy chủ vào container. Định dạng: host:container:mode (ví dụ: "/home/user/source:/source:rw").

Bind toàn cục và theo từng agent được gộp (không thay thế). Với scope: "shared", bind theo từng agent bị bỏ qua.

agents.defaults.sandbox.browser.binds chỉ gắn thêm các thư mục máy chủ vào container trình duyệt môi trường cô lập.

• Khi được đặt (bao gồm []), nó thay thế agents.defaults.sandbox.docker.binds cho container trình duyệt.
• Khi bị bỏ qua, container trình duyệt dùng dự phòng agents.defaults.sandbox.docker.binds (tương thích ngược).

Ví dụ (nguồn chỉ đọc + một thư mục dữ liệu bổ sung):

{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          binds: ["/home/user/source:/source:ro", "/var/data/myapp:/data:ro"],
        },
      },
    },
    list: [
      {
        id: "build",
        sandbox: {
          docker: {
            binds: ["/mnt/cache:/cache:rw"],
          },
        },
      },
    ],
  },
}

# Image và thiết lập

Image Docker mặc định: openclaw-sandbox:bookworm-slim

scripts/sandbox-setup.sh

docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'
FROM debian:bookworm-slim
ENV DEBIAN_FRONTEND=noninteractive
RUN apt-get update && apt-get install -y --no-install-recommends \
  bash ca-certificates curl git jq python3 ripgrep \
  && rm -rf /var/lib/apt/lists/*
RUN useradd --create-home --shell /bin/bash sandbox
USER sandbox
WORKDIR /home/sandbox
CMD ["sleep", "infinity"]
DOCKERFILE

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

Theo mặc định, container môi trường cô lập Docker chạy với không có mạng. Ghi đè bằng agents.defaults.sandbox.docker.network.

Các bản cài Docker và gateway chạy trong container nằm ở đây: Docker

Đối với triển khai gateway Docker, scripts/docker/setup.sh có thể bootstrap cấu hình môi trường cô lập. Đặt OPENCLAW_SANDBOX=1 (hoặc true/yes/on) để bật đường dẫn đó. Bạn có thể ghi đè vị trí socket bằng OPENCLAW_DOCKER_SOCKET. Thiết lập đầy đủ và tham chiếu env: Docker.

# setupCommand (thiết lập container một lần)

setupCommand chạy một lần sau khi container môi trường cô lập được tạo (không phải mỗi lần chạy). Nó thực thi bên trong container qua sh -lc.

Đường dẫn:

• Toàn cục: agents.defaults.sandbox.docker.setupCommand
• Theo từng agent: agents.list[].sandbox.docker.setupCommand

# Chính sách công cụ và lối thoát

Chính sách cho phép/từ chối công cụ vẫn được áp dụng trước các quy tắc sandbox. Nếu một công cụ bị từ chối trên toàn cục hoặc theo từng agent, sandboxing sẽ không khôi phục công cụ đó.

tools.elevated là một lối thoát tường minh chạy exec bên ngoài sandbox (gateway theo mặc định, hoặc node khi mục tiêu exec là node). Các chỉ thị /exec chỉ áp dụng cho người gửi được ủy quyền và tồn tại theo từng phiên; để tắt cứng exec, hãy dùng chính sách từ chối công cụ (xem Sandbox so với Chính sách công cụ so với Elevated).

Gỡ lỗi:

• Dùng openclaw sandbox explain để kiểm tra chế độ sandbox hiệu lực, chính sách công cụ và các khóa cấu hình khắc phục.
• Xem Sandbox so với Chính sách công cụ so với Elevated để hiểu mô hình tư duy "tại sao phần này bị chặn?".

Hãy giữ nó được khóa chặt.

# Ghi đè đa agent

Mỗi agent có thể ghi đè sandbox + công cụ: agents.list[].sandbox và agents.list[].tools (cộng với agents.list[].tools.sandbox.tools cho chính sách công cụ sandbox). Xem Sandbox & Công cụ đa agent để biết thứ tự ưu tiên.

# Ví dụ bật tối thiểu

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
      },
    },
  },
}

# Liên quan

• Sandbox & Công cụ đa agent — ghi đè theo từng agent và thứ tự ưu tiên
• OpenShell — thiết lập backend sandbox được quản lý, chế độ workspace và tham chiếu cấu hình
• Cấu hình sandbox
• Sandbox so với Chính sách công cụ so với Elevated — gỡ lỗi "tại sao phần này bị chặn?"
• Bảo mật