Cô lập môi trường

OpenClaw có thể chạy việc thực thi công cụ bên trong một backend hộp cát để giảm phạm vi ảnh hưởng. Hộp cát mặc định bị tắt và được điều khiển bởi agents.defaults.sandbox (toàn cục) hoặc agents.list[].sandbox (theo từng tác nhân). Tiến trình Gateway luôn ở trên máy chủ; chỉ việc thực thi công cụ được chuyển vào hộp cát khi tính năng này được bật.

Những gì được chạy trong hộp cát

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

Không được chạy trong hộp cát:

• Bản thân tiến trình Gateway.
• Mọi công cụ được cho phép rõ ràng chạy bên ngoài hộp cát thông qua tools.elevated. Lệnh exec đặc quyền bỏ qua hộp cát và chạy trên đường thoát đã cấu hình (mặc định là gateway, hoặc node khi đích exec là node). Nếu hộp cát bị tắt, tools.elevated không thay đổi gì vì exec vốn đã chạy trên máy chủ. Xem Chế độ đặc quyền.

Chế độ, phạm vi và backend

Ba thiết lập độc lập kiểm soát hành vi của hộp cát:

Chế độ kiểm soát thời điểm áp dụng hộp cát:

• off: không dùng hộp cát.
• non-main: chạy mọi phiên trong hộp cát, ngoại trừ phiên chính của tác nhân. Khóa phiên chính luôn là agent:<agentId>:main (hoặc global khi session.scope là "global"); không thể cấu hình khóa này. Các phiên nhóm/kênh sử dụng khóa riêng, vì vậy chúng luôn được coi là không chính và được chạy trong hộp cát.
• all: mọi phiên đều chạy trong hộp cát.

Phạm vi kiểm soát số lượng vùng chứa/môi trường được tạo:

• agent: một vùng chứa cho mỗi tác nhân.
• session: một vùng chứa cho mỗi phiên.
• shared: một vùng chứa dùng chung cho tất cả các phiên chạy trong hộp cát (các giá trị ghi đè docker/ssh/browser theo từng tác nhân bị bỏ qua trong phạm vi này).

Backend kiểm soát môi trường thực thi nào chạy các công cụ trong hộp cát. Cấu hình dành riêng cho SSH nằm trong agents.defaults.sandbox.ssh; cấu hình dành riêng cho OpenShell nằm trong plugins.entries.openshell.config.

Backend Docker

Docker là backend mặc định sau khi bật hộp cát. Backend này chạy các công cụ và trình duyệt hộp cát cục bộ thông qua socket trình nền Docker (/var/run/docker.sock); khả năng cách ly đến từ các không gian tên Docker.

Giá trị mặc định: network: "none" (không có lưu lượng đi ra), readOnlyRoot: true, capDrop: ["ALL"], image openclaw-sandbox:bookworm-slim.

Để cung cấp GPU của máy chủ, hãy đặt agents.defaults.sandbox.docker.gpus (hoặc giá trị ghi đè theo từng tác nhân) thành một giá trị như "all" hoặc "device=GPU-uuid". Giá trị này được truyền cho cờ --gpus của Docker và yêu cầu một môi trường thực thi máy chủ tương thích, chẳng hạn như NVIDIA Container Toolkit.

Trình duyệt hộp cát

• Trình duyệt hộp cát tự động khởi động (đảm bảo có thể truy cập CDP) khi công cụ trình duyệt cần đến. Cấu hình thông qua agents.defaults.sandbox.browser.autoStart (mặc định là true) và autoStartTimeoutMs (mặc định là 12 giây).
• Các vùng chứa trình duyệt hộp cát sử dụng một mạng Docker chuyên dụng (openclaw-sandbox-browser) thay cho mạng bridge toàn cục. Cấu hình bằng agents.defaults.sandbox.browser.network.
• agents.defaults.sandbox.browser.cdpSourceRange giới hạn lưu lượng CDP đi vào ở biên vùng chứa bằng danh sách CIDR cho phép (ví dụ: 172.21.0.1/32).
• Quyền truy cập quan sát noVNC được bảo vệ bằng mật khẩu theo mặc định; OpenClaw phát hành một URL mã thông báo tồn tại trong thời gian ngắn, phục vụ một trang khởi động cục bộ và mở noVNC với mật khẩu trong phần phân mảnh URL (không nằm trong chuỗi truy vấn hoặc nhật ký tiêu đề).
• agents.defaults.sandbox.browser.allowHostControl (mặc định là false) cho phép các phiên trong hộp cát nhắm rõ ràng đến trình duyệt của máy chủ.
• Các danh sách cho phép tùy chọn kiểm soát target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

