​

Sandboxing

​

Neler sandbox içine alınır

• Araç yürütmesi (exec, read, write, edit, apply_patch, process vb.).
• İsteğe bağlı sandbox browser (agents.defaults.sandbox.browser).
  • Varsayılan olarak sandbox browser otomatik başlar (CDP’nin erişilebilir olmasını sağlar) ve browser aracı buna ihtiyaç duyduğunda devreye girer. agents.defaults.sandbox.browser.autoStart ve agents.defaults.sandbox.browser.autoStartTimeoutMs ile yapılandırın.
  • Varsayılan olarak sandbox browser 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.
  • İsteğe bağlı agents.defaults.sandbox.browser.cdpSourceRange, kapsayıcı kenarı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 kısa ömürlü bir token URL üretir, bu URL yerel bir bootstrap sayfası sunar ve noVNC’yi parolayla URL fragment’ında açar (query/header günlüklerinde değil).
  • agents.defaults.sandbox.browser.allowHostControl, sandbox içindeki oturumların açıkça ana makine browser’ını hedeflemesine izin verir.
  • İsteğe bağlı izin listeleri target: "custom" için geçit görevi görür: allowedControlUrls, allowedControlHosts, allowedControlPorts.

• Gateway sürecinin kendisi.
• Açıkça sandbox dışında çalışmasına izin verilen herhangi bir araç (ör. tools.elevated).
  • Elevated exec sandboxing’i atlar ve yapılandırılmış kaçış yolunu kullanır (varsayılan olarak gateway, exec hedefi node olduğunda node).
  • Sandboxing kapalıysa tools.elevated yürütmeyi değiştirmez (zaten ana makinededir). Bkz. Elevated Mode.

​

Modlar

• "off": sandboxing yok.
• "non-main": yalnızca main olmayan oturumları sandbox içine alır (normal sohbetlerin ana makinede olmasını istiyorsanız varsayılan).
• "all": her oturum bir sandbox içinde çalışır. Not: "non-main", ajan kimliğine değil session.mainKey değerine (varsayılan "main") dayanır. Grup/kanal oturumları kendi anahtarlarını kullanır, bu nedenle main olmayan sayılır ve sandbox içine alınır.

​

Kapsam

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

​

Arka uç

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

​

Bir arka uç seçme

​

SSH arka ucu

{
  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 SecretRef / satır içi içerik 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" },
        },
      },
    },
  },
}

• OpenClaw, sandbox.ssh.workspaceRoot altında kapsam başına bir uzak kök oluşturur.
• Oluşturma veya yeniden oluşturmadan sonraki ilk kullanımda OpenClaw bu uzak çalışma alanını yerel çalışma alanından bir kez tohumlar.
• Bundan sonra exec, read, write, edit, apply_patch, istem medya okumaları ve gelen medya hazırlığı doğrudan uzak çalışma alanında SSH üzerinden çalışır.
• OpenClaw, uzaktaki değişiklikleri yerel çalışma alanına otomatik olarak geri senkronize etmez.

• identityFile, certificateFile, knownHostsFile: mevcut yerel dosyaları kullanır ve bunları OpenSSH yapılandırmasından geçirir.
• identityData, certificateData, knownHostsData: satır içi dizeler veya SecretRef kullanır. OpenClaw bunları normal secrets çalışma zamanı anlık görüntüsü üzerinden çözer, 0600 izinleriyle geçici dosyalara yazar ve SSH oturumu bittiğinde siler.
• Aynı öğe için hem *File hem *Data ayarlanmışsa, o SSH oturumu için *Data kazanır.

• Tohumlama adımından sonra OpenClaw dışında yapılan ana makine yerel düzenlemeleri, sandbox’ı yeniden oluşturana kadar uzakta görünmez.
• openclaw sandbox recreate, kapsam başına uzak kökü siler ve sonraki kullanımda yerelden yeniden tohumlar.
• Browser sandboxing, SSH arka ucunda desteklenmez.
• sandbox.docker.* ayarları SSH arka ucunda geçerli değildir.

​

OpenShell arka ucu

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

• 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ı kanonik olur. OpenClaw, uzak çalışma alanını bir kez yerel çalışma alanından tohumlar; sonra dosya araçları ve exec, değişiklikleri geri senkronize etmeden doğrudan uzak sandbox üzerinde çalışır.

