​

OpenShell

​

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

2. 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 đó.
3. Kiểm tra:

openclaw sandbox list
openclaw sandbox explain

​

Chế độ Workspace

​

mirror

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

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

​

remote

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

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

​

Chọn chế độ

​

Tham khảo cấu hình

​

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

# 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

​

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

• 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

• Sandboxing — các chế độ, phạm vi, và so sánh backend
• Sandbox vs Tool Policy vs Elevated — gỡ lỗi công cụ bị chặn
• Multi-Agent Sandbox and Tools — ghi đè cho từng agent
• Sandbox CLI — các lệnh openclaw sandbox