OpenShell

OpenShell adalah backend sandbox terkelola: alih-alih menjalankan kontainer Docker secara lokal, OpenClaw mendelegasikan siklus hidup sandbox ke CLI openshell, yang menyediakan lingkungan jarak jauh dan menjalankan perintah melalui SSH.

Plugin ini menggunakan kembali transportasi SSH dan jembatan sistem berkas jarak jauh yang sama dengan backend SSH generik, serta menambahkan siklus hidup OpenShell (sandbox create/get/delete/ssh-config) dan mode sinkronisasi ruang kerja mirror opsional.

Prasyarat

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

Mulai cepat

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 dengan:

openclaw sandbox listopenclaw sandbox explain

Mode ruang kerja

Ini adalah keputusan OpenShell yang paling penting.

mirror (bawaan)

plugins.entries.openshell.config.mode: "mirror" mempertahankan ruang kerja lokal sebagai sumber kanonis:

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

Paling cocok untuk alur kerja pengembangan: perubahan lokal di luar OpenClaw akan muncul pada exec berikutnya, dan perilaku sandbox mendekati backend Docker.

Konsekuensi: biaya unggah + unduh pada setiap giliran exec.

remote

mode: "remote" menjadikan ruang kerja OpenShell sebagai sumber kanonis:

• 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 pada ruang kerja jarak jauh. OpenClaw tidak menyinkronkan perubahan jarak jauh kembali ke lokal.
• Pembacaan media saat penyusunan prompt tetap berfungsi (alat berkas/media membaca melalui jembatan sandbox).

Paling cocok untuk agen yang berjalan lama dan CI: overhead per giliran lebih rendah, dan perubahan lokal pada host tidak dapat menimpa keadaan jarak jauh secara diam-diam.

Memilih mode

Referensi konfigurasi

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

remoteWorkspaceDir dan remoteAgentWorkspaceDir harus berupa jalur absolut dan tetap berada di bawah akar terkelola /sandbox atau /agent; jalur absolut lainnya ditolak.

Pengaturan tingkat sandbox (mode, scope, workspaceAccess) berada di bawah agents.defaults.sandbox seperti backend lainnya. 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 khusus

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

Pengelolaan siklus hidup

# Cantumkan semua runtime sandbox (Docker + OpenShell)openclaw sandbox list # Periksa kebijakan yang berlakuopenclaw sandbox explain # Buat ulang (menghapus ruang kerja jarak jauh, diisi ulang saat penggunaan berikutnya)openclaw sandbox recreate --all

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

Buat ulang setelah mengubah salah satu dari:

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

Penguatan keamanan

Jembatan sistem berkas mode mirror menyematkan akar ruang kerja lokal dan memeriksa ulang jalur kanonis (melalui realpath) sebelum setiap operasi baca, tulis, mkdir, hapus, dan ganti nama, serta menolak symlink di tengah jalur. Pertukaran symlink atau ruang kerja yang dipasang ulang tidak dapat mengalihkan akses berkas ke luar pohon yang dicerminkan.

Batasan saat ini

• Browser sandbox tidak didukung pada backend OpenShell.
• sandbox.docker.binds tidak berlaku untuk OpenShell; pembuatan sandbox gagal jika bind dikonfigurasi.
• Opsi runtime khusus Docker di bawah sandbox.docker.* (selain env) hanya berlaku untuk backend Docker.

Cara kerjanya

1. OpenClaw menjalankan sandbox get untuk nama sandbox (dengan --gateway/--gateway-endpoint yang dikonfigurasi); jika gagal, OpenClaw membuatnya dengan sandbox create, meneruskan --name, --from, --policy jika diatur, --gpu jika diaktifkan, --auto-providers/--no-auto-providers, dan satu flag --provider untuk setiap penyedia yang dikonfigurasi.
2. OpenClaw menjalankan sandbox ssh-config untuk nama sandbox guna mengambil detail koneksi SSH.
3. Inti menulis konfigurasi SSH ke berkas sementara dan membuka sesi SSH melalui jembatan sistem berkas jarak jauh yang sama dengan backend SSH generik.
4. Dalam mode mirror: sinkronkan lokal ke jarak jauh sebelum exec, jalankan, lalu sinkronkan kembali setelahnya.
5. Dalam mode remote: isi satu kali saat pembuatan, lalu operasikan langsung pada ruang kerja jarak jauh.

Terkait

• Sandboxing - mode, cakupan, dan perbandingan backend
• Sandbox vs Kebijakan Alat vs Ditingkatkan - men-debug alat yang diblokir
• Sandbox dan Alat Multi-Agen - penggantian khusus per agen
• CLI Sandbox - perintah openclaw sandbox