OpenShell - OpenClaw

OpenShell adalah backend sandbox terkelola untuk OpenClaw. Alih-alih menjalankan kontainer Docker secara lokal, OpenClaw mendelegasikan siklus hidup sandbox ke CLI openshell, yang menyediakan lingkungan jarak jauh dengan eksekusi perintah berbasis SSH. Plugin OpenShell menggunakan kembali transport SSH inti yang sama dan jembatan sistem berkas jarak jauh yang sama seperti backend SSH generik. Plugin ini menambahkan siklus hidup khusus OpenShell (sandbox create/get/delete, sandbox ssh-config) dan mode ruang kerja mirror opsional.

Prasyarat

Plugin OpenShell terinstal (openclaw plugins install @openclaw/openshell-sandbox)
CLI openshell terinstal dan tersedia di PATH (atau tetapkan jalur kustom melalui plugins.entries.openshell.config.command)
Akun OpenShell dengan akses sandbox
OpenClaw Gateway berjalan di host

Mulai cepat

Instal dan aktifkan Plugin, lalu tetapkan backend sandbox:

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

Mulai ulang Gateway. Pada giliran agen berikutnya, OpenClaw membuat sandbox OpenShell dan merutekan eksekusi alat melaluinya.
Verifikasi:

openclaw sandbox list
openclaw sandbox explain

Mode ruang kerja

Ini adalah keputusan terpenting saat menggunakan OpenShell.

`mirror`

Gunakan plugins.entries.openshell.config.mode: "mirror" saat Anda ingin ruang kerja lokal tetap menjadi kanonis. Perilaku:

Sebelum exec, OpenClaw menyinkronkan ruang kerja lokal ke sandbox OpenShell.
Setelah exec, OpenClaw menyinkronkan ruang kerja jarak jauh kembali ke ruang kerja lokal.
Alat berkas tetap beroperasi melalui jembatan sandbox, tetapi ruang kerja lokal tetap menjadi sumber kebenaran di antara giliran.

Paling cocok untuk:

Anda mengedit berkas secara lokal di luar OpenClaw dan ingin perubahan tersebut terlihat di sandbox secara otomatis.
Anda ingin sandbox OpenShell berperilaku semirip mungkin dengan backend Docker.
Anda ingin ruang kerja host mencerminkan penulisan sandbox setelah setiap giliran exec.

Tradeoff: biaya sinkronisasi tambahan sebelum dan setelah setiap exec.

`remote`

Gunakan plugins.entries.openshell.config.mode: "remote" saat Anda ingin ruang kerja OpenShell menjadi kanonis. Perilaku:

Saat sandbox pertama kali dibuat, OpenClaw mengisi ruang kerja jarak jauh dari ruang kerja lokal satu kali.
Setelah itu, exec, read, write, edit, dan apply_patch beroperasi langsung terhadap ruang kerja OpenShell jarak jauh.
OpenClaw tidak menyinkronkan perubahan jarak jauh kembali ke ruang kerja lokal.
Pembacaan media pada waktu prompt tetap berfungsi karena alat berkas dan media membaca melalui jembatan sandbox.

Paling cocok untuk:

Sandbox seharusnya terutama berada di sisi jarak jauh.
Anda ingin overhead sinkronisasi per giliran yang lebih rendah.
Anda tidak ingin pengeditan lokal host diam-diam menimpa status sandbox jarak jauh.

Jika Anda mengedit berkas di host di luar OpenClaw setelah pengisian awal, sandbox jarak jauh tidak melihat perubahan tersebut. Gunakan openclaw sandbox recreate untuk mengisi ulang.

Memilih mode

	`mirror`	`remote`
Ruang kerja kanonis	Host lokal	OpenShell jarak jauh
Arah sinkronisasi	Dua arah (setiap exec)	Pengisian satu kali
Overhead per giliran	Lebih tinggi (unggah + unduh)	Lebih rendah (operasi jarak jauh langsung)
Pengeditan lokal terlihat?	Ya, pada exec berikutnya	Tidak, hingga dibuat ulang
Paling cocok untuk	Alur kerja pengembangan	Agen berjalan lama, CI

Referensi konfigurasi

Semua konfigurasi OpenShell berada di bawah plugins.entries.openshell.config:

