Cơ chế hộp cát

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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).

• Bản thân 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 sandbox (ví dụ tools.elevated).
  • Exec nâng quyền bỏ qua sandbox và dùng đường thoát đã cấu hình (gateway theo mặc định, hoặc node khi mục tiêu exec là node).
  • Nếu sandbox bị tắt, tools.elevated không thay đổi cách thực thi (vì đã ở trên host). Xem Chế độ nâng quyền.

​

Chế độ

​

Phạm vi

• "agent" (mặc định): một container cho mỗi agent.
• "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 sandbox.

​

Backend

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

​

Chọn backend

​

Backend Docker

​

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",
          // 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" },
        },
      },
    },
  },
}

​

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à chuẩn. OpenClaw đồng bộ các tệp cục bộ vào OpenShell trước exec và đồng bộ workspace từ xa trở lại sau exec.
• remote: workspace OpenShell là chuẩn 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à exec chạy trực tiếp trên sandbox từ xa mà không đồng bộ thay đổi trở lại.

​

Chế độ workspace

​

Vòng đời OpenShell

• openclaw sandbox list hiển thị runtime OpenShell cũng như runtime Docker
• openclaw sandbox recreate xóa runtime hiện tại và cho phép OpenClaw tạo lại trong lần dùng tiếp theo
• logic dọn dẹp cũng nhận biết phần phụ trợ

• tạo lại sẽ xóa không gian làm việc từ xa chính thức cho phạm vi đó
• lần dùng tiếp theo gieo một không gian làm việc từ xa mới từ không gian làm việc cục bộ

​

Truy cập không gian làm việc

• chế độ mirror vẫn dùng không gian làm việc cục bộ làm nguồn chính thức giữa các lượt thực thi
• chế độ remote dùng không gian làm việc OpenShell từ xa làm nguồn chính thức sau bước gieo ban đầu
• workspaceAccess: "ro" và "none" vẫn hạn chế hành vi ghi theo cùng cách

​

Gắn kết bind 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 dùng dự phòng 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"],
          },
        },
      },
    ],
  },
}

​

Hình ảnh và thiết lập

scripts/sandbox-setup.sh

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

​

setupCommand (thiết lập container một lầ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à lối thoát

• 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 sửa lỗi.
• Xem Môi trường cô lập so với chính sách công cụ so với nâng quyền để có mô hình tư duy “vì sao điều này bị chặn?”.

​

Ghi đè đa tác tử

​

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