OpenShell

OpenShell, yönetilen bir korumalı alan arka ucudur: OpenClaw, Docker kapsayıcılarını yerel olarak çalıştırmak yerine korumalı alan yaşam döngüsünü uzak ortamlar hazırlayan ve komutları SSH üzerinden çalıştıran openshell CLI'ye devreder.

Plugin, genel SSH arka ucuyla aynı SSH aktarımını ve uzak dosya sistemi köprüsünü yeniden kullanır; ayrıca OpenShell yaşam döngüsünü (sandbox create/get/delete/ssh-config) ve isteğe bağlı mirror çalışma alanı eşitleme modunu ekler.

Ön koşullar

• OpenShell Plugin'inin yüklü olması (openclaw plugins install @openclaw/openshell-sandbox)
• PATH üzerinde openshell CLI (veya plugins.entries.openshell.config.command aracılığıyla özel bir yol)
• Korumalı alan erişimi olan bir OpenShell hesabı
• Ana makinede çalışan OpenClaw Gateway

Hızlı başlangıç

openclaw plugins install @openclaw/openshell-sandbox

{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "openshell",        scope: "session",        workspaceAccess: "rw",      },    },  },  plugins: {    entries: {      openshell: {        enabled: true,        config: {          from: "openclaw",          mode: "remote",        },      },    },  },}

Gateway'i yeniden başlatın. Bir sonraki aracı turunda OpenClaw bir OpenShell korumalı alanı oluşturur ve araç yürütmeyi bunun üzerinden yönlendirir. Şunlarla doğrulayın:

openclaw sandbox listopenclaw sandbox explain

Çalışma alanı modları

Bu, OpenShell için en önemli karardır.

mirror (varsayılan)

plugins.entries.openshell.config.mode: "mirror", yerel çalışma alanını kanonik tutar:

• OpenClaw, exec öncesinde yerel çalışma alanını korumalı alanla eşitler.
• OpenClaw, exec sonrasında uzak çalışma alanını yeniden yerel ortama eşitler.
• Dosya araçları korumalı alan köprüsünden geçer ancak turlar arasında doğruluk kaynağı yerel ortam olmaya devam eder.

Geliştirme iş akışları için en uygunudur: OpenClaw dışında yapılan yerel düzenlemeler bir sonraki yürütmede görünür ve korumalı alan Docker arka ucuna benzer şekilde davranır.

Ödünleşim: Her yürütme turunda yükleme ve indirme maliyeti oluşur.

remote

mode: "remote", OpenShell çalışma alanını kanonik hâle getirir:

• İlk korumalı alan oluşturulduğunda OpenClaw, uzak çalışma alanını yerel ortamdan bir kez başlangıç verileriyle doldurur.
• Bundan sonra exec, read, write, edit ve apply_patch doğrudan uzak çalışma alanında işlem yapar. OpenClaw, uzak değişiklikleri yerel ortama eşitlemez.
• İstem sırasında medya okumaları çalışmaya devam eder (dosya/medya araçları korumalı alan köprüsü üzerinden okur).

Uzun süre çalışan aracılar ve CI için en uygunudur: Tur başına ek yük daha düşüktür ve ana makinedeki yerel düzenlemeler uzak durumun sessizce üzerine yazamaz.

Mod seçimi

Yapılandırma başvurusu

Tüm OpenShell yapılandırması plugins.entries.openshell.config altında bulunur:

remoteWorkspaceDir ve remoteAgentWorkspaceDir mutlak yollar olmalı ve yönetilen /sandbox veya /agent kökleri altında kalmalıdır; diğer mutlak yollar reddedilir.

Korumalı alan düzeyindeki ayarlar (mode, scope, workspaceAccess), diğer arka uçlarda olduğu gibi agents.defaults.sandbox altında bulunur. Tam matris için Korumalı Alan Kullanımı sayfasına bakın.

Örnekler

Asgari uzak kurulum

{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "openshell",      },    },  },  plugins: {    entries: {      openshell: {        enabled: true,        config: {          from: "openclaw",          mode: "remote",        },      },    },  },}

GPU ile mirror modu

