Cơ chế sandbox

Documentation Index

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

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

​

Những gì được cách ly

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

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

​

Chế độ

​

Phạm vi

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

​

Phần phụ trợ

• "docker" (mặc định khi bật cách ly): runtime môi trường cách ly dựa trên Docker cục bộ.
• "ssh": runtime môi trường cách ly từ xa chung dựa trên SSH.
• "openshell": runtime môi trường cách ly dựa trên OpenShell.

​

Chọn phần phụ trợ

​

Phần phụ trợ Docker

​

Phần phụ trợ 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" },
        },
      },
    },
  },
}

​

Phần phụ trợ 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ộ tệp cục bộ vào OpenShell trước khi exec và đồng bộ workspace từ xa trở lại sau khi exec.
• remote: workspace OpenShell là chuẩn sau khi môi trường cách ly được tạo. OpenClaw gieo workspace từ xa một lần từ workspace cục bộ, sau đó công cụ tệp và exec chạy trực tiếp trên môi trường cách ly 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à để OpenClaw tạo lại nó trong lần dùng tiếp theo
• logic dọn dẹp cũng nhận biết backend

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

​

Truy cập workspace

• chế độ mirror vẫn dùng workspace cục bộ làm nguồn chuẩn chính giữa các lượt exec
• chế độ remote dùng workspace OpenShell từ xa làm nguồn chuẩn chính sau lần khởi tạo ban đầu
• workspaceAccess: "ro" và "none" vẫn hạn chế hành vi ghi theo cùng cách

​

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

​

Image và thiết lập

scripts/sandbox-setup.sh

docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'
FROM debian:bookworm-slim
ENV DEBIAN_FRONTEND=noninteractive
RUN 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 sandbox
USER sandbox
WORKDIR /home/sandbox
CMD ["sleep", "infinity"]
DOCKERFILE

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 agent: 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 khắc phục.
• Xem Môi trường cô lập 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 điều này bị chặn?”.

​

Ghi đè đa agent

​

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

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

​

Liên quan

• Môi trường cô lập & Công cụ đa agent — ghi đè theo từng agent và thứ tự ưu tiên
• OpenShell — thiết lập backend môi trường cô lập được quản lý, chế độ workspace và tham chiếu cấu hình
• Cấu hình môi trường cô lập
• Môi trường cô lập so với Chính sách công cụ so với Quyền nâng cao — gỡ lỗi “tại sao điều này bị chặn?”
• Bảo mật