Chuyển đến nội dung chính

Documentation Index

Fetch the complete documentation index at: https://openclawhub.vn/llms.txt

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

​
OpenShell

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

​
Yêu cầu trước

  • CLI openshell đã được cài đặt và có trong PATH (hoặc thiết lập đườ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

  1. Kích hoạt plugin và thiết lập backend sandbox:
{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "session",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote",
        },
      },
    },
  },
}
  1. Khởi động lại Gateway. Ở lần chạy tiếp theo của agent, OpenClaw sẽ tạo một sandbox OpenShell và định tuyến việc thực thi công cụ qua đó.
  2. Kiểm tra: 
openclaw sandbox list
openclaw sandbox explain

​
Chế độ Workspace

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

​
mirror

Sử dụng plugins.entries.openshell.config.mode: "mirror" khi bạn muốn workspace cục bộ là nguồn chính. Hành vi:
  • Trước khi exec, OpenClaw đồng bộ workspace cục bộ vào sandbox OpenShell.
  • Sau khi 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 chính giữa các lần chạy.
Phù hợp nhất cho:
  • Bạn chỉnh sửa tệp cục bộ ngoài OpenClaw và muốn những thay đổi đó tự động hiển thị trong sandbox.
  • Bạn muốn sandbox OpenShell hoạt động giống như backend Docker nhất có thể.
  • Bạn muốn workspace trên máy chủ phản ánh các ghi chép trong sandbox sau mỗi lần thực thi.
Đánh đổi: chi phí đồng bộ thêm trước và sau mỗi lần thực thi.

​
remote

Sử dụng plugins.entries.openshell.config.mode: "remote" khi bạn muốn workspace OpenShell trở thành nguồn chính. Hành vi:
  • Khi sandbox được tạo lần đầu, OpenClaw sẽ khởi tạo 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 media khi nhắc vẫn hoạt động vì các công cụ tệp và media đọc qua cầu nối sandbox.
Phù hợp nhất cho:
  • Sandbox nên tồn tại chủ yếu ở phía từ xa.
  • Bạn muốn giảm chi phí đồng bộ cho mỗi lần chạy.
  • Bạn không muốn các chỉnh sửa cục bộ trên máy chủ ghi đè trạng thái sandbox từ xa một cách âm thầm.
Quan trọng: nếu bạn chỉnh sửa tệp trên máy chủ ngoài OpenClaw sau khi khởi tạo ban đầu, sandbox từ xa không thấy những thay đổi đó. Sử dụng openclaw sandbox recreate để khởi tạo lại.

​
Chọn chế độ

mirrorremote
Workspace chínhMáy chủ cục bộOpenShell từ xa
Hướng đồng bộHai chiều (mỗi lần exec)Khởi tạo một lần
Chi phí mỗi lần chạyCao hơn (tải lên + tải về)Thấp hơn (thao tác từ xa)
Chỉnh sửa cục bộ thấy được?Có, ở lần exec tiếp theoKhông, cho đến khi khởi tạo lại
Phù hợp nhất choQuy trình phát triểnAgent chạy dài, CI

​
Tham khảo cấu hình

Tất cả cấu hình OpenShell nằm dưới plugins.entries.openshell.config:
KeyTypeDefaultDescription
mode"mirror" or "remote""mirror"Chế độ đồng bộ workspace
commandstring"openshell"Đường dẫn hoặc tên của CLI openshell
fromstring"openclaw"Nguồn sandbox cho lần tạo đầu tiên
gatewaystring—Tên gateway OpenShell (--gateway)
gatewayEndpointstring—URL endpoint gateway OpenShell (--gateway-endpoint)
policystring—ID chính sách OpenShell cho việc tạo sandbox
providersstring[][]Tên nhà cung cấp để đính kèm khi tạo sandbox
gpubooleanfalseYêu cầu tài nguyên GPU
autoProvidersbooleantrueTruyền --auto-providers trong quá trình tạo sandbox
remoteWorkspaceDirstring"/sandbox"Workspace chính có thể ghi bên trong sandbox
remoteAgentWorkspaceDirstring"/agent"Đường dẫn mount workspace agent (cho truy cập chỉ đọc)
timeoutSecondsnumber120Thờ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 bất kỳ backend nào. Xem Sandboxing để biết ma trận đầy đủ.

​
Ví dụ

​
Thiết lập từ xa 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 cho 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

Các sandbox OpenShell được quản lý thông qua CLI sandbox thông thường: 
# Liệt kê tất cả các runtime sandbox (Docker + OpenShell)
openclaw sandbox list

# Kiểm tra chính sách hiệu lực
openclaw sandbox explain

# Tạo lại (xóa workspace từ xa, khởi tạo lại khi sử dụng tiếp theo)
openclaw sandbox recreate --all
Đối với chế độ remote, tạo lại đặc biệt quan trọng: nó xóa workspace từ xa chính cho phạm vi đó. Lần sử dụng tiếp theo sẽ khởi tạo một workspace từ xa mới từ workspace cục bộ. Đối với chế độ mirror, tạo lại 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 chính.

​
Khi nào cần tạo lại

Tạo lại sau khi thay đổi bất kỳ điều 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

​
Hạn chế 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út điều chỉnh runtime đặc thù của Docker dưới sandbox.docker.* chỉ áp dụng cho backend Docker.

​
Cách hoạt động

  1. OpenClaw gọi openshell sandbox create (với các cờ --from, --gateway, --policy, --providers, --gpu như đã cấu hình).
  2. OpenClaw gọi openshell sandbox ssh-config <name> để lấy thông tin kết nối SSH cho sandbox.
  3. Core ghi cấu hình SSH vào một tệp tạm thời và mở một phiên SSH sử dụng cùng cầu nối hệ thống tệp từ xa như backend SSH chung.
  4. Trong chế độ mirror: đồng bộ từ cục bộ đến từ xa trước khi thực thi, chạy, đồng bộ lại sau khi thực thi.
  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 workspace từ xa.

​
Xem thêm

Last modified on March 22, 2026