Korumalı alana alma

OpenClaw, patlama yarıçapını azaltmak için araçları sandbox arka uçlarının 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.

# Sandbox içine 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 içine 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 kullanımını 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 ana makinededir). Bkz. Yükseltilmiş Mod.

# Modlar

agents.defaults.sandbox.mode, sandbox kullanımının ne zaman uygulanacağını denetler:

# Kapsam

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

• "agent" (varsayılan): ajan başına bir container.
• "session": oturum başına bir container.
• "shared": sandbox içindeki tüm oturumlar tarafından paylaşılan bir container.

# Arka uç

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

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

# 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 container yalıtımı Docker namespace'leri tarafından belirlenir.

Ana makine GPU'larını Docker sandbox'larına açmak için agents.defaults.sandbox.docker.gpus değerini veya ajan 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 runtime'ı gerektirir.

# SSH arka ucu

OpenClaw'ın exec, dosya araçları ve medya okumalarını SSH ile erişilebilen herhangi bir makinede sandbox içine 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 içine 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 özel OpenShell sayfasına bakın.

OpenShell, genel SSH arka ucuyla aynı çekirdek SSH taşımasını ve uzak dosya sistemi köprüsünü yeniden kullanır; ayrıca OpenShell'e özgü yaşam döngüsünü (sandbox create/get/delete, sandbox ssh-config) ve 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 seed eder, 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.

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 ortamları hâlâ normal sandbox yaşam döngüsü üzerinden yönetilir:

• openclaw sandbox list, Docker runtime'larının yanı sıra OpenShell runtime'larını da gösterir
• openclaw sandbox recreate, geçerli runtime'ı siler ve bir sonraki kullanımda OpenClaw'ın onu yeniden oluşturmasına izin verir
• temizleme mantığı da backend farkındadır

remote modu için recreate özellikle önemlidir:

• recreate, 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ı besler

mirror modu için recreate, yerel çalışma alanı zaten kanonik kaldığından çoğunlukla uzak yürütme ortamını sıfırlar.

# Çalışma alanı erişimi

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

OpenShell backend ile:

• mirror modu, exec turları arasında yerel çalışma alanını hâlâ kanonik kaynak olarak kullanır
• remote modu, ilk beslemeden 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 sandbox çalışma alanına kopyalanır (media/inbound/*).

# Özel bind mount'lar

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

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

agents.defaults.sandbox.browser.binds, ek host 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 yerini alır.
• 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-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

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 container'lı Gateway burada yer alır: Docker

Docker Gateway dağıtımları için scripts/docker/setup.sh, sandbox 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 env referansı: Docker.

# setupCommand (tek seferlik container kurulumu)

setupCommand, sandbox container'ı oluşturulduktan sonra bir kez çalışır (her çalıştırmada değil). Container 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ç politikası ve çıkış yolları

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

tools.elevated, exec komutunu sandbox dışında çalıştıran açık bir çıkış 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. Sandbox ve Araç Politikası ve Elevated).

Hata ayıklama:

• Geçerli sandbox modunu, araç politikasını ve düzeltme yapılandırma anahtarlarını incelemek için openclaw sandbox explain kullanın.
• "Bu neden engellendi?" zihinsel modeli için bkz. Sandbox ve Araç Politikası ve Elevated.

Kilitli tutun.

# Çok ajanlı geçersiz kılmalar

Her ajan sandbox + araçları geçersiz kılabilir: agents.list[].sandbox ve agents.list[].tools (sandbox araç politikası için ayrıca agents.list[].tools.sandbox.tools). Öncelik sırası için bkz. Çok Ajanlı Sandbox ve Araçlar.

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

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

# İlgili

• Çok Ajanlı Sandbox ve Araçlar — ajan bazında geçersiz kılmalar ve öncelik sırası
• OpenShell — yönetilen sandbox arka uç kurulumu, çalışma alanı modları ve yapılandırma referansı
• Sandbox yapılandırması
• Sandbox ve Araç Politikası ve Elevated — "Bu neden engellendi?" hata ayıklaması
• Güvenlik