Korumalı alan oluşturma

OpenClaw, etki alanını azaltmak için araç yürütmeyi bir korumalı alan arka ucu içinde çalıştırabilir. Korumalı alan varsayılan olarak kapalıdır ve agents.defaults.sandbox (genel) veya agents.list[].sandbox (ajan başına) tarafından denetlenir. Gateway işlemi her zaman ana makinede kalır; etkinleştirildiğinde yalnızca araç yürütme korumalı alana taşınır.

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).

Korumalı alanda çalıştırılmayanlar:

• 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ş exec, korumalı alanı atlar ve yapılandırılmış çıkış yolunda çalışır (varsayılan olarak gateway; exec hedefi node olduğunda node). Korumalı alan kapalıysa exec zaten ana makinede çalıştığından tools.elevated hiçbir şeyi değiştirmez. Bkz. Yükseltilmiş Mod.

Modlar, kapsam ve arka uç

Korumalı alan davranışını üç bağımsız ayar denetler:

Mod, korumalı alanın ne zaman uygulanacağını denetler:

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

Kapsam, kaç kapsayıcı/ortam oluşturulacağını denetler:

• agent: ajan başına bir kapsayıcı.
• session: oturum başına bir kapsayıcı.
• shared: korumalı alandaki tüm oturumlar tarafından paylaşılan bir kapsayıcı (bu kapsamda ajan başına docker/ssh/browser geçersiz kılmaları yok sayılır).

Arka uç, korumalı alan araçlarını hangi çalışma zamanının yürüteceğini denetler. SSH'ye özgü yapılandırma agents.defaults.sandbox.ssh altında; OpenShell'e özgü yapılandırma ise plugins.entries.openshell.config altında bulunur.

Docker arka ucu

Korumalı alan etkinleştirildiğinde Docker varsayılan arka uçtur. Araçları ve korumalı alan tarayıcılarını Docker daemon soketi (/var/run/docker.sock) üzerinden yerel olarak çalıştırır; yalıtım Docker ad alanlarından gelir.

Varsayılanlar: network: "none" (dışarıya erişim yok), readOnlyRoot: true, capDrop: ["ALL"], imaj openclaw-sandbox:bookworm-slim.

Ana makine GPU'larını kullanıma açmak için agents.defaults.sandbox.docker.gpus değerini (veya ajan başına geçersiz kılmayı) "all" ya da "device=GPU-uuid" gibi bir değere ayarlayın. Bu değer Docker'ın --gpus bayrağına aktarılır ve NVIDIA Container Toolkit gibi uyumlu bir ana makine çalışma zamanı gerektirir.

Korumalı alan tarayıcısı

