Korumalı Alan

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’a alınanlar

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

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

​

Modlar

​

Kapsam

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

​

Backend

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

​

Backend seçme

​

Docker backend’i

​

SSH backend’i

{
  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 backend’i

{
  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’e senkronize eder ve exec sonrasında uzak çalışma alanını geri senkronize eder.
• remote: sandbox oluşturulduktan sonra OpenShell çalışma alanı kanoniktir. 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 senkronize etmeden 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 sonraki kullanımda bunu yeniden oluşturmasına izin verir
• temizleme mantığı da arka uç farkındadı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 yerel çalışma alanını yine kanonik kaynak olarak kullanır
• remote modu, ilk tohumlamadan sonra uzak OpenShell çalışma alanını kanonik kaynak olarak kullanır
• workspaceAccess: "ro" ve "none" yazma davranışını aynı şekilde kısıtlamaya devam eder

​

Özel bağlama noktaları

• Ayarlandığında ([] dahil), tarayıcı konteyneri için agents.defaults.sandbox.docker.binds değerinin yerine geçer.
• Atlandığında, tarayıcı konteyneri 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)

• Global: agents.defaults.sandbox.docker.setupCommand
• Ajan başına: agents.list[].sandbox.docker.setupCommand

​

Araç ilkesi ve kaçış mekanizmaları

• Etkin korumalı alan modunu, araç ilkesini ve düzeltme yapılandırma anahtarlarını incelemek için openclaw sandbox explain kullanın.
• “Bu neden engellendi?” zihinsel modeli için bkz. Korumalı alan vs Araç İlkesi vs Yükseltilmiş.

​

Çok ajanlı geçersiz kılmalar

​

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

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

​

İlgili

• Çok Ajanlı Korumalı Alan ve Araçlar — ajan bazlı geçersiz kılmalar ve öncelik sırası
• OpenShell — yönetilen korumalı alan arka uç kurulumu, çalışma alanı modları ve yapılandırma başvurusu
• Korumalı alan yapılandırması
• Korumalı alan vs Araç İlkesi vs Yükseltilmiş — “bu neden engellendi?” hata ayıklaması
• Güvenlik