Korumalı alan

OpenClaw, etki alanını azaltmak için araçları sandbox arka uçları içinde çalıştırabilir. Bu isteğe bağlıdır ve yapılandırma (agents.defaults.sandbox veya agents.list[].sandbox) ile denetlenir. Sandbox kapalıysa araçlar ana makinede çalışır. Gateway ana makinede kalır; etkinleştirildiğinde araç yürütme yalıtılmış bir sandbox içinde çalışır.

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

Sandbox'a alınmayanlar:

• 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

agents.defaults.sandbox.mode, sandbox'ın ne zaman kullanılacağını denetler:

Kapsam

agents.defaults.sandbox.scope, kaç kapsayıcı oluşturulacağını denetler:

• "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ç

agents.defaults.sandbox.backend, sandbox'ı hangi çalışma zamanının sağlayacağını denetler:

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

SSH'ye özgü yapılandırma agents.defaults.sandbox.ssh altında bulunur. OpenShell'e özgü yapılandırma plugins.entries.openshell.config altında bulunur.

Arka uç seçme

Docker arka ucu

Sandbox varsayılan olarak kapalıdır. Sandbox'ı etkinleştirir ve bir arka uç seçmezseniz OpenClaw Docker arka ucunu kullanır. Araçları ve sandbox tarayıcılarını Docker daemon soketi (/var/run/docker.sock) üzerinden yerel olarak yürütür. Sandbox kapsayıcı yalıtımı Docker ad alanları tarafından belirlenir.

Ana makine GPU'larını Docker sandbox'larına açmak için agents.defaults.sandbox.docker.gpus değerini veya aracı başına agents.list[].sandbox.docker.gpus geçersiz kılmasını ayarlayın. Değer, Docker'ın --gpus bayrağına ayrı bir argüman olarak aktarılır; örneğin "all" veya "device=GPU-uuid" ve NVIDIA Container Toolkit gibi uyumlu bir ana makine çalışma zamanı gerektirir.

SSH arka ucu

OpenClaw'ın exec, dosya araçları ve medya okumalarını SSH ile erişilebilen rastgele bir makinede sandbox'a almasını istediğinizde 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",          // 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

OpenClaw'ın araçları OpenShell tarafından yönetilen uzak bir ortamda sandbox'a almasını istediğinizde backend: "openshell" kullanın. Tam kurulum kılavuzu, yapılandırma başvurusu ve çalışma alanı modu karşılaştırması için ayrılmış OpenShell sayfasına bakın.

OpenShell, genel SSH arka ucuyla aynı temel SSH taşımasını ve uzak dosya sistemi köprüsünü yeniden kullanır; buna OpenShell'e özgü yaşam döngüsü (sandbox create/get/delete, sandbox ssh-config) ve isteğe bağlı mirror çalışma alanı modu ekler.

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

OpenShell modları:

• 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'in iki çalışma alanı modeli vardır. Pratikte en önemli kısım budur.

Sandbox'ı geçici bir yürütme ortamı olarak düşünüyorsanız mirror seçin. Sandbox'ı gerçek çalışma alanı olarak düşünüyorsanız remote seçin.

OpenShell yaşam döngüsü

OpenShell sandbox'ları hâlâ normal sandbox yaşam döngüsü üzerinden yönetilir:

• 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

remote modu için yeniden oluşturma özellikle önemlidir:

• 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

mirror modu için yeniden oluşturma, yerel çalışma alanı zaten kanonik kaldığından esas olarak uzak yürütme ortamını sıfırlar.

Çalışma alanı erişimi

agents.defaults.sandbox.workspaceAccess, sandbox'ın neyi görebileceğini kontrol eder:

OpenShell arka ucuyla:

• 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

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

Özel bind bağlamaları

agents.defaults.sandbox.docker.binds, ek ana makine dizinlerini container içine bağlar. Biçim: host:container:mode (ör. "/home/user/source:/source:rw").

Genel ve ajan başına bind'ler birleştirilir (değiştirilmez). scope: "shared" altında ajan başına bind'ler yok sayılır.

agents.defaults.sandbox.browser.binds, ek ana makine dizinlerini yalnızca sandbox tarayıcısı container'ına bağlar.

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

Örnek (salt okunur kaynak + ek bir veri dizini):

{  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

Varsayılan olarak Docker sandbox container'ları ağ olmadan çalışır. agents.defaults.sandbox.docker.network ile geçersiz kılın.

Docker kurulumları ve konteynerleştirilmiş Gateway burada bulunur: Docker

Docker Gateway dağıtımları için 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) ayarlayın. Soket konumunu OPENCLAW_DOCKER_SOCKET ile geçersiz kılabilirsiniz. Tam kurulum ve ortam referansı: Docker.

setupCommand (tek seferlik konteyner kurulumu)

setupCommand, korumalı alan 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
• Aracı başına: agents.list[].sandbox.docker.setupCommand

Araç ilkesi ve kaçış mekanizmaları

Araç izin/verme ve reddetme ilkeleri, korumalı alan kurallarından önce hâlâ uygulanır. Bir araç genel olarak veya aracı başına reddedilmişse, korumalı alan onu geri getirmez.

tools.elevated, exec işlemini korumalı alan dışında çalıştıran açık bir kaçış mekanizmasıdır (varsayılan olarak gateway veya exec hedefi node olduğunda node). /exec yönergeleri yalnızca yetkili gönderenler için geçerlidir ve oturum başına kalıcıdır; exec işlemini kesin olarak devre dışı bırakmak için araç ilkesi reddini kullanın (bkz. Korumalı Alan ile Araç İlkesi ile Elevated Karşılaştırması).

Hata ayıklama:

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

Sıkı şekilde kilitli tutun.

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

Her aracı korumalı alanı ve araçları geçersiz kılabilir: agents.list[].sandbox ve agents.list[].tools (ayrıca korumalı alan araç ilkesi için agents.list[].tools.sandbox.tools). Öncelik sırası için Çok Aracılı 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

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