OpenShell

OpenShell, OpenClaw için yönetilen bir sandbox arka ucudur. OpenClaw, Docker kapsayıcılarını yerelde çalıştırmak yerine sandbox yaşam döngüsünü SSH tabanlı komut yürütme ile uzak ortamlar sağlayan openshell CLI'ına devreder.

OpenShell Plugin'i, genel SSH arka ucu ile aynı çekirdek SSH aktarımını ve uzak dosya sistemi köprüsünü yeniden kullanır. OpenShell'e özgü yaşam döngüsü (sandbox create/get/delete, sandbox ssh-config) ve isteğe bağlı bir mirror çalışma alanı modu ekler.

Önkoşullar

• OpenShell Plugin'i kurulu (openclaw plugins install @openclaw/openshell-sandbox)
• openshell CLI'ı kurulu ve PATH üzerinde (veya plugins.entries.openshell.config.command ile özel bir yol ayarlayın)
• Sandbox erişimi olan bir OpenShell hesabı
• Ana makinede çalışan OpenClaw Gateway

Hızlı başlangıç

1. Plugin'i kurup etkinleştirin, ardından sandbox arka ucunu ayarlayın:

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

2. Gateway'i yeniden başlatın. Sonraki ajan turunda OpenClaw bir OpenShell sandbox'ı oluşturur ve araç yürütmeyi bunun üzerinden yönlendirir.

3. Doğrulayın:

openclaw sandbox listopenclaw sandbox explain

Çalışma alanı modları

OpenShell kullanırken en önemli karar budur.

mirror

Yerel çalışma alanının esas kaynak olarak kalmasını istediğinizde plugins.entries.openshell.config.mode: "mirror" kullanın.

Davranış:

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

En uygun olduğu durumlar:

• Dosyaları OpenClaw dışında yerelde düzenliyorsunuz ve bu değişikliklerin sandbox'ta otomatik olarak görünmesini istiyorsunuz.
• OpenShell sandbox'ının mümkün olduğunca Docker arka ucu gibi davranmasını istiyorsunuz.
• Ana makine çalışma alanının her exec turundan sonra sandbox yazmalarını yansıtmasını istiyorsunuz.

Ödün: her exec öncesinde ve sonrasında ek eşitleme maliyeti.

remote

OpenShell çalışma alanının esas kaynak olmasını istediğinizde plugins.entries.openshell.config.mode: "remote" kullanın.

Davranış:

• Sandbox ilk kez oluşturulduğunda OpenClaw uzak çalışma alanını yerel çalışma alanından bir kez başlatır.
• Bundan sonra exec, read, write, edit ve apply_patch doğrudan uzak OpenShell çalışma alanına karşı çalışır.
• OpenClaw uzak değişiklikleri yerel çalışma alanına geri eşitlemez.
• Komut istemi zamanındaki medya okumaları yine çalışır, çünkü dosya ve medya araçları sandbox köprüsü üzerinden okur.

En uygun olduğu durumlar:

• Sandbox öncelikle uzak tarafta yaşamalıdır.
• Tur başına eşitleme ek yükünün daha düşük olmasını istiyorsunuz.
• Ana makine yerelindeki düzenlemelerin uzak sandbox durumunu sessizce ezmesini istemiyorsunuz.

Mod seçimi

Yapılandırma başvurusu

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

Sandbox düzeyi ayarlar (mode, scope, workspaceAccess) diğer arka uçlarda olduğu gibi agents.defaults.sandbox altında yapılandırılır. Tam matris için Sandboxlama bölümüne bakın.

Örnekler

Minimal 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 ajan 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

OpenShell sandbox'ları normal sandbox CLI'ı üzerinden yönetilir:

# List all sandbox runtimes (Docker + OpenShell)openclaw sandbox list # Inspect effective policyopenclaw sandbox explain # Recreate (deletes remote workspace, re-seeds on next use)openclaw sandbox recreate --all

remote modu için yeniden oluşturma özellikle önemlidir: bu kapsamın esas uzak çalışma alanını siler. Sonraki kullanım, yerel çalışma alanından yeni bir uzak çalışma alanı başlatır.

mirror modu için yeniden oluşturma çoğunlukla uzak yürütme ortamını sıfırlar, çünkü yerel çalışma alanı esas kaynak olarak kalır.

Ne zaman yeniden oluşturmalı

Bunlardan 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

openclaw sandbox recreate --all

Güvenlik sertleştirme

OpenShell çalışma alanı kök fd'sini sabitler ve her okumadan önce sandbox kimliğini yeniden denetler; böylece sembolik bağlantı değişimleri veya yeniden bağlanmış bir çalışma alanı okumaları hedeflenen uzak çalışma alanının dışına yönlendiremez.

Mevcut sınırlamalar

• Sandbox tarayıcısı OpenShell arka ucunda desteklenmez.
• sandbox.docker.binds OpenShell için geçerli değildir.
• sandbox.docker.* altındaki Docker'a özgü çalışma zamanı ayarları yalnızca Docker arka ucu için geçerlidir.

Nasıl çalışır

1. OpenClaw openshell sandbox create çağırır (yapılandırıldığı şekilde --from, --gateway, --policy, --providers, --gpu bayraklarıyla).
2. OpenClaw sandbox için SSH bağlantı ayrıntılarını almak üzere openshell sandbox ssh-config <name> çağı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ünü kullanarak bir SSH oturumu açar.
4. mirror modunda: exec öncesi yerelden uzağa eşitle, çalıştır, exec sonrası geri eşitle.
5. remote modunda: oluşturma sırasında bir kez başlat, ardından doğrudan uzak çalışma alanı üzerinde çalış.

İlgili

• Sandboxlama -- modlar, kapsamlar ve arka uç karşılaştırması
• Sandbox ile Araç Politikası ile Elevated Karşılaştırması -- engellenen araçlarda hata ayıklama
• Çok Ajanlı Sandbox ve Araçlar -- ajan başına geçersiz kılmalar
• Sandbox CLI -- openclaw sandbox komutları