Korumalı Alan Kullanımı

​

Korumalı alanda çalıştırılanlar

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

• Gateway işleminin kendisi.
• tools.elevated aracılığıyla korumalı alan dışında çalışmasına açıkça izin verilen tüm araçlar. Yükseltilmiş yürütme, korumalı alanı atlar ve yapılandırılmış çıkış yolunda çalışır (varsayılan olarak gateway; yürütme hedefi node olduğunda ise node). Korumalı alan kapalıysa yürütme zaten ana sistemde çalıştığından tools.elevated hiçbir şeyi değiştirmez. Bkz. Yükseltilmiş Mod.

​

Modlar, kapsam ve arka uç

• off: korumalı alan kullanılmaz.
• non-main: ajanın ana oturumu dışındaki tüm oturumları korumalı alanda çalıştırır. Ana oturum anahtarı her zaman agent:<agentId>:main değeridir (session.scope, "global" olduğunda ise global); yapılandırılamaz. Grup/kanal oturumları kendi anahtarlarını kullanır; bu nedenle her zaman ana olmayan oturum sayılır ve korumalı alanda çalıştırılır.
• all: her oturum bir korumalı alanda çalışır.

• agent: ajan başına bir kapsayıcı.
• session: oturum başına bir kapsayıcı.
• shared: korumalı alandaki tüm oturumların paylaştığı tek bir kapsayıcı (bu kapsam altında ajan başına docker/ssh/browser geçersiz kılmaları yok sayılır).

​

Docker arka ucu

​

Korumalı alan tarayıcısı

• Tarayıcı aracı ihtiyaç duyduğunda korumalı alan tarayıcısı otomatik olarak başlatılır (CDP’nin erişilebilir olmasını sağlar). agents.defaults.sandbox.browser.autoStart (varsayılan true) ve autoStartTimeoutMs (varsayılan 12s) aracılığıyla yapılandırın.
• Korumalı alan tarayıcı kapsayıcıları, genel bridge ağı yerine özel bir Docker ağı (openclaw-sandbox-browser) kullanır. agents.defaults.sandbox.browser.network ile yapılandırın.
• agents.defaults.sandbox.browser.cdpSourceRange, bir CIDR izin listesiyle kapsayıcı sınırındaki CDP girişini kısıtlar (örneğin 172.21.0.1/32).
• noVNC gözlemci erişimi varsayılan olarak parola korumalıdır; OpenClaw, yerel bir önyükleme sayfası sunan ve noVNC’yi URL parçasındaki parolayla (sorgu dizesinde veya üstbilgi günlüklerinde değil) açan kısa ömürlü bir belirteç URL’si oluşturur.
• agents.defaults.sandbox.browser.allowHostControl (varsayılan false), korumalı alandaki oturumların ana sistem tarayıcısını açıkça hedeflemesine olanak tanır.
• İsteğe bağlı izin listeleri target: "custom" kullanımını denetler: allowedControlUrls, allowedControlHosts, allowedControlPorts.

​

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",
          // Ya da yerel dosyalar yerine SecretRefs / satır içi içerikler kullanın:
          // 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" },
        },
      },
    },
  },
}

