OpenShell

OpenShell là một backend sandbox được quản lý: thay vì chạy các container Docker cục bộ, OpenClaw ủy quyền vòng đời sandbox cho CLI openshell, công cụ này cấp phát các môi trường từ xa và thực thi lệnh qua SSH.

Plugin này tái sử dụng cùng cơ chế truyền tải SSH và cầu nối hệ thống tệp từ xa như backend SSH dùng chung, đồng thời bổ sung vòng đời OpenShell (sandbox create/get/delete/ssh-config) cùng chế độ đồng bộ không gian làm việc mirror tùy chọn.

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

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

Bắt đầu nhanh

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 tác tử tiếp theo, OpenClaw sẽ tạo một sandbox OpenShell và định tuyến việc thực thi công cụ qua đó. Xác minh bằng:

openclaw sandbox listopenclaw sandbox explain

Các chế độ không gian làm việc

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

mirror (mặc định)

plugins.entries.openshell.config.mode: "mirror" giữ không gian làm việc cục bộ làm bản chuẩn:

• Trước khi exec, OpenClaw đồng bộ không gian làm việc cục bộ vào sandbox.
• Sau khi exec, OpenClaw đồng bộ không gian làm việc từ xa trở lại cục bộ.
• Các công cụ tệp đi qua cầu nối sandbox, nhưng bản cục bộ vẫn là nguồn dữ liệu chuẩn giữa các lượt.

Phù hợp nhất với quy trình phát triển: các chỉnh sửa cục bộ bên ngoài OpenClaw sẽ xuất hiện ở lần exec tiếp theo, và sandbox hoạt động gần giống backend Docker.

Đánh đổi: phát sinh chi phí tải lên + tải xuống ở mỗi lượt exec.

remote

mode: "remote" đặt không gian làm việc OpenShell làm bản chuẩn:

• Khi tạo sandbox lần đầu, OpenClaw khởi tạo không gian làm việc từ xa từ bản cục bộ một lần.
• Sau đó, exec, read, write, edit và apply_patch thao tác trực tiếp trên không gian làm việc từ xa. OpenClaw không đồng bộ các thay đổi từ xa trở lại cục bộ.
• Việc đọc nội dung đa phương tiện khi tạo lời nhắc vẫn hoạt động (công cụ tệp/phương tiện đọc qua cầu nối sandbox).

Phù hợp nhất với các tác tử chạy lâu dài và CI: chi phí mỗi lượt thấp hơn, đồng thời các chỉnh sửa cục bộ trên máy chủ không thể âm thầm ghi đè trạng thái từ xa.

Chọn chế độ

Tham chiếu cấu hình

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

remoteWorkspaceDir và remoteAgentWorkspaceDir phải là đường dẫn tuyệt đối và nằm trong các thư mục gốc được quản lý /sandbox hoặc /agent; các đường dẫn tuyệt đối khác sẽ bị từ chối.

Các thiết lập cấp sandbox (mode, scope, workspaceAccess) nằm trong agents.defaults.sandbox như với mọi backend. Xem Sandbox để biết toàn bộ ma trận.

Ví dụ

Thiết lập remote tối thiểu

{  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 tác tử 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

# Liệt kê tất cả môi trường chạy sandbox (Docker + OpenShell)openclaw sandbox list # Kiểm tra chính sách có hiệu lựcopenclaw sandbox explain # Tạo lại (xóa không gian làm việc từ xa, khởi tạo lại ở lần sử dụng tiếp theo)openclaw sandbox recreate --all

Đối với chế độ remote, việc tạo lại đặc biệt quan trọng: thao tác này xóa không gian làm việc từ xa chuẩn của phạm vi đó, và lần sử dụng tiếp theo sẽ khởi tạo một không gian mới từ bản cục bộ. Đối với chế độ mirror, việc tạo lại chủ yếu đặt lại môi trường thực thi từ xa vì bản cục bộ vẫn là bản chuẩn.

Tạo lại 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

Tăng cường bảo mật

Cầu nối hệ thống tệp ở chế độ mirror cố định thư mục gốc của không gian làm việc cục bộ và kiểm tra lại các đường dẫn chuẩn (qua realpath) trước mỗi thao tác đọc, ghi, mkdir, xóa và đổi tên, đồng thời từ chối các liên kết tượng trưng nằm giữa đường dẫn. Việc tráo đổi liên kết tượng trưng hoặc gắn kết lại không gian làm việc không thể chuyển hướng quyền truy cập tệp ra ngoài cây được phản chiếu.

Các 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; việc tạo sandbox sẽ thất bại nếu có cấu hình binds.
• Các tùy chọn môi trường chạy dành riêng cho Docker trong sandbox.docker.* (ngoại trừ env) chỉ áp dụng cho backend Docker.

Cách thức hoạt động

1. OpenClaw chạy sandbox get cho tên sandbox (kèm mọi --gateway/--gateway-endpoint đã cấu hình); nếu thao tác đó thất bại, OpenClaw tạo sandbox bằng sandbox create, truyền --name, --from, --policy khi được đặt, --gpu khi được bật, --auto-providers/--no-auto-providers và một cờ --provider cho mỗi nhà cung cấp đã cấu hình.
2. OpenClaw chạy sandbox ssh-config cho tên sandbox để lấy thông tin kết nối SSH.
3. Lõi ghi cấu hình SSH vào một tệp tạm thời và mở phiên SSH thông qua cùng cầu nối hệ thống tệp từ xa như backend SSH dùng chung.
4. Trong chế độ mirror: đồng bộ cục bộ lên từ xa trước khi exec, chạy lệnh, rồi đồng bộ trở lại sau đó.
5. Trong chế độ remote: khởi tạo một lần khi tạo, sau đó thao tác trực tiếp trên không gian làm việc từ xa.

Liên quan

• Sandbox - các chế độ, phạm vi và so sánh backend
• Sandbox, chính sách công cụ và chế độ nâng cao - gỡ lỗi các công cụ bị chặn
• Sandbox và công cụ đa tác tử - ghi đè theo từng tác tử
• CLI sandbox - các lệnh openclaw sandbox