OpenShell

OpenShell è un backend sandbox gestito per OpenClaw. Invece di eseguire container Docker localmente, OpenClaw delega il ciclo di vita della sandbox alla CLI openshell, che effettua il provisioning di ambienti remoti con esecuzione dei comandi basata su SSH.

Il Plugin OpenShell riutilizza lo stesso trasporto SSH di base e lo stesso bridge del filesystem remoto del backend SSH generico. Aggiunge il ciclo di vita specifico di OpenShell (sandbox create/get/delete, sandbox ssh-config) e una modalità workspace mirror opzionale.

Prerequisiti

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

Avvio rapido

1. Installa e abilita il Plugin, quindi imposta il backend sandbox:

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. Riavvia il Gateway. Al turno successivo dell'agente, OpenClaw crea una sandbox OpenShell e instrada l'esecuzione degli strumenti attraverso di essa.

3. Verifica:

openclaw sandbox listopenclaw sandbox explain

Modalità workspace

Questa è la decisione più importante quando si usa OpenShell.

mirror

Usa plugins.entries.openshell.config.mode: "mirror" quando vuoi che il workspace locale resti canonico.

Comportamento:

• Prima di exec, OpenClaw sincronizza il workspace locale nella sandbox OpenShell.
• Dopo exec, OpenClaw sincronizza il workspace remoto di nuovo nel workspace locale.
• Gli strumenti per i file operano comunque tramite il bridge della sandbox, ma il workspace locale rimane la fonte di verità tra i turni.

Ideale per:

• Modifichi file localmente fuori da OpenClaw e vuoi che tali modifiche siano visibili automaticamente nella sandbox.
• Vuoi che la sandbox OpenShell si comporti il più possibile come il backend Docker.
• Vuoi che il workspace host rifletta le scritture della sandbox dopo ogni turno exec.

Compromesso: costo di sincronizzazione aggiuntivo prima e dopo ogni exec.

remote

Usa plugins.entries.openshell.config.mode: "remote" quando vuoi che il workspace OpenShell diventi canonico.

Comportamento:

• Quando la sandbox viene creata per la prima volta, OpenClaw inizializza una sola volta il workspace remoto dal workspace locale.
• Dopo di che, exec, read, write, edit e apply_patch operano direttamente sul workspace OpenShell remoto.
• OpenClaw non sincronizza le modifiche remote nel workspace locale.
• Le letture dei media al momento del prompt continuano a funzionare perché gli strumenti per file e media leggono tramite il bridge della sandbox.

Ideale per:

• La sandbox deve risiedere principalmente sul lato remoto.
• Vuoi un overhead di sincronizzazione inferiore per turno.
• Non vuoi che modifiche locali sull'host sovrascrivano silenziosamente lo stato della sandbox remota.

Scegliere una modalità

Riferimento di configurazione

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

Le impostazioni a livello di sandbox (mode, scope, workspaceAccess) si configurano sotto agents.defaults.sandbox, come con qualsiasi backend. Consulta Sandboxing 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

Le sandbox OpenShell vengono gestite tramite la normale CLI sandbox:

# 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

Per la modalità remote, recreate è particolarmente importante: elimina il workspace remoto canonico per quello scope. L'uso successivo inizializza un nuovo workspace remoto dal workspace locale.

Per la modalità mirror, recreate reimposta principalmente l'ambiente di esecuzione remoto, perché il workspace locale rimane canonico.

Quando usare recreate

Usa recreate dopo aver modificato uno di questi elementi:

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

openclaw sandbox recreate --all

Rafforzamento della sicurezza

OpenShell fissa il fd della radice del workspace e ricontrolla l'identità della sandbox prima di ogni lettura, quindi scambi di symlink o un workspace rimontato non possono reindirizzare le letture fuori dal workspace remoto previsto.

Limitazioni attuali

• Il browser sandbox non è supportato sul backend OpenShell.
• sandbox.docker.binds non si applica a OpenShell.
• Le impostazioni runtime specifiche di Docker sotto sandbox.docker.* si applicano solo al backend Docker.

Come funziona

1. OpenClaw chiama openshell sandbox create (con i flag --from, --gateway, --policy, --providers, --gpu come configurato).
2. OpenClaw chiama openshell sandbox ssh-config <name> per ottenere i dettagli di connessione SSH della sandbox.
3. Il core scrive la configurazione SSH in un file temporaneo e apre una sessione SSH usando lo stesso bridge del filesystem remoto del backend SSH generico.
4. In modalità mirror: sincronizza dal locale al remoto prima di exec, esegue, poi sincronizza indietro dopo exec.
5. In modalità remote: inizializza una volta alla creazione, poi opera direttamente sul workspace remoto.

Correlati

• Sandboxing -- modalità, scope e confronto dei backend
• Sandbox vs Tool Policy vs Elevated -- debug degli strumenti bloccati
• Multi-Agent Sandbox and Tools -- override per agente
• CLI sandbox -- comandi openclaw sandbox