Korumalı Alan

OpenClaw, etki alanını daraltmak için araçları sandbox backend'leri içinde çalıştırabilir. Bu isteğe bağlıdır ve yapılandırmayla (agents.defaults.sandbox veya agents.list[].sandbox) kontrol edilir. Sandbox kapalıysa araçlar host üzerinde çalışır. Gateway host üzerinde kalır; araç yürütme etkinleştirildiğinde yalıtılmış bir sandbox içinde çalışır.

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

Sandbox'a alınmayanlar:

• 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

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

Kapsam

agents.defaults.sandbox.scope, kaç container oluşturulacağını kontrol eder:

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

agents.defaults.sandbox.backend, sandbox'ı hangi runtime'ın sağlayacağını kontrol eder:

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

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.

Backend seçme

Docker backend'i

Sandbox varsayılan olarak kapalıdır. Sandbox'ı etkinleştirir ve bir backend seçmezseniz OpenClaw Docker backend'ini kullanır. Araçları ve sandbox tarayıcılarını Docker daemon socket'i (/var/run/docker.sock) üzerinden yerel olarak yürütür. Sandbox container yalıtımı Docker namespace'leri tarafından belirlenir.

Host GPU'larını Docker sandbox'larına göstermek için agents.defaults.sandbox.docker.gpus değerini veya agent 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 geçirilir; örneğin "all" veya "device=GPU-uuid" ve NVIDIA Container Toolkit gibi uyumlu bir host runtime'ı gerektirir.

SSH backend'i

OpenClaw'ın exec, dosya araçları ve medya okumalarını rastgele bir SSH erişilebilir 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 backend'i

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

OpenShell, genel SSH backend'iyle aynı çekirdek SSH aktarımını ve uzak dosya sistemi köprüsünü yeniden kullanır ve OpenShell'e özgü lifecycle (sandbox create/get/delete, sandbox ssh-config) ile isteğe bağlı mirror çalışma alanı 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          remoteWorkspaceDir: "/sandbox",          remoteAgentWorkspaceDir: "/agent",        },      },    },  },}

OpenShell modları:

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

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

OpenShell yaşam döngüsü

OpenShell korumalı alanları yine normal korumalı alan 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 sonraki kullanımda bunu yeniden oluşturmasına izin verir
• temizleme mantığı da arka uç farkındadı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, korumalı alanın neyi görebileceğini denetler:

OpenShell arka ucu ile:

• 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

Gelen medya etkin korumalı alan ç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: host:container:mode (ör. "/home/user/source:/source:rw").

Global ve ajan başına bağlamalar birleştirilir (değiştirilmez). scope: "shared" altında, ajan başına bağlamalar yok sayılır.

agents.defaults.sandbox.browser.binds, ek ana makine dizinlerini yalnızca korumalı alan tarayıcı konteynerine bağlar.

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

Ö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 korumalı alan konteynerleri 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 üzerinden yürütülür.

Yollar:

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

Araç ilkesi ve kaçış mekanizmaları

Araç izin/verme ilkeleri, korumalı alan kurallarından önce uygulanmaya devam eder. Bir araç genel olarak veya ajan bazında reddedilmişse, korumalı alan onu geri getirmez.

tools.elevated, exec komutunu korumalı alanın dışında çalıştıran açık bir kaçış mekanizmasıdır (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 bazında kalıcıdır; exec komutunu kesin olarak devre dışı bırakmak için araç ilkesi reddini kullanın (bkz. Korumalı alan vs Araç İlkesi vs Yükseltilmiş).

Hata ayıklama:

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

Kilit altında tutun.

Çok ajanlı geçersiz kılmalar

Her ajan 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 bkz. Çok Ajanlı Korumalı Alan ve Araçlar.

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