CLI пісочниці

Керуйте середовищами виконання пісочниці для ізольованого виконання агентів: контейнерами Docker, цільовими вузлами SSH або бекендами OpenShell.

Команди

openclaw sandbox list

Вивести список середовищ виконання пісочниці зі станом, бекендом, відповідністю конфігурації, віком, часом простою та пов’язаним сеансом або агентом.

openclaw sandbox listopenclaw sandbox list --browser  # лише браузерні контейнериopenclaw sandbox list --json

openclaw sandbox recreate

Видалити середовища виконання пісочниці, щоб примусово повторно створити їх із поточною конфігурацією. Середовища виконання автоматично створюються повторно під час наступного використання агента.

openclaw sandbox recreate --allopenclaw sandbox recreate --agent mybot        # включає підсеанси agent:mybot:*openclaw sandbox recreate --session "agent:main:main"openclaw sandbox recreate --browser --all      # лише браузерні контейнериopenclaw sandbox recreate --all --force        # пропустити підтвердження

Параметри:

• --all: повторно створити всі контейнери пісочниці
• --session <key>: повторно створити середовище виконання з цим точним ключем області дії (як показано командою sandbox list); без розгортання короткого імені
• --agent <id>: повторно створити середовища виконання для одного агента (відповідає agent:<id> і agent:<id>:*)
• --browser: впливати лише на браузерні контейнери
• --force: пропустити запит на підтвердження

Передайте рівно один із параметрів: --all, --session або --agent.

Для ssh і OpenShell remote повторне створення важливіше, ніж для Docker: після початкового заповнення віддалений робочий простір стає канонічним, команда recreate видаляє цей канонічний віддалений робочий простір для вибраної області дії, а наступний запуск повторно заповнює його з поточного локального робочого простору.

openclaw sandbox explain

Переглянути ефективний режим і область дії пісочниці, доступ до робочого простору, політику інструментів пісочниці та обмеження для інструментів із підвищеними привілеями (зі шляхами до ключів конфігурації для виправлення).

У звіті workspaceRoot залишається налаштованим коренем пісочниці, а ефективний робочий простір хоста, робочий каталог середовища виконання бекенда й таблиця монтувань Docker відображаються окремо. Для workspaceAccess: "rw" ефективним робочим простором хоста є робочий простір агента, а не каталог усередині workspaceRoot.

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

На відміну від recreate --session, ця команда приймає короткі імена сеансів (наприклад, main) і розгортає їх відносно визначеного агента.

Навіщо потрібне повторне створення

Оновлення конфігурації пісочниці не впливає на запущені контейнери: наявні середовища виконання зберігають старі налаштування, а неактивні середовища видаляються лише після завершення періоду prune.idleHours (типове значення — 24 години). Агенти, яких використовують регулярно, можуть необмежено довго підтримувати застарілі середовища виконання активними. Команда openclaw sandbox recreate видаляє старе середовище виконання, щоб під час наступного використання його було перебудовано відповідно до поточної конфігурації.

Поширені причини

Міграція реєстру

Метадані середовищ виконання пісочниці зберігаються у спільній базі даних стану SQLite. У старіших інсталяціях можуть залишатися застарілі файли реєстру, які звичайне читання більше не перезаписує:

• ~/.openclaw/sandbox/containers.json
• ~/.openclaw/sandbox/browsers.json
• один сегмент JSON на кожен контейнер або браузер у ~/.openclaw/sandbox/containers/ чи ~/.openclaw/sandbox/browsers/

Запустіть openclaw doctor --fix, щоб перенести коректні застарілі записи до SQLite. Некоректні застарілі файли поміщаються в карантин, щоб пошкоджений старий реєстр не міг приховувати поточні записи середовищ виконання.

Конфігурація

Налаштування пісочниці зберігаються в ~/.openclaw/openclaw.json у розділі agents.defaults.sandbox (перевизначення для окремих агентів розміщуються в agents.list[].sandbox):

{  "agents": {    "defaults": {      "sandbox": {        "mode": "all", // off, non-main, all        "backend": "docker", // docker, ssh, openshell (надається Plugin)        "scope": "agent", // session, agent, shared        "docker": {          "image": "openclaw-sandbox:bookworm-slim",          "containerPrefix": "openclaw-sbx-",          // ... інші параметри Docker        },        "prune": {          "idleHours": 24, // автоматичне видалення після 24 годин простою          "maxAgeDays": 7, // автоматичне видалення через 7 днів        },      },    },  },}

Пов’язані матеріали

• Довідник CLI
• Ізоляція в пісочниці
• Робочий простір агента
• Doctor: перевіряє налаштування пісочниці.