OpenShell - OpenClaw

OpenShell là backend sandbox được quản lý cho OpenClaw. Thay vì chạy Docker container cục bộ, OpenClaw ủy quyền vòng đời sandbox cho CLI openshell, công cụ này cấp phát môi trường từ xa với thực thi lệnh dựa trên SSH. Plugin OpenShell tái sử dụng cùng transport SSH lõi và cầu nối hệ thống tệp từ xa như backend SSH chung. Nó bổ sung vòng đời riêng cho OpenShell (sandbox create/get/delete, sandbox ssh-config) và chế độ workspace mirror tùy chọn.

Điều kiện tiên quyết

Đã cài đặt Plugin OpenShell (openclaw plugins install @openclaw/openshell-sandbox)
Đã cài đặt CLI openshell và có trong PATH (hoặc đặt đường dẫn tùy chỉnh qua plugins.entries.openshell.config.command)
Một tài khoản OpenShell có quyền truy cập sandbox
OpenClaw Gateway đang chạy trên host

Bắt đầu nhanh

Cài đặt và bật Plugin, sau đó đặt backend sandbox:

openclaw plugins install @openclaw/openshell-sandbox

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "session",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote",
        },
      },
    },
  },
}

Khởi động lại Gateway. Ở lượt agent tiếp theo, OpenClaw tạo một sandbox OpenShell và định tuyến việc thực thi công cụ qua sandbox đó.
Xác minh:

openclaw sandbox list
openclaw sandbox explain

Chế độ workspace

Đây là quyết định quan trọng nhất khi sử dụng OpenShell.

`mirror`

Dùng plugins.entries.openshell.config.mode: "mirror" khi bạn muốn workspace cục bộ vẫn là nguồn chuẩn. Hành vi:

Trước exec, OpenClaw đồng bộ workspace cục bộ vào sandbox OpenShell.
Sau exec, OpenClaw đồng bộ workspace từ xa trở lại workspace cục bộ.
Các công cụ tệp vẫn hoạt độ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.

Phù hợp nhất cho:

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

Đánh đổi: thêm chi phí đồng bộ trước và sau mỗi exec.

`remote`

Dùng plugins.entries.openshell.config.mode: "remote" khi bạn muốn workspace OpenShell trở thành nguồn chuẩn. Hành vi:

Khi sandbox được tạo lần đầu, OpenClaw gieo 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 trên workspace OpenShell từ xa.
OpenClaw không đồng bộ các thay đổi từ xa trở lại workspace cục bộ.
Các lượt đọc media tại thời điểm prompt vẫn hoạt động vì công cụ tệp và media đọc qua cầu nối sandbox.

Phù hợp nhất cho:

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

Nếu bạn chỉnh sửa tệp trên host bên ngoài OpenClaw sau lần gieo ban đầu, sandbox từ xa không thấy các thay đổi đó. Dùng openclaw sandbox recreate để gieo lại.

Chọn chế độ

	`mirror`	`remote`
Workspace chuẩn	Host cục bộ	OpenShell từ xa
Hướng đồng bộ	Hai chiều (mỗi exec)	Gieo một lần
Chi phí mỗi lượt	Cao hơn (tải lên + tải xuống)	Thấp hơn (thao tác trực tiếp từ xa)
Chỉnh sửa cục bộ hiển thị?	Có, ở exec tiếp theo	Không, cho đến khi recreate
Phù hợp nhất cho	Quy trình phát triển	Agent chạy lâu, CI

Tham chiếu cấu hình

Toàn bộ cấu hình OpenShell nằm dưới plugins.entries.openshell.config:

Khóa	Kiểu	Mặc định	Mô tả
`mode`	`"mirror"` hoặc `"remote"`	`"mirror"`	Chế độ đồng bộ workspace
`command`	`string`	`"openshell"`	Đường dẫn hoặc tên của CLI `openshell`
`from`	`string`	`"openclaw"`	Nguồn sandbox cho lần tạo đầu tiên
`gateway`	`string`	—	Tên Gateway OpenShell (`--gateway`)
`gatewayEndpoint`	`string`	—	URL endpoint Gateway OpenShell (`--gateway-endpoint`)
`policy`	`string`	—	ID policy OpenShell để tạo sandbox
`providers`	`string[]`	`[]`	Tên provider cần gắn khi sandbox được tạo
`gpu`	`boolean`	`false`	Yêu cầu tài nguyên GPU
`autoProviders`	`boolean`	`true`	Truyền `--auto-providers` trong khi tạo sandbox
`remoteWorkspaceDir`	`string`	`"/sandbox"`	Workspace chính có thể ghi bên trong sandbox
`remoteAgentWorkspaceDir`	`string`	`"/agent"`	Đường dẫn mount workspace agent (cho quyền truy cập chỉ đọc)
`timeoutSeconds`	`number`	`120`	Thời gian chờ cho các thao tác CLI `openshell`