• OpenClaw, OpenShell’den openshell sandbox ssh-config <name> ile sandbox’a özgü SSH yapılandırmasını ister.
• Çekirdek bu SSH yapılandırmasını geçici bir dosyaya yazar, SSH oturumunu açar ve backend: "ssh" tarafından kullanılan aynı uzak dosya sistemi köprüsünü yeniden kullanır.
• Yaşam döngüsü yalnızca mirror modunda farklıdır: exec öncesinde yerelden uzağa senkronizasyon, sonrasında geri senkronizasyon.

• sandbox browser henüz desteklenmiyor
• sandbox.docker.binds, OpenShell arka ucunda desteklenmiyor
• sandbox.docker.* altındaki Docker’a özgü çalışma zamanı ayarları yalnızca Docker arka ucunda geçerlidir

​

Çalışma alanı modları

mirror

• exec öncesinde OpenClaw yerel çalışma alanını OpenShell sandbox’ına senkronize eder.
• exec sonrasında OpenClaw uzak çalışma alanını yerel çalışma alanına geri senkronize eder.
• Dosya araçları yine sandbox köprüsü üzerinden çalışır, ancak turlar arasında doğruluk kaynağı yerel çalışma alanı olarak kalır.

• OpenClaw dışında dosyaları yerel olarak düzenliyor ve bu değişikliklerin sandbox’ta otomatik görünmesini istiyorsanız
• OpenShell sandbox’ının olabildiğince Docker arka ucuna benzer davranmasını istiyorsanız
• Her exec turundan sonra ana makine çalışma alanının sandbox yazılarını yansıtmasını istiyorsanız

• exec öncesi ve sonrası ek senkronizasyon maliyeti

remote

• Sandbox ilk kez oluşturulduğunda OpenClaw uzak çalışma alanını bir kez yerel çalışma alanından tohumlar.
• Bundan sonra exec, read, write, edit ve apply_patch doğrudan uzak OpenShell çalışma alanında çalışır.
• OpenClaw, uzaktaki değişiklikleri exec sonrasında yerel çalışma alanına geri senkronize etmez.
• İstem zamanındaki medya okumaları yine çalışır çünkü dosya ve medya araçları yerel ana makine yolunu varsaymak yerine sandbox köprüsünden okur.
• Taşıma, openshell sandbox ssh-config tarafından döndürülen OpenShell sandbox’ına SSH ile yapılır.

• Tohumlama adımından sonra OpenClaw dışında ana makinede dosya düzenlerseniz, uzak sandbox bu değişiklikleri otomatik olarak görmez.
• Sandbox yeniden oluşturulursa, uzak çalışma alanı tekrar yerel çalışma alanından tohumlanır.
• scope: "agent" veya scope: "shared" ile bu uzak çalışma alanı aynı kapsamta paylaşılır.

• sandbox esas olarak uzak OpenShell tarafında yaşamalıysa
• tur başına daha düşük senkronizasyon ek yükü istiyorsanız
• ana makine yerel düzenlemelerinin sessizce uzaktaki sandbox durumunun üzerine yazmasını istemiyorsanız

​

OpenShell yaşam döngüsü

• openclaw sandbox list, OpenShell çalışma zamanlarını Docker çalışma zamanlarıyla birlikte gösterir
• openclaw sandbox recreate, mevcut çalışma zamanını siler ve OpenClaw’ın sonraki kullanımda yeniden oluşturmasına izin verir
• budama mantığı da arka uç farkındadır

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

​

Çalışma alanı erişimi

• "none" (varsayılan): araçlar ~/.openclaw/sandboxes altında bir sandbox çalışma alanı görür.
• "ro": ajan çalışma alanını /agent altında salt okunur bağlar (write/edit/apply_patch devre dışı kalır).
• "rw": ajan çalışma alanını /workspace altında okuma/yazma olarak bağlar.

• mirror modu, exec turları arasında yine yerel çalışma alanını 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" yine aynı şekilde yazma davranışını sınırlar

​

Özel bind mount’lar

• Ayarlandığında ([] dahil), browser kapsayıcısı için agents.defaults.sandbox.docker.binds değerinin yerini alır.
• Atlandığında browser kapsayıcısı geriye dönük uyumluluk için agents.defaults.sandbox.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"],
          },
        },
      },
    ],
  },
}

