> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/tr/gateway/sandboxing#ssh-backend) 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:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw plugins install @openclaw/openshell-sandbox
```

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw sandbox list
openclaw 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.

<Warning>
  İlk başlatmadan sonra ana makinede OpenClaw dışında dosyaları düzenlerseniz, uzak sandbox bu değişiklikleri **görmez**. Yeniden başlatmak için `openclaw sandbox recreate` kullanın.
</Warning>

### Mod seçimi

|                                    | `mirror`                        | `remote`                            |
| ---------------------------------- | ------------------------------- | ----------------------------------- |
| **Esas çalışma alanı**             | Yerel ana makine                | Uzak OpenShell                      |
| **Eşitleme yönü**                  | Çift yönlü (her exec)           | Bir kerelik başlatma                |
| **Tur başına ek yük**              | Daha yüksek (yükleme + indirme) | Daha düşük (doğrudan uzak işlemler) |
| **Yerel düzenlemeler görünür mü?** | Evet, sonraki exec'te           | Hayır, yeniden oluşturulana kadar   |
| **En uygun olduğu durum**          | Geliştirme iş akışları          | Uzun süre çalışan ajanlar, CI       |

## Yapılandırma başvurusu

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

| Anahtar                   | Tür                        | Varsayılan    | Açıklama                                                  |
| ------------------------- | -------------------------- | ------------- | --------------------------------------------------------- |
| `mode`                    | `"mirror"` veya `"remote"` | `"mirror"`    | Çalışma alanı eşitleme modu                               |
| `command`                 | `string`                   | `"openshell"` | `openshell` CLI'ının yolu veya adı                        |
| `from`                    | `string`                   | `"openclaw"`  | İlk oluşturma için sandbox kaynağı                        |
| `gateway`                 | `string`                   | —             | OpenShell gateway adı (`--gateway`)                       |
| `gatewayEndpoint`         | `string`                   | —             | OpenShell gateway uç nokta URL'si (`--gateway-endpoint`)  |
| `policy`                  | `string`                   | —             | Sandbox oluşturma için OpenShell politika kimliği         |
| `providers`               | `string[]`                 | `[]`          | Sandbox oluşturulduğunda eklenecek sağlayıcı adları       |
| `gpu`                     | `boolean`                  | `false`       | GPU kaynakları iste                                       |
| `autoProviders`           | `boolean`                  | `true`        | Sandbox oluşturma sırasında `--auto-providers` geçir      |
| `remoteWorkspaceDir`      | `string`                   | `"/sandbox"`  | Sandbox içindeki birincil yazılabilir çalışma alanı       |
| `remoteAgentWorkspaceDir` | `string`                   | `"/agent"`    | Ajan çalışma alanı bağlama yolu (salt okunur erişim için) |
| `timeoutSeconds`          | `number`                   | `120`         | `openshell` CLI işlemleri için zaman aşımı                |

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](/tr/gateway/sandboxing) bölümüne bakın.

## Örnekler

### Minimal uzak kurulum

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote",
        },
      },
    },
  },
}
```

### GPU ile mirror modu

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# List all sandbox runtimes (Docker + OpenShell)
openclaw sandbox list

# Inspect effective policy
openclaw 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`

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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](/tr/gateway/sandboxing) -- modlar, kapsamlar ve arka uç karşılaştırması
* [Sandbox ile Araç Politikası ile Elevated Karşılaştırması](/tr/gateway/sandbox-vs-tool-policy-vs-elevated) -- engellenen araçlarda hata ayıklama
* [Çok Ajanlı Sandbox ve Araçlar](/tr/tools/multi-agent-sandbox-tools) -- ajan başına geçersiz kılmalar
* [Sandbox CLI](/tr/cli/sandbox) -- `openclaw sandbox` komutları