Песочница

​

Что помещается в песочницу

• Выполнение инструментов (exec, read, write, edit, apply_patch, process и т. д.).
• Необязательный браузер в песочнице (agents.defaults.sandbox.browser).

• Сам процесс Gateway.
• Любой инструмент, которому явно разрешено запускаться вне песочницы (например, tools.elevated).
  • Elevated exec обходит песочницу и использует настроенный путь выхода (gateway по умолчанию или node, когда цель exec — node).
  • Если песочница отключена, tools.elevated не меняет выполнение (оно уже на хосте). См. Elevated Mode.

​

Режимы

​

Область действия

• "agent" (по умолчанию): один контейнер на агента.
• "session": один контейнер на сессию.
• "shared": один контейнер, общий для всех сессий в песочнице.

​

Бэкенд

• "docker" (по умолчанию, когда песочница включена): локальная среда выполнения песочницы на базе Docker.
• "ssh": универсальная удаленная среда выполнения песочницы на базе SSH.
• "openshell": среда выполнения песочницы на базе OpenShell.

​

Выбор бэкенда

​

Бэкенд Docker

​

Бэкенд SSH

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "ssh",
        scope: "session",
        workspaceAccess: "rw",
        ssh: {
          target: "user@gateway-host:22",
          workspaceRoot: "/tmp/openclaw-sandboxes",
          strictHostKeyChecking: true,
          updateHostKeys: true,
          identityFile: "~/.ssh/id_ed25519",
          certificateFile: "~/.ssh/id_ed25519-cert.pub",
          knownHostsFile: "~/.ssh/known_hosts",
          // Or use SecretRefs / inline contents instead of local files:
          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
        },
      },
    },
  },
}

​

Бэкенд OpenShell

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "session",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote", // mirror | remote
          remoteWorkspaceDir: "/sandbox",
          remoteAgentWorkspaceDir: "/agent",
        },
      },
    },
  },
}

• mirror (по умолчанию): локальный workspace остается каноническим. OpenClaw синхронизирует локальные файлы в OpenShell перед exec и синхронизирует удаленный workspace обратно после exec.
• remote: workspace OpenShell становится каноническим после создания песочницы. OpenClaw один раз заполняет удаленный workspace из локального workspace, затем файловые инструменты и exec выполняются напрямую с удаленной песочницей без синхронизации изменений обратно.

​

Режимы рабочей области

​

Жизненный цикл OpenShell

• openclaw sandbox list показывает как среды выполнения OpenShell, так и среды выполнения Docker
• openclaw sandbox recreate удаляет текущую среду выполнения и позволяет OpenClaw создать ее заново при следующем использовании
• логика очистки также учитывает бэкенд

• повторное создание удаляет каноническую удаленную рабочую область для этой области действия
• следующее использование заполняет свежую удаленную рабочую область из локальной рабочей области

​

Доступ к рабочей области

• режим mirror по-прежнему использует локальную рабочую область как канонический источник между ходами exec
• режим remote использует удаленную рабочую область OpenShell как канонический источник после начального заполнения
• workspaceAccess: "ro" и "none" по-прежнему ограничивают поведение записи тем же образом

​

Пользовательские bind-монтирования

• Если задано (включая []), это заменяет agents.defaults.sandbox.docker.binds для контейнера браузера.
• Если не указано, контейнер браузера откатывается к agents.defaults.sandbox.docker.binds (обратно совместимо).

{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          binds: ["/home/user/source:/source:ro", "/var/data/myapp:/data:ro"],
        },
      },
    },
    list: [
      {
        id: "build",
        sandbox: {
          docker: {
            binds: ["/mnt/cache:/cache:rw"],
          },
        },
      },
    ],
  },
}

​

Образы и настройка

scripts/sandbox-setup.sh

docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'
FROM debian:bookworm-slim
ENV DEBIAN_FRONTEND=noninteractive
RUN apt-get update && apt-get install -y --no-install-recommends \
  bash ca-certificates curl git jq python3 ripgrep \
  && rm -rf /var/lib/apt/lists/*
RUN useradd --create-home --shell /bin/bash sandbox
USER sandbox
WORKDIR /home/sandbox
CMD ["sleep", "infinity"]
DOCKERFILE

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

​

setupCommand (однократная настройка контейнера)

• Глобально: agents.defaults.sandbox.docker.setupCommand
• Для отдельного агента: agents.list[].sandbox.docker.setupCommand

​

Политика инструментов и аварийные обходы

• Используйте openclaw sandbox explain, чтобы проверить эффективный режим песочницы, политику инструментов и ключи конфигурации для исправления.
• См. Песочница, политика инструментов и Elevated для ментальной модели «почему это заблокировано?».

​

Переопределения для нескольких агентов

​

Минимальный пример включения

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
      },
    },
  },
}

​

Связанные материалы

• Песочница и инструменты для нескольких агентов — переопределения для отдельных агентов и порядок приоритета
• OpenShell — настройка управляемого бэкенда песочницы, режимы рабочей области и справочник конфигурации
• Конфигурация песочницы
• Песочница, политика инструментов и Elevated — отладка «почему это заблокировано?»
• Безопасность