OpenShell

OpenShell is een beheerde sandbox-backend voor OpenClaw. In plaats van Docker containers lokaal uit te voeren, delegeert OpenClaw de levenscyclus van de sandbox aan de openshell CLI, die externe omgevingen inricht met SSH-gebaseerde opdrachtuitvoering.

De OpenShell-Plugin hergebruikt hetzelfde kern-SSH-transport en dezelfde externe bestandssysteembrug als de generieke SSH-backend. Deze voegt OpenShell-specifieke levenscyclus toe (sandbox create/get/delete, sandbox ssh-config) en een optionele mirror-werkruimtemodus.

Vereisten

• OpenShell-Plugin geïnstalleerd (openclaw plugins install @openclaw/openshell-sandbox)
• De openshell CLI geïnstalleerd en beschikbaar op PATH (of stel een aangepast pad in via plugins.entries.openshell.config.command)
• Een OpenShell-account met sandbox-toegang
• OpenClaw Gateway actief op de host

Snel starten

1. Installeer en schakel de Plugin in en stel daarna de sandbox-backend in:

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. Herstart de Gateway. Bij de volgende agentbeurt maakt OpenClaw een OpenShell- sandbox aan en routeert het tooluitvoering erdoorheen.

3. Verifieer:

openclaw sandbox listopenclaw sandbox explain

Werkruimtemodi

Dit is de belangrijkste beslissing bij het gebruik van OpenShell.

mirror

Gebruik plugins.entries.openshell.config.mode: "mirror" wanneer je wilt dat de lokale werkruimte canoniek blijft.

Gedrag:

• Vóór exec synchroniseert OpenClaw de lokale werkruimte naar de OpenShell-sandbox.
• Na exec synchroniseert OpenClaw de externe werkruimte terug naar de lokale werkruimte.
• Bestandstools werken nog steeds via de sandboxbrug, maar de lokale werkruimte blijft tussen beurten de bron van waarheid.

Het meest geschikt voor:

• Je bewerkt bestanden lokaal buiten OpenClaw en wilt dat die wijzigingen automatisch zichtbaar zijn in de sandbox.
• Je wilt dat de OpenShell-sandbox zich zoveel mogelijk gedraagt als de Docker-backend.
• Je wilt dat de hostwerkruimte sandboxschrijfacties weergeeft na elke exec-beurt.

Afweging: extra synchronisatiekosten vóór en na elke exec.

remote

Gebruik plugins.entries.openshell.config.mode: "remote" wanneer je wilt dat de OpenShell-werkruimte canoniek wordt.

Gedrag:

• Wanneer de sandbox voor het eerst wordt aangemaakt, vult OpenClaw de externe werkruimte één keer vanuit de lokale werkruimte.
• Daarna werken exec, read, write, edit en apply_patch rechtstreeks op de externe OpenShell-werkruimte.
• OpenClaw synchroniseert externe wijzigingen niet terug naar de lokale werkruimte.
• Media-lezingen tijdens prompts blijven werken, omdat bestands- en mediatools via de sandboxbrug lezen.

Het meest geschikt voor:

• De sandbox moet primair aan de externe kant leven.
• Je wilt lagere synchronisatie-overhead per beurt.
• Je wilt niet dat lokale bewerkingen op de host stilzwijgend externe sandboxstatus overschrijven.

Een modus kiezen

Configuratiereferentie

Alle OpenShell-configuratie staat onder plugins.entries.openshell.config:

Sandboxinstellingen op niveau (mode, scope, workspaceAccess) worden geconfigureerd onder agents.defaults.sandbox, zoals bij elke backend. Zie Sandboxing voor de volledige matrix.

Voorbeelden

Minimale externe setup

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

Mirror-modus met 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 agent met aangepaste Gateway

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

Levenscyclusbeheer

OpenShell-sandboxes worden beheerd via de normale sandbox-CLI:

# 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

Voor remote-modus is opnieuw aanmaken extra belangrijk: dit verwijdert de canonieke externe werkruimte voor die scope. Het volgende gebruik vult een nieuwe externe werkruimte vanuit de lokale werkruimte.

Voor mirror-modus reset opnieuw aanmaken vooral de externe uitvoeringsomgeving, omdat de lokale werkruimte canoniek blijft.

Wanneer opnieuw aanmaken

Maak opnieuw aan na het wijzigen van een van deze:

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

openclaw sandbox recreate --all

Beveiligingsversterking

OpenShell pint de fd van de werkruimteroot en controleert de sandboxidentiteit opnieuw vóór elke leesactie, zodat symlinkwissels of een opnieuw gekoppelde werkruimte leesacties niet buiten de bedoelde externe werkruimte kunnen omleiden.

Huidige beperkingen

• Sandboxbrowser wordt niet ondersteund op de OpenShell-backend.
• sandbox.docker.binds is niet van toepassing op OpenShell.
• Docker-specifieke runtimeknoppen onder sandbox.docker.* zijn alleen van toepassing op de Docker- backend.

Hoe het werkt

1. OpenClaw roept openshell sandbox create aan (met --from, --gateway, --policy, --providers, --gpu-flags zoals geconfigureerd).
2. OpenClaw roept openshell sandbox ssh-config <name> aan om SSH-verbindingsdetails voor de sandbox op te halen.
3. Core schrijft de SSH-configuratie naar een tijdelijk bestand en opent een SSH-sessie met dezelfde externe bestandssysteembrug als de generieke SSH-backend.
4. In mirror-modus: synchroniseer lokaal naar extern vóór exec, voer uit, synchroniseer terug na exec.
5. In remote-modus: vul één keer bij aanmaak en werk daarna rechtstreeks op de externe werkruimte.

Gerelateerd

• Sandboxing -- modi, scopes en backendvergelijking
• Sandbox versus toolbeleid versus Elevated -- geblokkeerde tools debuggen
• Multi-agent-sandbox en tools -- overschrijvingen per agent
• Sandbox-CLI -- openclaw sandbox-opdrachten