Cô lập trong sandbox

​

Những gì được sandbox

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

• 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 sandbox (ví dụ tools.elevated).
  • Elevated exec bỏ qua sandboxing và dùng đường thoát đã cấu hình (gateway theo mặc định, hoặc node khi mục tiêu exec là node).
  • Nếu sandboxing tắt, tools.elevated không thay đổi cách thực thi (đã ở trên host). Xem Chế độ Elevated.

​

Chế độ

​

Phạm vi

• "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ả phiên được sandbox.

​

Backend

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

​

Chọn backend

​

Backend Docker

​

Backend 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

{
  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",
        },
      },
    },
  },
}

• 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 exec và đồng bộ workspace từ xa trở lại sau exec.
• remote: workspace OpenShell là canonical sau khi sandbox đượ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 sandbox từ xa mà không đồng bộ thay đổi trở lại.

​

Chế độ workspace

​

Vòng đời OpenShell

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

• tạo lại sẽ xóa workspace từ xa chuẩn cho phạm vi đó
• lần dùng tiếp theo gieo một workspace từ xa mới từ workspace cục bộ

​

Truy cập workspace

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

​

Bind mount tùy chỉnh

• 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).

{
  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"],
          },
        },
      },
    ],
  },
}

​

Hình ảnh và thiết lập

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

​

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

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

​

Chính sách công cụ và cơ chế thoát

• Dùng openclaw sandbox explain để kiểm tra chế độ hộp cát 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 Hộp cát so với Chính sách công cụ so với Đặc quyền nâng cao để hiểu mô hình tư duy “tại sao mục này bị chặn?”.

​

Ghi đè đa tác nhân

​

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

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

​

Liên quan

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