​

Sandboxing

​

Những gì được sandbox

• Thực thi công cụ (exec, read, write, edit, apply_patch, process, v.v.).
• Trình duyệt sandbox tùy chọn (agents.defaults.sandbox.browser).
  • 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.
  • Mặc định, các container trình duyệt sandbox sử dụng một mạng Docker riêng biệt (openclaw-sandbox-browser) thay vì mạng bridge toàn cầu. Cấu hình với agents.defaults.sandbox.browser.network.
  • agents.defaults.sandbox.browser.cdpSourceRange tùy chọn giới hạn CDP ingress ở cạnh container với danh sách cho phép CIDR (ví dụ 172.21.0.1/32).
  • Quyền truy cập noVNC observer được bảo vệ bằng mật khẩu mặc định; OpenClaw phát ra một URL token ngắn hạn phục vụ một trang bootstrap cục bộ và mở noVNC với mật khẩu trong đoạn URL (không phải query/header logs).
  • agents.defaults.sandbox.browser.allowHostControl cho phép các phiên sandbox nhắm mục tiêu trình duyệt host một cách rõ ràng.
  • Danh sách cho phép tùy chọn kiểm soát target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

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

​

Chế độ

• "off": không có sandboxing.
• "non-main": chỉ sandbox các phiên không chính (mặc định nếu bạn muốn các cuộc trò chuyện bình thường trên host).
• "all": mọi phiên đều chạy trong một 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 sử dụng khóa riêng của chúng, vì vậy chúng được tính là không chính 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 được chia sẻ bởi tất cả các phiên sandboxed.

​

Backend

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

​

Chọn backend

​

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",
          // Hoặc sử dụng SecretRefs / nội dung inline thay vì 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" },
        },
      },
    },
  },
}

• OpenClaw tạo một root từ xa theo phạm vi dưới sandbox.ssh.workspaceRoot.
• Lần đầu sử dụng sau khi tạo hoặc tạo lại, OpenClaw seed workspace từ xa đó từ workspace cục bộ một lần.
• Sau đó, exec, read, write, edit, apply_patch, đọc media nhắc nhở, và dàn dựng media inbound chạy trực tiếp chống lại workspace từ xa qua SSH.
• OpenClaw không tự động đồng bộ hóa các thay đổi từ xa trở lại workspace cục bộ.

• identityFile, certificateFile, knownHostsFile: sử dụng các tệp cục bộ hiện có và truyền chúng qua cấu hình OpenSSH.
• identityData, certificateData, knownHostsData: sử dụng chuỗi inline hoặc SecretRefs. OpenClaw giải quyết chúng thông qua snapshot runtime bí mật thông thường, ghi chúng vào tệp tạm thời với 0600, và xóa chúng khi phiên SSH kết thúc.
• Nếu cả *File và *Data đều được đặt cho cùng một mục, *Data sẽ thắng cho phiên SSH đó.

• Các chỉnh sửa cục bộ trên host được thực hiện bên ngoài OpenClaw sau bước seed không được nhìn thấy từ xa cho đến khi bạn tạo lại sandbox.
• openclaw sandbox recreate xóa root từ xa theo phạm vi và seed lại từ cục bộ khi sử dụng lần tiếp theo.
• Trình duyệt sandbox không được hỗ trợ trên backend SSH.
• Các cài đặt sandbox.docker.* không áp dụng cho backend SSH.

​

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à nguồn chính. OpenClaw đồng bộ hóa các tệp cục bộ vào sandbox OpenShell trước khi thực thi và đồng bộ hóa workspace từ xa trở lại sau khi thực thi.
• remote: workspace OpenShell là nguồn chính sau khi sandbox được tạo. OpenClaw seed workspace từ xa một lần từ workspace cục bộ, sau đó các công cụ tệp và thực thi chạy trực tiếp chống lại sandbox từ xa mà không đồng bộ hóa các thay đổi trở lại.

• OpenClaw yêu cầu OpenShell cung cấp cấu hình SSH cụ thể cho sandbox qua openshell sandbox ssh-config <name>.
• Core ghi cấu hình SSH đó vào một tệp tạm thời, mở phiên SSH, và tái sử dụng cùng cầu nối hệ thống tệp từ xa được sử dụng bởi backend: "ssh".
• Chỉ trong chế độ mirror, vòng đời khác biệt: đồng bộ hóa cục bộ với từ xa trước khi thực thi, sau đó đồng bộ hóa trở lại sau khi thực thi.

• Trình duyệt sandbox chưa được hỗ trợ
• sandbox.docker.binds không được hỗ trợ trên backend OpenShell
• Các nút runtime cụ thể của Docker dưới sandbox.docker.* vẫn chỉ áp dụng cho backend Docker

​

Các chế độ workspace

mirror

• Trước khi exec, OpenClaw đồng bộ hóa workspace cục bộ vào sandbox OpenShell.
• Sau khi exec, OpenClaw đồng bộ hóa workspace từ xa trở lại workspace cục bộ.
• Các công cụ tệp vẫn hoạt động thông qua cầu nối sandbox, nhưng workspace cục bộ vẫn là nguồn sự thật giữa các lượt.

• bạn chỉnh sửa tệp cục bộ bên ngoài OpenClaw và muốn những thay đổi đó xuất hiện trong sandbox tự động
• bạn muốn sandbox OpenShell hoạt động giống như backend Docker nhất có thể
• bạn muốn workspace host phản ánh các ghi chép sandbox sau mỗi lượt thực thi

• chi phí đồng bộ hóa bổ sung trước và sau khi thực thi

remote