• Bind’lar sandbox dosya sistemini atlar: ayarladığınız kipte (:ro veya :rw) ana makine yollarını açığa çıkarırlar.
• OpenClaw tehlikeli bind kaynaklarını engeller (örneğin docker.sock, /etc, /proc, /sys, /dev ve bunları açığa çıkaracak üst bağlamalar).
• OpenClaw ayrıca ~/.aws, ~/.cargo, ~/.config, ~/.docker, ~/.gnupg, ~/.netrc, ~/.npm ve ~/.ssh gibi yaygın ana dizin kimlik bilgisi köklerini de engeller.
• Bind doğrulaması yalnızca dize eşleştirmesi değildir. OpenClaw kaynak yolu normalize eder, sonra engellenen yolları ve izin verilen kökleri yeniden kontrol etmeden önce bunu en derin mevcut üst öğe üzerinden tekrar çözer.
• Bu, son yaprak henüz mevcut olmasa bile symlink üst öğe kaçışlarının yine kapalı başarısız olacağı anlamına gelir. Örnek: /workspace/run-link/new-file, run-link oraya işaret ediyorsa yine /var/run/... olarak çözülür.
• İzin verilen kaynak kökleri de aynı şekilde kanonikleştirilir; bu nedenle yalnızca symlink çözümlemesinden önce izin listesi içinde gibi görünen bir yol yine outside allowed roots olarak reddedilir.
• Hassas bağlamalar (gizli değerler, SSH anahtarları, hizmet kimlik bilgileri) kesinlikle gerekmedikçe :ro olmalıdır.
• Çalışma alanına yalnızca okuma erişimi gerekiyorsa workspaceAccess: "ro" ile birleştirin; bind kipleri bağımsız kalır.
• Bind’ların araç ilkesi ve elevated exec ile nasıl etkileştiği için bkz. Sandbox vs Tool Policy vs Elevated.

​

İmajlar + kurulum

scripts/sandbox-setup.sh

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

• --remote-debugging-address=127.0.0.1
• --remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>
• --user-data-dir=${HOME}/.chrome
• --no-first-run
• --no-default-browser-check
• --disable-3d-apis
• --disable-gpu
• --disable-dev-shm-usage
• --disable-background-networking
• --disable-extensions
• --disable-features=TranslateUI
• --disable-breakpad
• --disable-crash-reporter
• --disable-software-rasterizer
• --no-zygote
• --metrics-recording-only
• --renderer-process-limit=2
• noSandbox etkin olduğunda --no-sandbox ve --disable-setuid-sandbox.
• Üç grafik sertleştirme bayrağı (--disable-3d-apis, --disable-software-rasterizer, --disable-gpu) isteğe bağlıdır ve kapsayıcılarda GPU desteği olmadığında kullanışlıdır. İş yükünüz WebGL veya başka 3D/browser özellikleri gerektiriyorsa OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 olarak ayarlayın.
• --disable-extensions varsayılan olarak etkindir ve eklentiye bağımlı akışlar için OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 ile kapatılabilir.
• --renderer-process-limit=2, OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N> ile denetlenir; 0, Chromium’un varsayılanını korur.

• network: "host" engellenir.
• network: "container:<id>" varsayılan olarak engellenir (namespace join atlatma riski).
• Break-glass geçersiz kılma: agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true.

​

setupCommand (bir kerelik kapsayıcı kurulumu)

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

• Varsayılan docker.network değeri "none"’dır (çıkış yok), bu yüzden paket kurulumları başarısız olur.
• docker.network: "container:<id>", dangerouslyAllowContainerNamespaceJoin: true gerektirir ve yalnızca break-glass içindir.
• readOnlyRoot: true yazmaları engeller; readOnlyRoot: false ayarlayın veya özel bir imaj hazırlayın.
• Paket kurulumları için user root olmalıdır (user alanını atlayın veya user: "0:0" ayarlayın).
• Sandbox exec, ana makine process.env değerini devralmaz. Skill API anahtarları için agents.defaults.sandbox.docker.env (veya özel bir imaj) kullanın.

​

Araç ilkesi + kaçış yolları

• Etkin sandbox 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. Sandbox vs Tool Policy vs Elevated. Sıkı tutun.

​

Çoklu ajan geçersiz kılmaları

​

Asgari etkinleştirme örneği

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

​

İlgili belgeler

• OpenShell — yönetilen sandbox arka uç kurulumu, çalışma alanı modları ve yapılandırma başvurusu
• Sandbox Configuration
• Sandbox vs Tool Policy vs Elevated — “bu neden engellendi?” hata ayıklaması
• Multi-Agent Sandbox & Tools — ajan başına geçersiz kılmalar ve öncelik
• Security