Các thiết lập cấp sandbox (mode, scope, workspaceAccess) được cấu hình dưới agents.defaults.sandbox như với mọi backend. Xem Sandboxing để biết ma trận đầy đủ.

Ví dụ

Thiết lập remote tối giản

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote",
        },
      },
    },
  },
}

Chế độ mirror với GPU

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "agent",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "mirror",
          gpu: true,
          providers: ["openai"],
          timeoutSeconds: 180,
        },
      },
    },
  },
}

OpenShell theo từng agent với Gateway tùy chỉnh

{
  agents: {
    defaults: {
      sandbox: { mode: "off" },
    },
    list: [
      {
        id: "researcher",
        sandbox: {
          mode: "all",
          backend: "openshell",
          scope: "agent",
          workspaceAccess: "rw",
        },
      },
    ],
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote",
          gateway: "lab",
          gatewayEndpoint: "https://lab.example",
          policy: "strict",
        },
      },
    },
  },
}

Quản lý vòng đời

Sandbox OpenShell được quản lý qua CLI sandbox thông thường:

# Liệt kê toàn bộ runtime sandbox (Docker + OpenShell)
openclaw sandbox list

# Kiểm tra policy có hiệu lực
openclaw sandbox explain

# Tạo lại (xóa workspace từ xa, gieo lại ở lần dùng tiếp theo)
openclaw sandbox recreate --all

Với chế độ remote, recreate đặc biệt quan trọng: nó xóa workspace từ xa chuẩn cho phạm vi đó. Lần dùng tiếp theo sẽ gieo một workspace từ xa mới từ workspace cục bộ. Với chế độ mirror, recreate chủ yếu đặt lại môi trường thực thi từ xa vì workspace cục bộ vẫn là nguồn chuẩn.

Khi nào cần recreate

Recreate sau khi thay đổi bất kỳ mục nào sau đây:

agents.defaults.sandbox.backend
plugins.entries.openshell.config.from
plugins.entries.openshell.config.mode
plugins.entries.openshell.config.policy

openclaw sandbox recreate --all

Gia cố bảo mật

OpenShell ghim fd gốc workspace và kiểm tra lại danh tính sandbox trước mỗi lần đọc, vì vậy việc tráo symlink hoặc remount workspace không thể chuyển hướng lượt đọc ra ngoài workspace từ xa dự kiến.

Giới hạn hiện tại

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

Cách hoạt động

OpenClaw gọi openshell sandbox create (với các cờ --from, --gateway, --policy, --providers, --gpu như đã cấu hình).
OpenClaw gọi openshell sandbox ssh-config <name> để lấy chi tiết kết nối SSH cho sandbox.
Lõi ghi cấu hình SSH vào tệp tạm và mở phiên SSH bằng cùng cầu nối hệ thống tệp từ xa như backend SSH chung.
Ở chế độ mirror: đồng bộ cục bộ lên từ xa trước exec, chạy, rồi đồng bộ trở lại sau exec.
Ở chế độ remote: gieo một lần khi tạo, sau đó thao tác trực tiếp trên workspace từ xa.

Liên quan

Sandboxing — chế độ, phạm vi, và so sánh backend
Sandbox so với Policy công cụ so với Elevated — gỡ lỗi công cụ bị chặn
Sandbox và công cụ đa agent — ghi đè theo từng agent
CLI sandbox — các lệnh openclaw sandbox

​Điều kiện tiên quyết

​Bắt đầu nhanh

​Chế độ workspace

​mirror

​remote

​Chọn chế độ

​Tham chiếu cấu hình

​Ví dụ

​Thiết lập remote tối giản

​Chế độ mirror với GPU

​OpenShell theo từng agent với Gateway tùy chỉnh

​Quản lý vòng đời

​Khi nào cần recreate

​Gia cố bảo mật

​Giới hạn hiện tại

​Cách hoạt động

​Liên quan

Điều kiện tiên quyết

Bắt đầu nhanh

Chế độ workspace

`mirror`

`remote`

Chọn chế độ

Tham chiếu cấu hình

Ví dụ

Thiết lập remote tối giản

Chế độ mirror với GPU

OpenShell theo từng agent với Gateway tùy chỉnh

Quản lý vòng đời

Khi nào cần recreate

Gia cố bảo mật

Giới hạn hiện tại

Cách hoạt động

Liên quan