Kunci	Tipe	Default	Deskripsi
`mode`	`"mirror"` or `"remote"`	`"mirror"`	Mode sinkronisasi ruang kerja
`command`	`string`	`"openshell"`	Jalur atau nama CLI `openshell`
`from`	`string`	`"openclaw"`	Sumber sandbox untuk pembuatan pertama kali
`gateway`	`string`	—	Nama Gateway OpenShell (`--gateway`)
`gatewayEndpoint`	`string`	—	URL endpoint Gateway OpenShell (`--gateway-endpoint`)
`policy`	`string`	—	ID kebijakan OpenShell untuk pembuatan sandbox
`providers`	`string[]`	`[]`	Nama penyedia yang dilampirkan saat sandbox dibuat
`gpu`	`boolean`	`false`	Meminta sumber daya GPU
`autoProviders`	`boolean`	`true`	Meneruskan `--auto-providers` selama pembuatan sandbox
`remoteWorkspaceDir`	`string`	`"/sandbox"`	Ruang kerja utama yang dapat ditulis di dalam sandbox
`remoteAgentWorkspaceDir`	`string`	`"/agent"`	Jalur mount ruang kerja agen (untuk akses hanya baca)
`timeoutSeconds`	`number`	`120`	Timeout untuk operasi CLI `openshell`

Pengaturan tingkat sandbox (mode, scope, workspaceAccess) dikonfigurasi di bawah agents.defaults.sandbox seperti backend lain. Lihat Sandboxing untuk matriks lengkap.

Contoh

Penyiapan remote minimal

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

Mode mirror dengan GPU

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

OpenShell per agen dengan Gateway kustom

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

Manajemen siklus hidup

Sandbox OpenShell dikelola melalui CLI sandbox normal:

# 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

Untuk mode remote, pembuatan ulang sangat penting: ini menghapus ruang kerja jarak jauh kanonis untuk cakupan tersebut. Penggunaan berikutnya mengisi ruang kerja jarak jauh baru dari ruang kerja lokal. Untuk mode mirror, pembuatan ulang terutama mereset lingkungan eksekusi jarak jauh karena ruang kerja lokal tetap kanonis.

Kapan membuat ulang

Buat ulang setelah mengubah salah satu dari berikut:

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

openclaw sandbox recreate --all

Penguatan keamanan

OpenShell mengunci fd root ruang kerja dan memeriksa ulang identitas sandbox sebelum setiap pembacaan, sehingga penggantian symlink atau ruang kerja yang di-mount ulang tidak dapat mengalihkan pembacaan keluar dari ruang kerja jarak jauh yang dimaksud.

Batasan saat ini

Browser sandbox tidak didukung pada backend OpenShell.
sandbox.docker.binds tidak berlaku untuk OpenShell.
Knob runtime khusus Docker di bawah sandbox.docker.* hanya berlaku untuk backend Docker.

Cara kerjanya

OpenClaw memanggil openshell sandbox create (dengan flag --from, --gateway, --policy, --providers, --gpu sesuai konfigurasi).
OpenClaw memanggil openshell sandbox ssh-config <name> untuk mendapatkan detail koneksi SSH untuk sandbox.
Core menulis konfigurasi SSH ke berkas sementara dan membuka sesi SSH menggunakan jembatan sistem berkas jarak jauh yang sama seperti backend SSH generik.
Dalam mode mirror: sinkronkan lokal ke jarak jauh sebelum exec, jalankan, sinkronkan kembali setelah exec.
Dalam mode remote: isi sekali saat create, lalu beroperasi langsung pada ruang kerja jarak jauh.

Terkait

Sandboxing — mode, cakupan, dan perbandingan backend
Sandbox vs Kebijakan Alat vs Elevated — men-debug alat yang diblokir
Sandbox dan Alat Multi-Agen — override per agen
CLI Sandbox — perintah openclaw sandbox

​Prasyarat

​Mulai cepat

​Mode ruang kerja

​mirror

​remote

​Memilih mode

​Referensi konfigurasi

​Contoh

​Penyiapan remote minimal

​Mode mirror dengan GPU

​OpenShell per agen dengan Gateway kustom

​Manajemen siklus hidup

​Kapan membuat ulang

​Penguatan keamanan

​Batasan saat ini

​Cara kerjanya

​Terkait

Prasyarat

Mulai cepat

Mode ruang kerja

`mirror`

`remote`

Memilih mode

Referensi konfigurasi

Contoh

Penyiapan remote minimal

Mode mirror dengan GPU

OpenShell per agen dengan Gateway kustom

Manajemen siklus hidup

Kapan membuat ulang

Penguatan keamanan

Batasan saat ini

Cara kerjanya

Terkait