• Korumalı alan tarayıcısı, tarayıcı aracı ihtiyaç duyduğunda 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 12 sn.) üzerinden 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, kapsayıcı sınırındaki CDP girişini bir CIDR izin listesiyle sınırlar (ö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 açan kısa ömürlü bir belirteç URL'si üretir (sorgu dizesinde veya üstbilgi günlüklerinde değil).
• agents.defaults.sandbox.browser.allowHostControl (varsayılan false), korumalı alandaki oturumların ana makine tarayıcısını açıkça hedeflemesine izin verir.
• İsteğe bağlı izin listeleri target: "custom" kullanımını denetler: allowedControlUrls, allowedControlHosts, allowedControlPorts.

SSH arka ucu

Rastgele bir SSH erişimli makinede exec, dosya araçları ve medya okumalarını korumalı alanda çalıştırmak için backend: "ssh" kullanın.

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

Varsayılanlar: command: "ssh", workspaceRoot: "/tmp/openclaw-sandboxes", strictHostKeyChecking: true, updateHostKeys: true.

• 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 işleminden sonraki ilk kullanımda yerel çalışma alanını bir kez bu uzak çalışma alanına aktarır. Ardından exec, read, write, edit, apply_patch, istem medya okumaları ve gelen medya hazırlama işlemleri doğrudan SSH üzerinden uzak çalışma alanında çalışır. OpenClaw, uzak değişiklikleri yerel çalışma alanına otomatik olarak eşitlemez.
• Kimlik doğrulama malzemesi: identityFile/certificateFile/knownHostsFile, mevcut yerel dosyalara başvurur. identityData/certificateData/knownHostsData, satır içi dizeleri veya normal gizli bilgiler çalışma zamanı anlık görüntüsü üzerinden çözümlenen SecretRefs değerlerini kabul eder; bunlar 0600 moduyla geçici dosyalara yazılır ve SSH oturumu sona erdiğinde silinir. Aynı öğe için hem bir *File hem de bir *Data çeşidi ayarlanmışsa ilgili oturumda *Data önceliklidir.
• Uzak ortamın esas olmasının sonuçları: İlk aktarımın ardından uzak SSH çalışma alanı gerçek korumalı alan durumu hâline gelir. Aktarım adımından sonra OpenClaw dışında ana makinede yapılan yerel düzenlemeler, korumalı alanı yeniden oluşturana kadar uzak ortamda görünmez. openclaw sandbox recreate, kapsam başına uzak kökü siler ve bir sonraki kullanımda yerel çalışma alanını yeniden aktarır. Bu arka uçta tarayıcı korumalı alanı desteklenmez ve sandbox.docker.* ayarları geçerli değildir.

OpenShell arka ucu

Araçları OpenShell tarafından yönetilen uzak bir ortamda korumalı alanda çalıştırmak için backend: "openshell" kullanın. OpenShell, genel SSH arka ucuyla aynı SSH aktarımını ve uzak dosya sistemi köprüsünü yeniden kullanır; ayrıca OpenShell yaşam döngüsünü (sandbox create/get/delete/ssh-config) ve isteğe bağlı bir mirror çalışma alanı eşitleme modunu ekler.

{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "openshell",        scope: "session",        workspaceAccess: "rw",      },    },  },  plugins: {    entries: {      openshell: {        enabled: true,        config: {          from: "openclaw",          mode: "remote", // mirror | remote        },      },    },  },}

mode: "mirror" (varsayılan), yerel çalışma alanını esas tutar: OpenClaw, exec öncesinde yerel içeriği korumalı alana eşitler ve sonrasında değişiklikleri geri eşitler. mode: "remote", uzak çalışma alanına yerel ortamdan bir kez başlangıç verisi aktarır; ardından exec/read/write/edit/apply_patch işlemlerini geri eşitleme yapmadan doğrudan uzak çalışma alanında çalıştırır. Aktarımdan sonra yapılan yerel düzenlemeler, openclaw sandbox recreate komutunu çalıştırana kadar görünmez. scope: "agent" veya scope: "shared" altında bu uzak çalışma alanı aynı kapsamda paylaşılır. Mevcut sınırlamalar: korumalı alan tarayıcısı henüz desteklenmez ve sandbox.docker.binds bu arka uçta geçerli değildir.

openclaw sandbox list/recreate/prune komutlarının tümü OpenShell çalışma zamanlarını Docker çalışma zamanlarıyla aynı şekilde ele alır; temizleme mantığı arka ucun farkındadır.

Tüm ön koşullar, yapılandırma başvurusu, çalışma alanı modu karşılaştırması ve yaşam döngüsü ayrıntıları için OpenShell bölümüne bakın.

Çalışma alanı erişimi

agents.defaults.sandbox.workspaceAccess, korumalı alanın neleri görebileceğini denetler:

OpenShell arka ucuyla mirror modu, çalıştırma turları arasında yerel çalışma alanını hâlâ kurallı kaynak olarak kullanır; remote modu ilk başlangıç verileri aktarıldıktan sonra uzak OpenShell çalışma alanını kurallı kaynak olarak kullanır ve workspaceAccess: "ro"/"none" yazma davranışını aynı şekilde kısıtlamaya devam eder.

Gelen medya, etkin sandbox çalışma alanına (media/inbound/*) kopyalanır.

Özel bağlama noktaları

agents.defaults.sandbox.docker.binds, ek ana makine dizinlerini konteynere bağlar. Biçim: ana_makine:konteyner:mod (ör. "/home/user/source:/source:rw").

Genel ve ajan başına bağlamalar birleştirilir (birbirinin yerini almaz). scope: "shared" altında ajan başına bağlamalar yok sayılır.

agents.defaults.sandbox.browser.binds, ek ana makine dizinlerini yalnızca sandbox tarayıcısı konteynerine bağlar. Ayarlandığında ([] dâhil), tarayıcı konteyneri için docker.binds değerinin yerini alır; belirtilmediğinde tarayıcı konteyneri docker.binds değerine geri döner.

{  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

Varsayılan Docker imajı: openclaw-sandbox:bookworm-slim

scripts/sandbox-setup.sh

docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'FROM debian:bookworm-slimENV DEBIAN_FRONTEND=noninteractiveRUN 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 sandboxUSER sandboxWORKDIR /home/sandboxCMD ["sleep", "infinity"]DOCKERFILE

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

Docker sandbox konteynerleri varsayılan olarak ağ olmadan çalışır. agents.defaults.sandbox.docker.network ile geçersiz kılın.

Docker kurulumları ve konteynerleştirilmiş Gateway burada açıklanır: Docker

Docker Gateway dağıtımları için scripts/docker/setup.sh, sandbox yapılandırmasını önyükleyebilir. Bu yolu etkinleştirmek için OPENCLAW_SANDBOX=1 (veya true/yes/on) olarak ayarlayın. Soket konumunu OPENCLAW_DOCKER_SOCKET ile geçersiz kılın. Tam kurulum ve ortam değişkeni başvurusu: Docker.

setupCommand (tek seferlik konteyner kurulumu)

setupCommand, sandbox konteyneri oluşturulduktan sonra bir kez çalışır (her çalıştırmada değil). Konteyner içinde sh -lc aracılığıyla yürütülür.

Yollar:

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

Araç ilkesi ve kaçış yolları

Araç izin verme/reddetme ilkeleri sandbox kurallarından önce uygulanmaya devam eder. Bir araç genel olarak veya ajan başına reddedilmişse sandbox kullanımı onu geri getirmez.

tools.elevated, exec komutunu sandbox dışında çalıştıran açık bir kaçış yoludur (varsayılan olarak gateway; çalıştırma hedefi node olduğunda node). /exec yönergeleri yalnızca yetkili göndericiler için geçerlidir ve oturum boyunca kalıcıdır; exec komutunu kesin olarak devre dışı bırakmak için araç ilkesi reddini kullanın (bkz. Sandbox, Araç İlkesi ve Yükseltilmiş Çalıştırma Karşılaştırması).

Hata ayıklama:

• openclaw sandbox list; sandbox konteynerlerini, durumlarını, imaj eşleşmesini, yaşını, boşta kalma süresini ve ilişkili oturumu/ajanı gösterir.
• openclaw sandbox explain [--session <key>] [--agent <id>]; geçerli sandbox modunu, ana makine çalışma alanını, çalışma zamanı çalışma dizinini, Docker bağlamalarını, araç ilkesini ve düzeltme yapılandırması anahtarlarını inceler. workspaceRoot alanı yapılandırılmış sandbox 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]; konteynerleri/ortamları kaldırır, böylece bir sonraki kullanımda mevcut yapılandırmayla yeniden oluşturulurlar.
• "Bu neden engellendi?" düşünce modeli için Sandbox, Araç İlkesi ve Yükseltilmiş Çalıştırma Karşılaştırması bölümüne bakın.

Çok ajanlı geçersiz kılmalar

Her ajan sandbox + araç ayarlarını geçersiz kılabilir: agents.list[].sandbox ve agents.list[].tools (sandbox araç ilkesi için ayrıca agents.list[].tools.sandbox.tools). Öncelik sırası için Çok Ajanlı Sandbox ve Araçlar bölümüne bakın.

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

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

İlgili

• Çoklu Aracı Sandbox'ı ve Araçları -- aracı başına geçersiz kılmalar ve öncelik sırası
• OpenShell -- yönetilen sandbox arka ucu kurulumu, çalışma alanı modları ve yapılandırma başvurusu
• Sandbox yapılandırması
• Sandbox, Araç Politikası ve Yükseltilmiş Yetki Karşılaştırması -- "bu neden engelleniyor?" sorununu ayıklama
• Güvenlik