Ізоляція в пісочниці

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

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

​

Що потрапляє в sandbox

• Виконання інструментів (exec, read, write, edit, apply_patch, process тощо).
• Необов’язковий sandbox-браузер (agents.defaults.sandbox.browser).

• Сам процес Gateway.
• Будь-який інструмент, якому явно дозволено виконуватися поза sandbox (наприклад, tools.elevated).
  • Elevated exec обходить sandboxing і використовує налаштований escape-шлях (gateway за замовчуванням або node, коли ціль exec — node).
  • Якщо sandboxing вимкнено, tools.elevated не змінює виконання (воно вже на хості). Див. Elevated Mode.

​

Режими

​

Область

• "agent" (за замовчуванням): один контейнер на агента.
• "session": один контейнер на сеанс.
• "shared": один контейнер, спільний для всіх sandbox-сеансів.

​

Бекенд

• "docker" (за замовчуванням, коли sandboxing увімкнено): локальне sandbox-середовище виконання на базі Docker.
• "ssh": універсальне віддалене sandbox-середовище виконання на базі SSH.
• "openshell": sandbox-середовище виконання на базі 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 (за замовчуванням): локальна робоча область залишається канонічною. OpenClaw синхронізує локальні файли в OpenShell перед exec і синхронізує віддалену робочу область назад після exec.
• remote: робоча область OpenShell є канонічною після створення sandbox. OpenClaw один раз заповнює віддалену робочу область із локальної робочої області, після чого файлові інструменти й exec виконуються безпосередньо щодо віддаленого sandbox без синхронізації змін назад.

​

Режими робочої області

​

Життєвий цикл 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 — налагодження «чому це заблоковано?»
• Безпека