CLI hộp cát

Quản lý các môi trường chạy sandbox để thực thi tác nhân biệt lập: vùng chứa Docker, đích SSH hoặc backend OpenShell.

Lệnh

openclaw sandbox list

Liệt kê các môi trường chạy sandbox cùng trạng thái, backend, mức khớp cấu hình, thời gian tồn tại, thời gian nhàn rỗi và phiên/tác nhân liên kết.

openclaw sandbox listopenclaw sandbox list --browser  # chỉ các vùng chứa trình duyệtopenclaw sandbox list --json

openclaw sandbox recreate

Xóa các môi trường chạy sandbox để buộc tạo lại theo cấu hình hiện tại. Các môi trường chạy được tự động tạo lại vào lần tiếp theo tác nhân được sử dụng.

openclaw sandbox recreate --allopenclaw sandbox recreate --agent mybot        # bao gồm các phiên con agent:mybot:*openclaw sandbox recreate --session "agent:main:main"openclaw sandbox recreate --browser --all      # chỉ các vùng chứa trình duyệtopenclaw sandbox recreate --all --force        # bỏ qua xác nhận

Tùy chọn:

• --all: tạo lại tất cả vùng chứa sandbox
• --session <key>: tạo lại môi trường chạy có chính xác khóa phạm vi này (như hiển thị bởi sandbox list); không mở rộng tên ngắn
• --agent <id>: tạo lại các môi trường chạy cho một tác nhân (khớp với agent:<id> và agent:<id>:*)
• --browser: chỉ tác động đến các vùng chứa trình duyệt
• --force: bỏ qua lời nhắc xác nhận

Chỉ truyền đúng một trong các tùy chọn --all, --session hoặc --agent.

Đối với ssh và OpenShell remote, việc tạo lại quan trọng hơn so với Docker: không gian làm việc từ xa trở thành bản chuẩn sau lần khởi tạo ban đầu, recreate xóa không gian làm việc từ xa chuẩn đó cho phạm vi đã chọn và lần chạy tiếp theo sẽ khởi tạo lại từ không gian làm việc cục bộ hiện tại.

openclaw sandbox explain

Kiểm tra chế độ/phạm vi/quyền truy cập không gian làm việc sandbox có hiệu lực, chính sách công cụ sandbox và các cổng kiểm soát công cụ nâng cao (kèm đường dẫn khóa cấu hình để khắc phục).

Báo cáo giữ workspaceRoot làm thư mục gốc sandbox đã cấu hình, đồng thời hiển thị riêng không gian làm việc máy chủ có hiệu lực, thư mục làm việc của môi trường chạy backend và bảng gắn kết Docker. Với workspaceAccess: "rw", không gian làm việc máy chủ có hiệu lực là không gian làm việc của tác nhân thay vì một thư mục bên dưới workspaceRoot.

openclaw sandbox explainopenclaw sandbox explain --session agent:main:mainopenclaw sandbox explain --agent workopenclaw sandbox explain --json

Không giống recreate --session, lệnh này chấp nhận tên phiên ngắn (ví dụ main) và mở rộng chúng theo tác nhân đã phân giải.

Tại sao cần tạo lại

Việc cập nhật cấu hình sandbox không ảnh hưởng đến các vùng chứa đang chạy: các môi trường chạy hiện có vẫn giữ thiết lập cũ và các môi trường chạy nhàn rỗi chỉ bị dọn dẹp sau prune.idleHours (mặc định 24 giờ). Các tác nhân được sử dụng thường xuyên có thể duy trì vô thời hạn các môi trường chạy dùng cấu hình cũ. openclaw sandbox recreate xóa môi trường chạy cũ để lần sử dụng tiếp theo xây dựng lại môi trường đó từ cấu hình hiện tại.

Các trường hợp thường cần thực hiện

Di chuyển sổ đăng ký

Siêu dữ liệu môi trường chạy sandbox nằm trong cơ sở dữ liệu trạng thái SQLite dùng chung. Các bản cài đặt cũ hơn có thể chứa những tệp sổ đăng ký cũ mà thao tác đọc thông thường không còn ghi lại:

• ~/.openclaw/sandbox/containers.json
• ~/.openclaw/sandbox/browsers.json
• một phân mảnh JSON cho mỗi vùng chứa/trình duyệt trong ~/.openclaw/sandbox/containers/ hoặc ~/.openclaw/sandbox/browsers/

Chạy openclaw doctor --fix để di chuyển các mục cũ hợp lệ vào SQLite. Các tệp cũ không hợp lệ được cách ly để sổ đăng ký cũ bị hỏng không thể che khuất các mục môi trường chạy hiện tại.

Cấu hình

Các thiết lập sandbox nằm trong ~/.openclaw/openclaw.json tại agents.defaults.sandbox (các ghi đè theo từng tác nhân nằm trong agents.list[].sandbox):

{  "agents": {    "defaults": {      "sandbox": {        "mode": "all", // off, non-main, all        "backend": "docker", // docker, ssh, openshell (do plugin cung cấp)        "scope": "agent", // session, agent, shared        "docker": {          "image": "openclaw-sandbox:bookworm-slim",          "containerPrefix": "openclaw-sbx-",          // ... các tùy chọn Docker khác        },        "prune": {          "idleHours": 24, // tự động dọn dẹp sau 24 giờ nhàn rỗi          "maxAgeDays": 7, // tự động dọn dẹp sau 7 ngày        },      },    },  },}

Liên quan

• Tài liệu tham khảo CLI
• Cơ chế sandbox
• Không gian làm việc của tác nhân
• Doctor: kiểm tra thiết lập sandbox.