OpenShell

OpenShell è un backend sandbox gestito: invece di eseguire container Docker localmente, OpenClaw delega il ciclo di vita della sandbox alla CLI openshell, che predispone ambienti remoti ed esegue comandi tramite SSH.

Il plugin riutilizza lo stesso trasporto SSH e lo stesso bridge del filesystem remoto del backend SSH generico e aggiunge la gestione del ciclo di vita di OpenShell (sandbox create/get/delete/ssh-config), oltre a una modalità opzionale mirror per la sincronizzazione dell'area di lavoro.

Prerequisiti

• Plugin OpenShell installato (openclaw plugins install @openclaw/openshell-sandbox)
• CLI openshell disponibile in PATH (oppure un percorso personalizzato tramite plugins.entries.openshell.config.command)
• Un account OpenShell con accesso alle sandbox
• Gateway OpenClaw in esecuzione sull'host

Avvio rapido

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

Riavvia il Gateway. Al turno successivo dell'agente, OpenClaw crea una sandbox OpenShell e vi instrada l'esecuzione degli strumenti. Verifica con:

openclaw sandbox listopenclaw sandbox explain

Modalità dell'area di lavoro

Questa è la decisione più importante relativa a OpenShell.

mirror (predefinita)

plugins.entries.openshell.config.mode: "mirror" mantiene canonica l'area di lavoro locale:

• Prima di exec, OpenClaw sincronizza l'area di lavoro locale nella sandbox.
• Dopo exec, OpenClaw sincronizza nuovamente in locale l'area di lavoro remota.
• Gli strumenti per i file passano attraverso il bridge della sandbox, ma tra un turno e l'altro la copia locale rimane la fonte autorevole.

Ideale per i flussi di lavoro di sviluppo: le modifiche locali effettuate al di fuori di OpenClaw vengono rilevate alla successiva esecuzione e il comportamento della sandbox è simile a quello del backend Docker.

Compromesso: costo di caricamento e scaricamento a ogni turno di esecuzione.

remote

mode: "remote" rende canonica l'area di lavoro OpenShell:

• Alla prima creazione della sandbox, OpenClaw inizializza una sola volta l'area di lavoro remota a partire da quella locale.
• Successivamente, exec, read, write, edit e apply_patch operano direttamente sull'area di lavoro remota. OpenClaw non sincronizza le modifiche remote in locale.
• La lettura dei contenuti multimediali durante la generazione del prompt continua a funzionare (gli strumenti per file e contenuti multimediali leggono tramite il bridge della sandbox).

Ideale per agenti di lunga durata e CI: minore sovraccarico per turno e le modifiche locali sull'host non possono sovrascrivere silenziosamente lo stato remoto.

Scelta della modalità

Riferimento della configurazione

Tutta la configurazione di OpenShell si trova in plugins.entries.openshell.config:

remoteWorkspaceDir e remoteAgentWorkspaceDir devono essere percorsi assoluti e rimanere nelle radici gestite /sandbox o /agent; gli altri percorsi assoluti vengono rifiutati.

Le impostazioni a livello di sandbox (mode, scope, workspaceAccess) si trovano in agents.defaults.sandbox, come per qualsiasi backend. Consulta Gestione delle sandbox per la matrice completa.

Esempi

Configurazione remota minima

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

Modalità mirror con 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 agente con gateway personalizzato

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

Gestione del ciclo di vita

# Elenca tutti i runtime sandbox (Docker + OpenShell)openclaw sandbox list # Esamina la policy effettivaopenclaw sandbox explain # Ricrea (elimina l'area di lavoro remota e la reinizializza all'utilizzo successivo)openclaw sandbox recreate --all

Per la modalità remote, la ricreazione è particolarmente importante: elimina l'area di lavoro remota canonica per l'ambito specificato e, all'utilizzo successivo, ne inizializza una nuova a partire da quella locale. Per la modalità mirror, la ricreazione reimposta principalmente l'ambiente di esecuzione remoto, poiché la copia locale rimane canonica.

Ricrea dopo aver modificato uno dei seguenti elementi:

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

Rafforzamento della sicurezza

Il bridge del filesystem in modalità mirror vincola la radice dell'area di lavoro locale e ricontrolla i percorsi canonici (tramite realpath) prima di ogni lettura, scrittura, creazione di directory, rimozione e rinomina, rifiutando i collegamenti simbolici all'interno del percorso. La sostituzione di un collegamento simbolico o il rimontaggio dell'area di lavoro non possono reindirizzare l'accesso ai file al di fuori dell'albero replicato.

Limitazioni attuali

• Il browser della sandbox non è supportato dal backend OpenShell.
• sandbox.docker.binds non si applica a OpenShell; la creazione della sandbox non riesce se sono configurati dei bind.
• Le opzioni di runtime specifiche di Docker in sandbox.docker.* (tranne env) si applicano solo al backend Docker.

Funzionamento

1. OpenClaw esegue sandbox get per il nome della sandbox (con gli eventuali --gateway/--gateway-endpoint configurati); se l'operazione non riesce, ne crea una con sandbox create, passando --name, --from, --policy quando impostato, --gpu quando abilitato, --auto-providers/--no-auto-providers e un flag --provider per ogni provider configurato.
2. OpenClaw esegue sandbox ssh-config per il nome della sandbox per recuperare i dettagli della connessione SSH.
3. Il core scrive la configurazione SSH in un file temporaneo e apre una sessione SSH tramite lo stesso bridge del filesystem remoto del backend SSH generico.
4. In modalità mirror: sincronizza dal locale al remoto prima dell'esecuzione, esegue il comando, quindi sincronizza nuovamente dal remoto al locale.
5. In modalità remote: inizializza una volta alla creazione, quindi opera direttamente sull'area di lavoro remota.

Argomenti correlati

• Gestione delle sandbox - modalità, ambiti e confronto tra backend
• Sandbox, policy degli strumenti e privilegi elevati - debug degli strumenti bloccati
• Sandbox e strumenti multi-agente - sostituzioni per agente
• CLI della sandbox - comandi openclaw sandbox