OpenShell

OpenShell is een beheerde sandboxbackend: in plaats van Docker-containers lokaal uit te voeren, delegeert OpenClaw de levenscyclus van de sandbox aan de openshell-CLI, die externe omgevingen inricht en opdrachten via SSH uitvoert.

De Plugin hergebruikt hetzelfde SSH-transport en dezelfde externe bestandssysteembrug als de algemene SSH-backend en voegt de OpenShell-levenscyclus (sandbox create/get/delete/ssh-config) plus een optionele mirror-modus voor werkruimtesynchronisatie toe.

Vereisten

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

Snel aan de slag

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

Start de Gateway opnieuw. Tijdens de volgende agentbeurt maakt OpenClaw een OpenShell-sandbox aan en leidt het de uitvoering van tools erdoorheen. Verifieer dit met:

openclaw sandbox listopenclaw sandbox explain

Werkruimtemodi

Dit is de belangrijkste keuze voor OpenShell.

mirror (standaard)

plugins.entries.openshell.config.mode: "mirror" houdt de lokale werkruimte canoniek:

• Vóór exec synchroniseert OpenClaw de lokale werkruimte naar de sandbox.
• Na exec synchroniseert OpenClaw de externe werkruimte terug naar lokaal.
• Bestandstools lopen via de sandboxbrug, maar lokaal blijft tussen beurten de gezaghebbende bron.

Het meest geschikt voor ontwikkelworkflows: lokale bewerkingen buiten OpenClaw worden bij de volgende uitvoering zichtbaar en de sandbox gedraagt zich ongeveer als de Docker-backend.

Afweging: kosten voor uploaden en downloaden bij elke uitvoeringsbeurt.

remote

mode: "remote" maakt de OpenShell-werkruimte canoniek:

• Wanneer de sandbox voor het eerst wordt aangemaakt, vult OpenClaw de externe werkruimte eenmalig vanuit de lokale werkruimte.
• Daarna werken exec, read, write, edit en apply_patch rechtstreeks op de externe werkruimte. OpenClaw synchroniseert externe wijzigingen niet terug naar lokaal.
• Het lezen van media tijdens het opstellen van prompts blijft werken (bestands- en mediatools lezen via de sandboxbrug).

Het meest geschikt voor langlopende agents en CI: lagere overhead per beurt en lokale bewerkingen op de host kunnen de externe status niet ongemerkt overschrijven.

Een modus kiezen

Configuratiereferentie

Alle OpenShell-configuratie bevindt zich onder plugins.entries.openshell.config:

remoteWorkspaceDir en remoteAgentWorkspaceDir moeten absolute paden zijn en binnen de beheerde hoofdmappen /sandbox of /agent blijven; andere absolute paden worden geweigerd.

Instellingen op sandboxniveau (mode, scope, workspaceAccess) bevinden zich net als bij elke backend onder agents.defaults.sandbox. Zie Sandboxing voor de volledige matrix.

Voorbeelden

Minimale externe configuratie

{  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

# Alle sandboxruntimes weergeven (Docker + OpenShell)openclaw sandbox list # Effectief beleid inspecterenopenclaw sandbox explain # Opnieuw aanmaken (verwijdert externe werkruimte, vult deze opnieuw bij volgend gebruik)openclaw sandbox recreate --all

Voor de modus remote is opnieuw aanmaken bijzonder belangrijk: hiermee wordt de canonieke externe werkruimte voor dat bereik verwijderd en bij het volgende gebruik wordt een nieuwe werkruimte vanuit lokaal gevuld. Voor de modus mirror wordt met opnieuw aanmaken voornamelijk de externe uitvoeringsomgeving hersteld, omdat lokaal canoniek blijft.

Maak opnieuw aan na het wijzigen van een van de volgende instellingen:

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

Beveiligingsversterking

De bestandssysteembrug in mirror-modus verankert de hoofdmap van de lokale werkruimte en controleert vóór elke lees-, schrijf-, mkdir-, verwijder- en hernoembewerking opnieuw de canonieke paden (via realpath), waarbij symbolische koppelingen midden in een pad worden geweigerd. Het omwisselen van een symbolische koppeling of opnieuw koppelen van de werkruimte kan bestandstoegang niet omleiden naar buiten de gespiegelde boomstructuur.

Huidige beperkingen

• De sandboxbrowser wordt niet ondersteund op de OpenShell-backend.
• sandbox.docker.binds is niet van toepassing op OpenShell; het aanmaken van de sandbox mislukt als koppelingen zijn geconfigureerd.
• Docker-specifieke runtimeopties onder sandbox.docker.* (behalve env) zijn alleen van toepassing op de Docker-backend.

Werking

1. OpenClaw voert sandbox get uit voor de sandboxnaam (met eventuele geconfigureerde --gateway/--gateway-endpoint); als dat mislukt, maakt het er een aan met sandbox create, waarbij --name, --from, --policy indien ingesteld, --gpu indien ingeschakeld, --auto-providers/--no-auto-providers en één --provider-vlag per geconfigureerde provider worden doorgegeven.
2. OpenClaw voert sandbox ssh-config uit voor de sandboxnaam om de SSH-verbindingsgegevens op te halen.
3. De kern schrijft de SSH-configuratie naar een tijdelijk bestand en opent een SSH-sessie via dezelfde externe bestandssysteembrug als de algemene SSH-backend.
4. In de modus mirror: synchroniseer lokaal naar extern vóór de uitvoering, voer uit en synchroniseer daarna terug.
5. In de modus remote: vul eenmalig bij het aanmaken en werk daarna rechtstreeks op de externe werkruimte.

Gerelateerd

• Sandboxing - modi, bereiken en vergelijking van backends
• Sandbox versus toolbeleid versus verhoogde rechten - geblokkeerde tools opsporen
• Sandbox en tools voor meerdere agents - overschrijvingen per agent
• Sandbox-CLI - openclaw sandbox-opdrachten