OpenShell

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

De Plugin hergebruikt hetzelfde SSH-transport en dezelfde externe bestandssysteembridge 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. Bij de volgende agentbeurt maakt OpenClaw een OpenShell- sandbox en leidt het de uitvoering van tools erdoorheen. Controleer 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 sandboxbridge, maar lokaal blijft tussen beurten de bron van waarheid.

Het meest geschikt voor ontwikkelworkflows: lokale wijzigingen buiten OpenClaw verschijnen bij de volgende uitvoering en de sandbox gedraagt zich vrijwel hetzelfde als de Docker-backend.

Nadeel: bij elke uitvoeringsbeurt zijn er upload- en downloadkosten.

remote

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

• Wanneer de sandbox voor het eerst wordt gemaakt, vult OpenClaw de externe werkruimte één keer 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-/mediatools lezen via de sandboxbridge).

Het meest geschikt voor langlopende agents en CI: minder overhead per beurt en lokale wijzigingen 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 hoofdpaden /sandbox of /agent blijven; andere absolute paden worden geweigerd.

Instellingen op sandboxniveau (mode, scope, workspaceAccess) bevinden zich onder agents.defaults.sandbox, net als bij elke backend. 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",        },      },    },  },}

Spiegelmodus 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, wordt bij volgend gebruik opnieuw gevuld)openclaw sandbox recreate --all

Voor de modus remote is opnieuw aanmaken bijzonder belangrijk: hierdoor 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 stelt opnieuw aanmaken voornamelijk de externe uitvoeringsomgeving opnieuw in, omdat lokaal canoniek blijft.

Maak opnieuw aan nadat je een van de volgende zaken hebt gewijzigd:

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

Beveiligingsversterking

De bestandssysteembridge van de spiegelmodus zet de hoofdmap van de lokale werkruimte vast en controleert canonieke paden (via realpath) opnieuw vóór elke lees-, schrijf-, mkdir-, verwijder- en hernoembewerking, waarbij symbolische koppelingen midden in het pad worden geweigerd. Een verwisselde symbolische koppeling of opnieuw gekoppelde werkruimte kan bestandstoegang niet omleiden naar buiten de gespiegelde structuur.

Huidige beperkingen

• De sandboxbrowser wordt niet ondersteund door 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.

Hoe het werkt

1. OpenClaw voert sandbox get uit voor de sandboxnaam (met eventueel 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 bestandssysteembridge als de algemene SSH-backend.
4. In de modus mirror: synchroniseer lokaal naar extern vóór uitvoering, voer uit en synchroniseer daarna terug.
5. In de modus remote: vul één keer bij het aanmaken en werk daarna rechtstreeks in de externe werkruimte.

Gerelateerd

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