• Khi sandbox được tạo lần đầu, OpenClaw seed workspace từ xa từ workspace cục bộ một lần.
• Sau đó, exec, read, write, edit, và apply_patch hoạt động trực tiếp chống lại workspace OpenShell từ xa.
• OpenClaw không đồng bộ hóa các thay đổi từ xa trở lại workspace cục bộ sau khi thực thi.
• Đọc media nhắc nhở vẫn hoạt động vì các công cụ tệp và media đọc thông qua cầu nối sandbox thay vì giả định một đường dẫn host cục bộ.
• Truyền tải là SSH vào sandbox OpenShell được trả về bởi openshell sandbox ssh-config.

• Nếu bạn chỉnh sửa tệp trên host bên ngoài OpenClaw sau bước seed, sandbox từ xa sẽ không thấy những thay đổi đó tự động.
• Nếu sandbox được tạo lại, workspace từ xa được seed lại từ workspace cục bộ.
• Với scope: "agent" hoặc scope: "shared", workspace từ xa đó được chia sẻ ở cùng phạm vi đó.

• sandbox nên sống chủ yếu ở phía OpenShell từ xa
• bạn muốn giảm chi phí đồng bộ hóa mỗi lượt
• bạn không muốn các chỉnh sửa cục bộ trên host ghi đè trạng thái sandbox từ xa một cách âm thầm

​

Vòng đời OpenShell

• openclaw sandbox list hiển thị cả runtime OpenShell và runtime Docker
• openclaw sandbox recreate xóa runtime hiện tại và cho phép OpenClaw tạo lại nó khi sử dụng lần tiếp theo
• logic prune cũng nhận biết backend

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

​

Quyền truy cập workspace

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

• chế độ mirror vẫn sử dụng workspace cục bộ làm nguồn chính giữa các lượt thực thi
• chế độ remote sử dụng workspace OpenShell từ xa làm nguồn chính sau seed ban đầu
• workspaceAccess: "ro" và "none" vẫn hạn chế hành vi ghi chép theo cùng cách

​

Bind mounts 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 quay lại 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"],
          },
        },
      },
    ],
  },
}

• Bind bỏ qua hệ thống tệp sandbox: chúng lộ ra các đường dẫn host với bất kỳ chế độ nào bạn đặt (:ro hoặc :rw).
• OpenClaw chặn các nguồn bind nguy hiểm (ví dụ: docker.sock, /etc, /proc, /sys, /dev, và các mount cha mẹ sẽ lộ ra chúng).
• Các mount nhạy cảm (bí mật, khóa SSH, thông tin xác thực dịch vụ) nên là :ro trừ khi thực sự cần thiết.
• Kết hợp với workspaceAccess: "ro" nếu bạn chỉ cần quyền đọc truy cập vào 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 công cụ và thực thi nâng cao.

​

Hình ảnh + thiết lập

scripts/sandbox-setup.sh

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

• --remote-debugging-address=127.0.0.1
• --remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>
• --user-data-dir=${HOME}/.chrome
• --no-first-run
• --no-default-browser-check
• --disable-3d-apis
• --disable-gpu
• --disable-dev-shm-usage
• --disable-background-networking
• --disable-extensions
• --disable-features=TranslateUI
• --disable-breakpad
• --disable-crash-reporter
• --disable-software-rasterizer
• --no-zygote
• --metrics-recording-only
• --renderer-process-limit=2
• --no-sandbox và --disable-setuid-sandbox khi noSandbox được bật.
• Ba cờ bảo vệ đồ họa (--disable-3d-apis, --disable-software-rasterizer, --disable-gpu) là tùy chọn và hữu ích khi container thiếu hỗ trợ GPU. Đặt OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 nếu khối lượng công việc của bạn yêu cầu WebGL hoặc các tính năng 3D/trình duyệt khác.
• --disable-extensions được bật mặc định và có thể bị vô hiệu hóa với OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 cho các luồng phụ thuộc vào tiện ích mở rộng.
• --renderer-process-limit=2 được kiểm soát bởi OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>, nơi 0 giữ mặc định của Chromium.

• network: "host" bị chặn.
• network: "container:<id>" bị chặn mặc định (rủi ro bỏ qua namespace join).
• Ghi đè khẩn cấp: agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true.

​

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

• Toàn cầu: agents.defaults.sandbox.docker.setupCommand
• Theo agent: agents.list[].sandbox.docker.setupCommand

• Mặc định docker.network là "none" (không có egress), vì vậy cài đặt gói sẽ thất bại.
• docker.network: "container:<id>" yêu cầu dangerouslyAllowContainerNamespaceJoin: true và chỉ là ghi đè khẩn cấp.
• readOnlyRoot: true ngăn chặn ghi; đặt readOnlyRoot: false hoặc tạo một hình ảnh tùy chỉnh.
• user phải là root để cài đặt gói (bỏ qua user hoặc đặt user: "0:0").
• Thực thi sandbox không kế thừa process.env của host. Sử dụng agents.defaults.sandbox.docker.env (hoặc một hình ảnh tùy chỉnh) cho các khóa API kỹ năng.

​

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

• Sử dụng openclaw sandbox explain để kiểm tra chế độ sandbox hiệu quả, chính sách công cụ, và các khóa cấu hình sửa chữa.
• Xem Sandbox vs Tool Policy vs Elevated để có mô hình tư duy “tại sao điều này bị chặn?”. Giữ nó bị khóa.

​

Ghi đè nhiều agent

​

Ví dụ kích hoạt tối thiểu

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

​

Tài liệu liên quan

• OpenShell — thiết lập backend sandbox được quản lý, chế độ workspace, và tham khảo cấu hình
• Sandbox Configuration
• Sandbox vs Tool Policy vs Elevated — gỡ lỗi “tại sao điều này bị chặn?”
• Multi-Agent Sandbox & Tools — ghi đè theo agent và thứ tự ưu tiên
• Security