​

Cô lập (Sandboxing)

​

Những gì được sandbox

• Thực thi tool (exec, read, write, edit, apply_patch, process, v.v.).
• Trình duyệt sandbox tùy chọn (agents.defaults.sandbox.browser).
  • Theo mặc định, trình duyệt sandbox tự động khởi động (đảm bảo CDP có thể truy cập) khi công cụ trình duyệt cần. Cấu hình qua agents.defaults.sandbox.browser.autoStart và agents.defaults.sandbox.browser.autoStartTimeoutMs.
  • agents.defaults.sandbox.browser.allowHostControl cho phép các phiên sandbox nhắm trực tiếp tới trình duyệt trên host.
  • Các allowlist tùy chọn kiểm soát target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

• Chính tiến trình Gateway.
• Bất kỳ tool nào được cho phép chạy trên host một cách rõ ràng (ví dụ: tools.elevated).
  • Thực thi nâng quyền chạy trên host và bỏ qua sandboxing.
  • Nếu tắt sandboxing, tools.elevated không thay đổi việc thực thi (đã chạy trên máy chủ). Xem Elevated Mode.

​

Chế độ

• "off": không sandboxing.
• "non-main": chỉ sandbox các phiên không phải main (mặc định nếu bạn muốn các cuộc chat bình thường chạy trên host).
• "all": mọi phiên đều chạy trong sandbox. Lưu ý: "non-main" dựa trên session.mainKey (mặc định "main"), không phải id agent. Các phiên nhóm/kênh dùng khóa riêng của chúng, nên được tính là non-main và sẽ được sandbox.

​

Phạm vi

• "session" (mặc định): một container cho mỗi phiên.
• "agent": một container cho mỗi agent.
• "shared": một container dùng chung cho tất cả các phiên sandbox.

​

Quyền truy cập workspace

• "none" (mặc định): các tool thấy một workspace sandbox dưới ~/.openclaw/sandboxes.
• "ro": gắn workspace của agent ở chế độ chỉ đọc tại /agent (vô hiệu hóa write/edit/apply_patch).
• "rw": gắn workspace của agent ở chế độ đọc/ghi tại /workspace.

​

Gắn bind tùy chỉnh

• Khi được thiết lập (bao gồm cả []), nó sẽ thay thế agents.defaults.sandbox.docker.binds cho container trình duyệt.
• Khi không được thiết lập, container trình duyệt sẽ dùng lại agents.defaults.sandbox.docker.binds (tương thích ngược).

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

• Các bind bỏ qua hệ thống tệp sandbox: chúng phơi bày đường dẫn trên host với chế độ bạn đặt (:ro hoặc :rw).
• Các mount nhạy cảm (ví dụ: docker.sock, secrets, khóa SSH) nên để :ro trừ khi thực sự cần.
• Kết hợp với workspaceAccess: "ro" nếu bạn chỉ cần quyền đọc workspace; chế độ bind vẫn độc lập.
• Xem Sandbox vs Tool Policy vs Elevated để biết cách bind tương tác với chính sách tool và thực thi nâng quyền.

​

Image + thiết lập

scripts/sandbox-setup.sh

scripts/sandbox-browser-setup.sh

​

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

• docker.network mặc định là "none" (không egress), nên cài gói sẽ thất bại.
• readOnlyRoot: true chặn ghi; đặt readOnlyRoot: false hoặc bake image tùy chỉnh.

• docker.network mặc định là "none" (không egress), nên cài gói sẽ thất bại.
• readOnlyRoot: true chặn ghi; đặt readOnlyRoot: false hoặc bake image tùy chỉnh.
• user phải là root để cài gói (bỏ user hoặc đặt user: "0:0").
• Sandbox exec không kế thừa process.env của máy chủ. Sử dụng agents.defaults.sandbox.docker.env (hoặc một image tùy chỉnh) cho các khóa API của skill.

​

Chính sách tool + lối thoát

• Dùng openclaw sandbox explain để kiểm tra chế độ sandbox hiệu lực, chính sách tool và các khóa cấu hình gợi ý sửa.
• Xem Sandbox vs Tool Policy vs Elevated để có mô hình tư duy “vì sao cái này bị chặn?”. Hãy khóa chặt.

​

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

​

Tài liệu liên quan

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

​

Tài liệu liên quan

• Sandbox Configuration
• Multi-Agent Sandbox & Tools
• Security