Backend SSH

Sử dụng backend: "ssh" để chạy exec, các công cụ tệp và thao tác đọc phương tiện trong 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",          // Hoặc sử dụng SecretRefs / nội dung nội tuyến thay cho tệp cục bộ:          // 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" },        },      },    },  },}

Giá trị mặc định: command: "ssh", workspaceRoot: "/tmp/openclaw-sandboxes", strictHostKeyChecking: true, updateHostKeys: true.

• Vòng đời: OpenClaw tạo một thư mục gốc từ xa theo từng phạm vi trong sandbox.ssh.workspaceRoot. Trong lần sử dụng đầu tiên sau khi tạo hoặc tạo lại, nó khởi tạo không gian làm việc từ xa đó một lần từ không gian làm việc cục bộ. Sau đó, exec, read, write, edit, apply_patch, thao tác đọc phương tiện trong lời nhắc và khâu chuẩn bị phương tiện đến sẽ chạy trực tiếp trên không gian làm việc từ xa qua SSH. OpenClaw không tự động đồng bộ các thay đổi từ xa trở lại không gian làm việc cục bộ.
• Dữ liệu xác thực: identityFile/certificateFile/knownHostsFile tham chiếu đến các tệp cục bộ hiện có. identityData/certificateData/knownHostsData chấp nhận chuỗi nội tuyến hoặc SecretRefs, được phân giải thông qua ảnh chụp nhanh môi trường thực thi bí mật thông thường, ghi vào các tệp tạm thời với chế độ 0600 và xóa khi phiên SSH kết thúc. Nếu cả biến thể *File và *Data đều được đặt cho cùng một mục, *Data được ưu tiên trong phiên đó.
• Hệ quả của việc lấy máy từ xa làm chuẩn: không gian làm việc SSH từ xa trở thành trạng thái hộp cát thực tế sau lần khởi tạo ban đầu. Các chỉnh sửa cục bộ trên máy chủ được thực hiện bên ngoài OpenClaw sau bước khởi tạo sẽ không hiển thị từ xa cho đến khi bạn tạo lại hộp cát. openclaw sandbox recreate xóa thư mục gốc từ xa theo từng phạm vi và khởi tạo lại từ cục bộ trong lần sử dụng tiếp theo. Backend này không hỗ trợ hộp cát trình duyệt và các thiết lập sandbox.docker.* không áp dụng cho nó.

Backend OpenShell

Sử dụng backend: "openshell" để chạy các công cụ trong hộp cát thuộc môi trường từ xa do OpenShell quản lý. OpenShell tái sử dụng cùng cơ chế truyền tải SSH và cầu nối hệ thống tệp từ xa như backend SSH chung, đồng thời bổ sung vòng đời OpenShell (sandbox create/get/delete/ssh-config) cùng chế độ đồng bộ không gian làm việc 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        },      },    },  },}

mode: "mirror" (mặc định) giữ không gian làm việc cục bộ làm chuẩn: OpenClaw đồng bộ dữ liệu cục bộ vào hộp cát trước exec và đồng bộ trở lại sau đó. mode: "remote" khởi tạo không gian làm việc từ xa một lần từ cục bộ, sau đó chạy exec/read/write/edit/apply_patch trực tiếp trên không gian làm việc từ xa mà không đồng bộ trở lại; các chỉnh sửa cục bộ sau lần khởi tạo sẽ không hiển thị cho đến khi bạn chạy openclaw sandbox recreate. Với scope: "agent" hoặc scope: "shared", không gian làm việc từ xa đó được dùng chung trong cùng phạm vi. Các hạn chế hiện tại: hộp cát trình duyệt chưa được hỗ trợ và sandbox.docker.binds không áp dụng cho backend này.