{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "openshell",        scope: "agent",        workspaceAccess: "rw",      },    },  },  plugins: {    entries: {      openshell: {        enabled: true,        config: {          from: "openclaw",          mode: "mirror",          gpu: true,          providers: ["openai"],          timeoutSeconds: 180,        },      },    },  },}

Özel Gateway ile aracı başına OpenShell

{  agents: {    defaults: {      sandbox: { mode: "off" },    },    list: [      {        id: "researcher",        sandbox: {          mode: "all",          backend: "openshell",          scope: "agent",          workspaceAccess: "rw",        },      },    ],  },  plugins: {    entries: {      openshell: {        enabled: true,        config: {          from: "openclaw",          mode: "remote",          gateway: "lab",          gatewayEndpoint: "https://lab.example",          policy: "strict",        },      },    },  },}

Yaşam döngüsü yönetimi

# Tüm korumalı alan çalışma ortamlarını listele (Docker + OpenShell)openclaw sandbox list # Etkin politikayı inceleopenclaw sandbox explain # Yeniden oluştur (uzak çalışma alanını siler, sonraki kullanımda başlangıç verilerini yeniden aktarır)openclaw sandbox recreate --all

remote modu için yeniden oluşturma özellikle önemlidir: İlgili kapsamın kanonik uzak çalışma alanını siler ve sonraki kullanımda yerel ortamdan yeni bir çalışma alanına başlangıç verileri aktarılır. mirror modunda yerel ortam kanonik kaldığından yeniden oluşturma esas olarak uzak yürütme ortamını sıfırlar.

Şunlardan herhangi birini değiştirdikten sonra yeniden oluşturun:

• agents.defaults.sandbox.backend
• plugins.entries.openshell.config.from
• plugins.entries.openshell.config.mode
• plugins.entries.openshell.config.policy

Güvenlik sağlamlaştırması

Mirror modu dosya sistemi köprüsü, yerel çalışma alanı kökünü sabitler ve her okuma, yazma, dizin oluşturma, kaldırma ve yeniden adlandırma işleminden önce kanonik yolları (realpath aracılığıyla) yeniden denetleyerek yolun ortasındaki sembolik bağlantıları reddeder. Sembolik bağlantı değişimi veya yeniden bağlanan bir çalışma alanı, dosya erişimini yansıtılan ağacın dışına yönlendiremez.

Mevcut sınırlamalar

• Korumalı alan tarayıcısı OpenShell arka ucunda desteklenmez.
• sandbox.docker.binds, OpenShell için geçerli değildir; bağlamalar yapılandırılmışsa korumalı alan oluşturma başarısız olur.
• sandbox.docker.* altındaki Docker'a özgü çalışma zamanı ayarları (env hariç) yalnızca Docker arka ucu için geçerlidir.

Nasıl çalışır?

1. OpenClaw, korumalı alan adı için sandbox get komutunu çalıştırır (yapılandırılmış --gateway/--gateway-endpoint değerleriyle); bu başarısız olursa sandbox create ile bir tane oluşturur ve ayarlandığında --name, --from, --policy, etkinleştirildiğinde --gpu, --auto-providers/--no-auto-providers ve yapılandırılmış her sağlayıcı için bir --provider bayrağı geçirir.
2. OpenClaw, SSH bağlantı ayrıntılarını almak için korumalı alan adıyla sandbox ssh-config komutunu çalıştırır.
3. Çekirdek, SSH yapılandırmasını geçici bir dosyaya yazar ve genel SSH arka ucuyla aynı uzak dosya sistemi köprüsü üzerinden bir SSH oturumu açar.
4. mirror modunda: yürütmeden önce yerelden uzağa eşitler, çalıştırır ve sonrasında yeniden yerel ortama eşitler.
5. remote modunda: oluşturma sırasında başlangıç verilerini bir kez aktarır, ardından doğrudan uzak çalışma alanında işlem yapar.

İlgili konular

• Korumalı Alan Kullanımı - modlar, kapsamlar ve arka uç karşılaştırması
• Korumalı Alan, Araç Politikası ve Yükseltilmiş Yetki Karşılaştırması - engellenen araçlarda hata ayıklama
• Çok Aracılı Korumalı Alan ve Araçlar - aracı başına geçersiz kılmalar
• Korumalı Alan CLI - openclaw sandbox komutları