Sandboxing

OpenClaw có thể chạy các tool bên trong Docker containers để giảm thiểu rủi ro. Tính năng này là tùy chọn và được điều khiển bởi cấu hình (agents.defaults.sandbox hoặc agents.list[].sandbox). Nếu tắt sandboxing, các tool sẽ chạy trực tiếp trên host. Gateway luôn chạy trên host; việc thực thi tool sẽ chạy trong sandbox cô lập khi được bật.

Đây không phải là ranh giới bảo mật hoàn hảo, nhưng nó giúp hạn chế đáng kể quyền truy cập filesystem và process khi model làm điều gì đó sai.

Những gì được sandbox hóa

Thực thi tool (exec, read, write, edit, apply_patch, process, v.v.).
Browser được sandbox hóa tùy chọn (agents.defaults.sandbox.browser).
- Mặc định, sandbox browser tự động khởi động (đảm bảo CDP có thể truy cập được) khi browser tool cần dùng. 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 session được sandbox hóa truy cập browser trên host một cách rõ ràng.
- Các allowlist tùy chọn kiểm soát target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

Không được sandbox hóa:

Tiến trình Gateway.
Bất kỳ tool nào được phép chạy trên host một cách rõ ràng (ví dụ tools.elevated).
- Elevated exec chạy trên host và bỏ qua sandboxing.
- Nếu sandboxing bị tắt, tools.elevated không thay đổi cách thực thi (đã chạy trên host). Xem Elevated Mode.

Các chế độ (Modes)

agents.defaults.sandbox.mode kiểm soát khi nào sandboxing được sử dụng:

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

Phạm vi (Scope)

agents.defaults.sandbox.scope kiểm soát bao nhiêu container được tạo:

"session" (mặc định): một container cho mỗi session.
"agent": một container cho mỗi agent.
"shared": một container được chia sẻ bởi tất cả các session được sandbox hóa.

Quyền truy cập Workspace

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

"none" (mặc định): các tool thấy một sandbox workspace dưới ~/.openclaw/sandboxes.
"ro": mount agent workspace ở chế độ read-only tại /agent (vô hiệu hóa write/edit/apply_patch).
"rw": mount agent workspace ở chế độ read/write tại /workspace.

Media đầu vào được copy vào sandbox workspace đang hoạt động (media/inbound/*). Lưu ý về Skills: tool read được root hóa trong sandbox. Với workspaceAccess: "none", OpenClaw sẽ mirror các skill đủ điều kiện vào sandbox workspace (.../skills) để chúng có thể được đọc. Với "rw", workspace skills có thể đọc được từ /workspace/skills.

Custom bind mounts

agents.defaults.sandbox.docker.binds mount các thư mục host bổ sung vào container. Định dạng: host:container:mode (ví dụ: "/home/user/source:/source:rw").

Các bind global và per-agent được merge (không thay thế). Với scope: "shared", các bind per-agent bị bỏ qua.

Ví dụ (source read-only + docker socket):

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

Lưu ý bảo mật:

Binds bỏ qua filesystem của sandbox: chúng expose các đường dẫn host với bất kỳ mode nào các bạn đặt (:ro hoặc :rw).
Các mount nhạy cảm (ví dụ: docker.sock, secrets, SSH keys) nên dùng :ro trừ khi thực sự cần thiết.
Kết hợp với workspaceAccess: "ro" nếu các bạn chỉ cần quyền đọc workspace; các bind mode vẫn độc lập.
Xem Sandbox vs Tool Policy vs Elevated để hiểu cách binds tương tác với tool policy và elevated exec.

Images + setup

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

Build một lần:

scripts/sandbox-setup.sh

Lưu ý: image mặc định không bao gồm Node. Nếu một skill cần Node (hoặc các runtime khác), các bạn có thể tự build custom image hoặc cài đặt qua sandbox.docker.setupCommand (yêu cầu network egress + writable root + root user).

Sandboxed browser image:

scripts/sandbox-browser-setup.sh

Mặc định, các sandbox container chạy với không có network. Override bằng agents.defaults.sandbox.docker.network.

Cài đặt Docker và containerized gateway ở đây: Docker

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

setupCommand chạy một lần sau khi sandbox container đượ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:

Global: agents.defaults.sandbox.docker.setupCommand
Per-agent: agents.list[].sandbox.docker.setupCommand

Các lỗi thường gặp:

docker.network mặc định là "none" (không có egress), nên việc cài package sẽ thất bại.
readOnlyRoot: true ngăn ghi; đặt readOnlyRoot: false hoặc build custom image.
user phải là root để cài package (bỏ qua user hoặc đặt user: "0:0").
Sandbox exec không kế thừa process.env của host. Dùng agents.defaults.sandbox.docker.env (hoặc custom image) cho các API key của skill.

Tool policy + escape hatches

Các policy allow/deny của tool vẫn áp dụng trước các quy tắc sandbox. Nếu một tool bị deny globally hoặc per-agent, sandboxing không thể đưa nó trở lại.

tools.elevated là một escape hatch rõ ràng để chạy exec trên host. Các directive /exec chỉ áp dụng cho người gửi được ủy quyền và tồn tại theo session; để vô hiệu hóa hoàn toàn exec, dùng tool policy deny (xem Sandbox vs Tool Policy vs Elevated).

Debugging:

Dùng openclaw sandbox explain để kiểm tra sandbox mode hiệu quả, tool policy và các config key fix-it.
Xem Sandbox vs Tool Policy vs Elevated để hiểu mô hình “tại sao bị chặn?”. Giữ nó khóa chặt nhé.

Multi-agent overrides

Mỗi agent có thể override sandbox + tools: agents.list[].sandbox và agents.list[].tools (cộng với agents.list[].tools.sandbox.tools cho sandbox tool policy). Xem Multi-Agent Sandbox & Tools để hiểu thứ tự ưu tiên.

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

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