Korumalı alan

​

Neler sandbox’a alınır

• Araç yürütme (exec, read, write, edit, apply_patch, process vb.).
• İsteğe bağlı sandbox’a alınmış tarayıcı (agents.defaults.sandbox.browser).

• Gateway sürecinin kendisi.
• Sandbox dışında çalışmasına açıkça izin verilen herhangi bir araç (ör. tools.elevated).
  • Yükseltilmiş exec sandbox’ı atlar ve yapılandırılmış kaçış yolunu kullanır (varsayılan olarak gateway, exec hedefi node olduğunda ise node).
  • Sandbox kapalıysa tools.elevated yürütmeyi değiştirmez (zaten ana makinededir). Bkz. Yükseltilmiş Mod.

​

Modlar

​

Kapsam

• "agent" (varsayılan): aracı başına bir kapsayıcı.
• "session": oturum başına bir kapsayıcı.
• "shared": sandbox’a alınmış tüm oturumlar tarafından paylaşılan bir kapsayıcı.

​

Arka uç

• "docker" (sandbox etkinleştirildiğinde varsayılan): yerel Docker destekli sandbox çalışma zamanı.
• "ssh": genel SSH destekli uzak sandbox çalışma zamanı.
• "openshell": OpenShell destekli sandbox çalışma zamanı.

​

Arka uç seçme

​

Docker arka ucu

​

SSH arka ucu

{
  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 arka ucu

{
  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 (varsayılan): yerel çalışma alanı kanonik kalır. OpenClaw, exec öncesinde yerel dosyaları OpenShell içine eşitler ve exec sonrasında uzak çalışma alanını geri eşitler.
• remote: sandbox oluşturulduktan sonra OpenShell çalışma alanı kanonik olur. OpenClaw, uzak çalışma alanını yerel çalışma alanından bir kez tohumlar; ardından dosya araçları ve exec, değişiklikleri geri eşitlemeden doğrudan uzak sandbox’a karşı çalışır.

​

Çalışma alanı modları

​

OpenShell yaşam döngüsü

• openclaw sandbox list, Docker çalışma zamanlarının yanı sıra OpenShell çalışma zamanlarını da gösterir
• openclaw sandbox recreate, geçerli çalışma zamanını siler ve OpenClaw’ın bir sonraki kullanımda yeniden oluşturmasına izin verir
• temizleme mantığı da arka uçtan haberdardır

• yeniden oluşturma, o kapsam için kanonik uzak çalışma alanını siler
• sonraki kullanım, yerel çalışma alanından yeni bir uzak çalışma alanı tohumlar

​

Çalışma alanı erişimi

• mirror modu, exec turları arasında kanonik kaynak olarak hâlâ yerel çalışma alanını kullanır
• remote modu, ilk tohumlamadan sonra kanonik kaynak olarak uzak OpenShell çalışma alanını kullanır
• workspaceAccess: "ro" ve "none" yazma davranışını aynı şekilde kısıtlamaya devam eder

​

Özel bind bağlamaları

• Ayarlandığında ([] dahil), tarayıcı container’ı için agents.defaults.sandbox.docker.binds değerinin yerine geçer.
• Atlandığında, tarayıcı container’ı agents.defaults.sandbox.docker.binds değerine geri döner (geriye dönük uyumlu).

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

​

İmajlar ve kurulum

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 (tek seferlik konteyner kurulumu)

• Genel: agents.defaults.sandbox.docker.setupCommand
• Aracı başına: agents.list[].sandbox.docker.setupCommand

​

Araç ilkesi ve kaçış mekanizmaları

• Etkili korumalı alan modunu, araç ilkesini ve düzeltme yapılandırma anahtarlarını incelemek için openclaw sandbox explain kullanın.
• “Bu neden engellendi?” düşünce modeli için Korumalı Alan ile Araç İlkesi ile Elevated Karşılaştırması bölümüne bakın.

​

Çok aracılı geçersiz kılmalar

​

En küçük etkinleştirme örneği

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

​

İlgili

• Çok Aracılı Korumalı Alan ve Araçlar — aracı başına geçersiz kılmalar ve öncelik sırası
• OpenShell — yönetilen korumalı alan arka uç kurulumu, çalışma alanı modları ve yapılandırma referansı
• Korumalı alan yapılandırması
• Korumalı Alan ile Araç İlkesi ile Elevated Karşılaştırması — “Bu neden engellendi?” hata ayıklaması
• Güvenlik