openclaw sandbox list/recreate/prune đều xử lý các môi trường thực thi OpenShell giống như môi trường thực thi Docker; logic dọn dẹp nhận biết backend.

Để biết đầy đủ các điều kiện tiên quyết, tài liệu tham chiếu cấu hình, nội dung so sánh các chế độ không gian làm việc và chi tiết vòng đời, hãy xem OpenShell.

Quyền truy cập không gian làm việc

agents.defaults.sandbox.workspaceAccess kiểm soát những gì hộp cát có thể thấy:

Với phần phụ trợ OpenShell, chế độ mirror vẫn sử dụng không gian làm việc cục bộ làm nguồn chuẩn giữa các lượt thực thi, chế độ remote sử dụng không gian làm việc OpenShell từ xa làm nguồn chuẩn sau lần khởi tạo dữ liệu ban đầu, còn workspaceAccess: "ro"/"none" vẫn hạn chế hành vi ghi theo cùng cách.

Phương tiện đầu vào được sao chép vào không gian làm việc sandbox đang hoạt động (media/inbound/*).

Gắn kết 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").

Các gắn kết toàn cục và theo từng tác tử được hợp nhất (không thay thế nhau). Với scope: "shared", các gắn kết theo từng tác tử 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 (kể cả []), giá trị này thay thế docker.binds cho container trình duyệt; khi bị lược bỏ, container trình duyệt dùng docker.binds làm phương án dự phòng.

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

Ảnh và thiết lập

Ảnh 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, các container sandbox Docker chạy không có mạng. Ghi đè bằng agents.defaults.sandbox.docker.network.

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

Đối với các triển khai Gateway bằng Docker, scripts/docker/setup.sh có thể khởi tạo cấu hình sandbox. Đặt OPENCLAW_SANDBOX=1 (hoặc true/yes/on) để bật đường dẫn này. Ghi đè vị trí socket bằng OPENCLAW_DOCKER_SOCKET. Tham chiếu đầy đủ về thiết lập và biến môi trường: 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 chạy ở mỗi lượt). Lệnh này 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 tác tử: agents.list[].sandbox.docker.setupCommand

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

Các 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 toàn cục hoặc theo từng tác tử, việc dùng sandbox không kích hoạt lại công cụ đó.

tools.elevated là một lối thoát tường minh để chạy exec bên ngoài sandbox (mặc định là gateway, hoặc node khi đích thực thi là node). Các 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 hoàn toàn exec, hãy dùng chính sách công cụ để từ chối (xem Sandbox so với chính sách công cụ so với quyền nâng cao).

Gỡ lỗi:

• openclaw sandbox list hiển thị các container sandbox, trạng thái, mức độ khớp ảnh, thời gian tồn tại, thời gian nhàn rỗi và phiên/tác tử liên quan.
• openclaw sandbox explain [--session <key>] [--agent <id>] kiểm tra chế độ sandbox hiệu lực, không gian làm việc máy chủ, thư mục làm việc của môi trường chạy, các điểm gắn kết Docker, chính sách công cụ và các khóa cấu hình khắc phục. Trường workspaceRoot vẫn là thư mục gốc sandbox đã cấu hình; effectiveHostWorkspaceRoot cho biết không gian làm việc đang hoạt động thực sự nằm ở đâu.
• openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force] xóa các container/môi trường để chúng được tạo lại với cấu hình hiện tại trong lần sử dụng tiếp theo.
• Xem Sandbox 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 thao tác này bị chặn?”.

Ghi đè cho nhiều tác tử

Mỗi tác tử có thể ghi đè sandbox + công cụ: agents.list[].sandbox và agents.list[].tools (cộng thêm agents.list[].tools.sandbox.tools cho chính sách công cụ sandbox). Xem Sandbox và công cụ cho nhiều tác tử để 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

• Hộp cát và công cụ đa tác nhân -- các thiết lập ghi đè theo từng tác nhân và thứ tự ưu tiên
• OpenShell -- thiết lập phần phụ trợ hộp cát được quản lý, các chế độ không gian làm việc và tài liệu tham khảo 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 quyền nâng cao -- gỡ lỗi "tại sao thao tác này bị chặn?"
• Bảo mật