Izolacja w piaskownicy

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.

​

Co trafia do piaskownicy

• Wykonywanie narzędzi (exec, read, write, edit, apply_patch, process itd.).
• Opcjonalna przeglądarka w piaskownicy (agents.defaults.sandbox.browser).

• Sam proces Gateway.
• Każde narzędzie jawnie dopuszczone do działania poza piaskownicą (np. tools.elevated).
  • Podniesione exec omija piaskownicę i używa skonfigurowanej ścieżki ucieczki (gateway domyślnie albo node, gdy celem exec jest node).
  • Jeśli uruchamianie w piaskownicy jest wyłączone, tools.elevated nie zmienia wykonywania (już odbywa się na hoście). Zobacz Tryb podniesiony.

​

Tryby

​

Zakres

• "agent" (domyślnie): jeden kontener na agenta.
• "session": jeden kontener na sesję.
• "shared": jeden kontener współdzielony przez wszystkie sesje w piaskownicy.

​

Backend

• "docker" (domyślnie, gdy piaskownica jest włączona): lokalne środowisko piaskownicy oparte na Dockerze.
• "ssh": ogólne zdalne środowisko piaskownicy oparte na SSH.
• "openshell": środowisko piaskownicy oparte na OpenShell.

​

Wybór backendu

​

Backend Docker

​

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

​

Backend 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 (domyślnie): lokalna przestrzeń robocza pozostaje kanoniczna. OpenClaw synchronizuje pliki lokalne do OpenShell przed exec i synchronizuje zdalną przestrzeń roboczą z powrotem po exec.
• remote: przestrzeń robocza OpenShell jest kanoniczna po utworzeniu piaskownicy. OpenClaw jednorazowo zasiewa zdalną przestrzeń roboczą z lokalnej przestrzeni roboczej, a następnie narzędzia plikowe i exec działają bezpośrednio na zdalnej piaskownicy bez synchronizowania zmian z powrotem.

​

Tryby przestrzeni roboczej

​

Cykl życia OpenShell

• openclaw sandbox list pokazuje środowiska uruchomieniowe OpenShell oraz środowiska uruchomieniowe Docker
• openclaw sandbox recreate usuwa bieżące środowisko uruchomieniowe i pozwala OpenClaw odtworzyć je przy następnym użyciu
• logika czyszczenia również uwzględnia backend

• odtworzenie usuwa kanoniczny zdalny obszar roboczy dla tego zakresu
• następne użycie inicjuje świeży zdalny obszar roboczy z lokalnego obszaru roboczego

​

Dostęp do obszaru roboczego

• tryb mirror nadal używa lokalnego obszaru roboczego jako kanonicznego źródła między turami exec
• tryb remote używa zdalnego obszaru roboczego OpenShell jako kanonicznego źródła po początkowym zainicjowaniu
• workspaceAccess: "ro" i "none" nadal ograniczają zachowanie zapisu w ten sam sposób

​

Niestandardowe montowania bind

• Gdy jest ustawione (w tym []), zastępuje agents.defaults.sandbox.docker.binds dla kontenera przeglądarki.
• Gdy jest pominięte, kontener przeglądarki używa awaryjnie agents.defaults.sandbox.docker.binds (zgodność wsteczna).

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

​

Obrazy i konfiguracja

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 (jednorazowa konfiguracja kontenera)

• Globalnie: agents.defaults.sandbox.docker.setupCommand
• Per-agent: agents.list[].sandbox.docker.setupCommand

​

Zasady narzędzi i wyjścia awaryjne

• Użyj openclaw sandbox explain, aby sprawdzić efektywny tryb piaskownicy, zasady narzędzi i klucze konfiguracji naprawczej.
• Zobacz Piaskownica kontra zasady narzędzi kontra podwyższone uprawnienia, aby poznać model myślowy „dlaczego to jest zablokowane?”.

​

Nadpisania dla wielu agentów

​

Minimalny przykład włączenia

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

​

Powiązane

• Piaskownica i narzędzia wielu agentów — nadpisania dla poszczególnych agentów i kolejność pierwszeństwa
• OpenShell — konfiguracja zarządzanego zaplecza piaskownicy, tryby przestrzeni roboczej i dokumentacja konfiguracji
• Konfiguracja piaskownicy
• Piaskownica kontra zasady narzędzi kontra podwyższone uprawnienia — debugowanie „dlaczego to jest zablokowane?”
• Bezpieczeństwo