Korumalı Alan Kullanımı

OpenClaw, etki alanını azaltmak için araç yürütmeyi bir korumalı alan arka ucunda çalıştırabilir. Korumalı alan varsayılan olarak kapalıdır ve agents.defaults.sandbox (genel) veya agents.entries.*.sandbox (ajan başına) tarafından denetlenir. Gateway işlemi her zaman ana sistemde 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ş 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ç

Üç bağımsız ayar korumalı alan davranışını denetler:

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

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

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

Arka uç, korumalı alandaki araçları 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 varsayılan arka uç Docker'dır. 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ıyla sağlanır.

Varsayılanlar: network: "none" (dışarı giden bağlantı yok), readOnlyRoot: true, capDrop: ["ALL"], imaj openclaw-sandbox:bookworm-slim.

Ana sistem 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 sistem çalışma zamanı gerektirir.

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

exec, dosya araçları ve medya okumalarını SSH ile erişilebilen herhangi bir makinede 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",          // 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" },        },      },    },  },}

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

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; bunlara 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ı kanonik tutar: OpenClaw, exec öncesinde yerel çalışma alanını sandbox'a eşitler ve sonrasında değişiklikleri geri eşitler. mode: "remote", uzak çalışma alanını yerelden bir kez başlangıç verileriyle doldurur, 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; başlangıç verileri aktarıldıktan sonra yapılan yerel düzenlemeler, openclaw sandbox recreate işlemini gerçekleştirene 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: sandbox tarayıcısı henüz desteklenmemektedir ve sandbox.docker.binds bu arka uç için geçerli değildir.

openclaw sandbox list/recreate/prune işlemlerinin tümü OpenShell çalışma zamanlarını Docker çalışma zamanlarıyla aynı şekilde ele alır; prune mantığı arka uca duyarlıdı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 sayfasına bakın.

Çalışma alanı erişimi

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

OpenShell arka ucunda mirror modu, exec çalıştırmaları arasında kanonik kaynak olarak yine yerel çalışma alanını kullanır; remote modu, ilk başlangıç verisi aktarımından sonra kanonik kaynak olarak uzak OpenShell çalışma alanını 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.

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

Sandbox'ta çalışan bir ajanın birincil çalışma alanından daha fazlasına ihtiyacı olduğunda Docker bind bağlamalarını kullanın. Her girdi, bir ana makine klasörünü açıkça belirtilmiş bir erişim moduyla bir container yoluna eşler:

host-directory:container-directory:rohost-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.

Bu örnek, research ajanına yazılabilir bir birincil çalışma alanı, /reference konumunda salt okunur başvuru materyali ve /drafts konumunda ayrı bir yazılabilir çıktı klasörü sağlar:

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

workspaceAccess ve bind modları birbirinden bağımsızdır:

workspaceAccess değerini değiştirmek, ek bir bind bağlamasını ro modundan rw moduna veya tersine değiştirmez. Genel ve ajan başına docker.binds değerleri birleştirilir. Ajan başına bind bağlamaları için scope: "agent" veya "session" kullanmaya devam edin; scope: "shared", ajan başına tüm Docker geçersiz kılmalarını yok sayar ve yalnızca genel bind bağlamalarını kullanır.

Bind bağlamaları, desteklenen çok klasörlü sınırdır; çünkü Docker, container'ın dosya sistemi görünümünü bağlama yalıtımıyla oluşturur ve ro/rw modu sandbox içindeki her sürece uygulanır. Bu sınır, her OpenClaw kod yolunda dosya yolu yetkilendirme denetimlerini çoğaltmadan exec, dosya sistemi araçları, alt süreçler ve kütüphaneleri kapsar. Ana makine tarafındaki bir yol izin listesi, izin verilen bir kabuk veya bağımlılık dosyalara doğrudan erişebildiğinde aynı eksiksiz sınırı sağlayamaz.

İsteğe bağlı dangerouslyAllowExternalBindSources, yalnızca çalışma alanı köklerinin dışındaki kaynaklara izin verir. OpenClaw'ın engellenen sistem, kimlik bilgisi, Docker soketi, sembolik bağlantı üst dizini veya ayrılmış hedef denetimlerini devre dışı bırakmaz. En küçük klasörü tercih edin, yazma gerekmediği sürece ro kullanın ve bağlamaları değiştirdikten sonra sandbox'ı yeniden oluşturun:

openclaw sandbox recreate --agent research

Diğer bind davranışları

agents.defaults.sandbox.docker.binds, genel bağlamaları yapılandırır. Biçim aynı host:container:mode biçimidir (örneğin "/home/user/source:/source:rw").

agents.defaults.sandbox.browser.binds, ek ana makine dizinlerini yalnızca sandbox tarayıcısı container'ına bağlar. Ayarlandığında ([] dâhil), tarayıcı container'ı için docker.binds değerinin yerini alır; belirtilmediğinde tarayıcı container'ı 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 container'ları varsayılan olarak ağ olmadan çalışır. agents.defaults.sandbox.docker.network ile geçersiz kılın.

Docker kurulumları ve container'laştırılmış Gateway burada bulunur: Docker

Docker Gateway dağıtımlarında scripts/docker/setup.sh, korumalı alan yapılandırmasını başlatabilir. Bu yolu etkinleştirmek için OPENCLAW_SANDBOX=1 (veya true/yes/on) değerini 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 container kurulumu)

setupCommand, korumalı alan container'ı oluşturulduktan sonra bir kez çalışır (her çalıştırmada değil). Container içinde sh -lc aracılığıyla yürütülür.

Yollar:

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

Araç politikası ve kaçış yolları

Araç izin/reddetme politikaları, korumalı alan kurallarından önce uygulanmaya devam eder. Bir araç genel olarak veya agent başına reddedilmişse korumalı alan kullanımı onu yeniden etkinleştirmez.

tools.elevated, exec aracını korumalı alan dışında çalıştıran açık bir kaçış yoludur (varsayılan olarak gateway; exec hedefi node olduğunda ise node). /exec yönergeleri yalnızca yetkili gönderenler için geçerlidir ve oturum başına kalıcıdır; exec özelliğini kesin olarak devre dışı bırakmak için araç politikası reddini kullanın (bkz. Korumalı Alan, Araç Politikası ve Yükseltilmiş Mod Karşılaştırması).

Hata ayıklama:

• 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ı

Her agent, korumalı alanı ve araçları geçersiz kılabilir: agents.entries.*.sandbox ve agents.entries.*.tools (ayrıca korumalı alan araç politikası için agents.entries.*.tools.sandbox.tools). Öncelik sırası için Çoklu Agent Korumalı Alanı 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 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