Cơ chế sandbox

OpenClaw có thể chạy công cụ bên trong các phần phụ trợ môi trường cách ly để giảm phạm vi ảnh hưởng. Đây là tính năng 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 cách ly, 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 môi trường cách ly riêng khi được bật.

Những gì được cách ly

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

Không được cách ly:

• 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 môi trường cách ly (ví dụ tools.elevated).
  • Exec nâng quyền bỏ qua cách ly 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 cách ly, tools.elevated không thay đổi cách thực thi (vốn đã ở trên máy chủ). Xem Chế độ nâng quyền.

Chế độ

agents.defaults.sandbox.mode kiểm soát khi nào cách ly được sử 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 tác nhân.
• "session": một container cho mỗi phiên.
• "shared": một container dùng chung cho tất cả các phiên được cách ly.

Phần phụ trợ

agents.defaults.sandbox.backend kiểm soát runtime nào cung cấp môi trường cách ly:

• "docker" (mặc định khi bật cách ly): runtime môi trường cách ly dựa trên Docker cục bộ.
• "ssh": runtime môi trường cách ly từ xa chung dựa trên SSH.
• "openshell": runtime môi trường cách ly dựa trên OpenShell.

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

Chọn phần phụ trợ

Phần phụ trợ Docker

Cách ly bị tắt theo mặc định. Nếu bạn bật cách ly và không chọn phần phụ trợ, OpenClaw dùng phần phụ trợ Docker. Nó thực thi công cụ và trình duyệt trong môi trường cách ly cục bộ thông qua socket daemon Docker (/var/run/docker.sock). Mức cách ly của container môi trường cách ly do namespace Docker quyết định.

Để cho môi trường cách ly Docker truy cập GPU trên máy chủ, đặt agents.defaults.sandbox.docker.gpus hoặc ghi đè theo từng tác nhân bằng agents.list[].sandbox.docker.gpus. Giá trị được truyền vào cờ --gpus của Docker dưới dạng đố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.

Phần phụ trợ SSH

Dùng backend: "ssh" khi bạn muốn OpenClaw cách ly exec, công cụ tệp và đọc phương tiện 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" },        },      },    },  },}

Phần phụ trợ OpenShell

Dùng backend: "openshell" khi bạn muốn OpenClaw cách ly công cụ 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 riêng.

OpenShell tái sử dụng cùng lõi truyền tải SSH và cầu nối hệ thống tệp từ xa như phần phụ trợ SSH chung, đồng thời thêm vòng đời riêng của 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à chuẩn. 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à chuẩn sau khi môi trường cách ly được tạo. OpenClaw gieo 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 môi trường cách ly 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 sandbox là môi trường thực thi tạm thời. Chọn remote nếu bạn xem sandbox là workspace thật.

Vòng đời OpenShell

Sandbox OpenShell vẫn được quản lý thông qua vòng đời sandbox 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à để OpenClaw tạo lại nó trong lần dùng tiếp theo
• logic dọn dẹp cũng nhận biết backend

Với chế độ remote, việc tạo lại đặc biệt quan trọng:

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

Với chế độ mirror, việc tạo lại 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à chuẩn chính.

Truy cập workspace

agents.defaults.sandbox.workspaceAccess kiểm soát sandbox có thể thấy gì:

Với backend OpenShell:

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

Media đến được sao chép vào workspace sandbox đang hoạt động (media/inbound/*).

Mount bind 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 hợp nhất (không thay thế). Dướ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 sandbox.

• 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 lại 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-slimENV DEBIAN_FRONTEND=noninteractiveRUN 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 sandboxUSER sandboxWORKDIR /home/sandboxCMD ["sleep", "infinity"]DOCKERFILE

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

Theo mặc định, container sandbox 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 tại đây: Docker

Với triển khai Gateway Docker, scripts/docker/setup.sh có thể bootstrap cấu hình sandbox. Đặ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 sandbox đượ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 môi trường cô lập. Nếu một công cụ bị từ chối trên toàn cục hoặc theo từng agent, môi trường cô lập sẽ không khôi phục công cụ đó.

tools.elevated là một lối thoát rõ ràng chạy exec bên ngoài môi trường cô lập (gateway theo mặc định, hoặc node khi mục tiêu thực thi là node). Chỉ thị /exec chỉ áp dụng cho người gửi được ủy quyền và được duy trì theo từng phiên; để vô hiệu hóa cứng exec, hãy dùng chính sách từ chối công cụ (xem Môi trường cô lập so với Chính sách công cụ so với Quyền nâng cao).

Gỡ lỗi:

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

Giữ chặt cấu hình bảo vệ.

Ghi đè đa agent

Mỗi agent có thể ghi đè môi trường cô lập + 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ụ trong môi trường cô lập). Xem Môi trường cô lập & 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

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