• Yaşam döngüsü: OpenClaw, sandbox.ssh.workspaceRoot altında kapsam başına bir uzak kök oluşturur. Oluşturma veya yeniden oluşturma sonrasındaki ilk kullanımda, bu uzak çalışma alanına yerel çalışma alanından bir kez başlangıç verileri aktarır. Bundan sonra exec, read, write, edit, apply_patch, istem medya okumaları ve gelen medya hazırlama işlemleri SSH üzerinden doğrudan uzak çalışma alanında çalışır. OpenClaw, uzak değişiklikleri yerel çalışma alanına otomatik olarak eşitlemez.
• Kimlik doğrulama materyali: identityFile/certificateFile/knownHostsFile mevcut yerel dosyalara başvurur. identityData/certificateData/knownHostsData, normal gizli bilgiler çalışma zamanı anlık görüntüsü aracılığıyla çözümlenen, 0600 moduyla geçici dosyalara yazılan ve SSH oturumu sona erdiğinde silinen satır içi dizeleri veya SecretRefs değerlerini kabul eder. Aynı öğe için hem *File hem de *Data çeşidi ayarlanmışsa o oturumda *Data önceliklidir.
• Uzak sistemin esas alınmasının sonuçları: İlk başlangıç verisi aktarımından sonra uzak SSH çalışma alanı gerçek korumalı alan durumu hâline gelir. Başlangıç verisi aktarımı adımından sonra OpenClaw dışında ana sistemde yapılan yerel düzenlemeler, korumalı alanı yeniden oluşturana kadar uzak sistemde görünmez. openclaw sandbox recreate, kapsam başına uzak kökü siler ve sonraki kullanımda yerelden yeniden başlangıç verileri aktarır. Tarayıcı korumalı alanı bu arka uçta desteklenmez ve sandbox.docker.* ayarları bu arka uç için geçerli değildir.

​

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

​

Çalışma alanı erişimi

​

Tek bir ajan için birden çok klasör

host-directory:container-directory:ro
host-directory:container-directory:rw

• ro, bağlanan klasörü sandbox içinde salt okunur yapar.
• rw, sandbox içindeki araçların ve süreçlerin ana makine klasörünü değiştirmesine izin verir.
• Container yolu, ajanın kullandığı yoldur. Ana makine yolları otomatik olarak açığa çıkarılmaz.

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        scope: "agent",
      },
    },
    list: [
      {
        id: "research",
        workspace: "/srv/openclaw/research-workspace",
        sandbox: {
          workspaceAccess: "rw",
          docker: {
            binds: ["/srv/shared/reference:/reference:ro", "/srv/shared/drafts:/drafts:rw"],
            // Bu kaynaklar ajan çalışma alanının dışında olduğu için gereklidir.
            dangerouslyAllowExternalBindSources: true,
          },
        },
      },
    ],
  },
}

openclaw sandbox recreate --agent research

​

Diğer bind davranışları

{
  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 container kurulumu)

• Genel: agents.defaults.sandbox.docker.setupCommand
• Agent başına: agents.entries.*.sandbox.docker.setupCommand

​

Araç politikası ve kaçış yolları

• openclaw sandbox list; korumalı alan container’larını, durumu, görüntü eşleşmesini, yaşı, boşta kalma süresini ve ilişkili oturumu/agent’ı gösterir.
• openclaw sandbox explain [--session <key>] [--agent <id>]; geçerli korumalı alan modunu, ana makine çalışma alanını, çalışma zamanı çalışma dizinini, Docker bağlamalarını, araç politikasını ve düzeltme yapılandırma anahtarlarını inceler. workspaceRoot alanı, yapılandırılmış korumalı alan kökü olarak kalır; effectiveHostWorkspaceRoot, etkin çalışma alanının gerçekte nerede bulunduğunu gösterir.
• openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force], bir sonraki kullanımda geçerli yapılandırmayla yeniden oluşturulmaları için container’ları/ortamları kaldırır.
• “Bu neden engellendi?” yaklaşımı için Korumalı Alan, Araç Politikası ve Yükseltilmiş Mod Karşılaştırması bölümüne bakın.

​

Çoklu agent geçersiz kılmaları

​

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

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

​

İlgili konular

• Çoklu Agent Korumalı Alanı ve Araçları — agent başına geçersiz kılmalar ve öncelik sırası
• OpenShell — yönetilen korumalı alan arka ucu kurulumu, çalışma alanı modları ve yapılandırma başvurusu
• Korumalı alan yapılandırması
• Korumalı Alan, Araç Politikası ve Yükseltilmiş Mod Karşılaştırması — “Bu neden engellendi?” sorusunda hata ayıklama
• Güvenlik