OpenShell - OpenClaw

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

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

Riavvia il Gateway. Al turno successivo dell’agente, OpenClaw crea una sandbox OpenShell e instrada l’esecuzione degli strumenti attraverso di essa.
Verifica:

openclaw sandbox list
openclaw 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.

Se modifichi file sull’host fuori da OpenClaw dopo l’inizializzazione iniziale, la sandbox remota non vede tali modifiche. Usa openclaw sandbox recreate per reinizializzarla.

Scegliere una modalità

	`mirror`	`remote`
Workspace canonico	Host locale	OpenShell remoto
Direzione sync	Bidirezionale (ogni exec)	Inizializzazione una tantum
Overhead per turno	Maggiore (upload + download)	Minore (operazioni remote dirette)
Modifiche locali visibili?	Sì, al prossimo exec	No, fino a recreate
Ideale per	Flussi di sviluppo	Agenti di lunga durata, CI

Riferimento di configurazione

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

Chiave	Tipo	Predefinito	Descrizione
`mode`	`"mirror"` o `"remote"`	`"mirror"`	Modalità di sincronizzazione workspace
`command`	`string`	`"openshell"`	Percorso o nome della CLI `openshell`
`from`	`string`	`"openclaw"`	Origine sandbox per la prima creazione
`gateway`	`string`	—	Nome Gateway OpenShell (`--gateway`)
`gatewayEndpoint`	`string`	—	URL endpoint Gateway OpenShell (`--gateway-endpoint`)
`policy`	`string`	—	ID policy OpenShell per la creazione della sandbox
`providers`	`string[]`	`[]`	Nomi dei provider da collegare quando la sandbox viene creata
`gpu`	`boolean`	`false`	Richiede risorse GPU
`autoProviders`	`boolean`	`true`	Passa `--auto-providers` durante la creazione della sandbox
`remoteWorkspaceDir`	`string`	`"/sandbox"`	Workspace scrivibile principale dentro la sandbox
`remoteAgentWorkspaceDir`	`string`	`"/agent"`	Percorso di mount del workspace agente (per accesso in sola lettura)
`timeoutSeconds`	`number`	`120`	Timeout per le operazioni della CLI `openshell`

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 policy
openclaw 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

OpenClaw chiama openshell sandbox create (con i flag --from, --gateway, --policy, --providers, --gpu come configurato).
OpenClaw chiama openshell sandbox ssh-config <name> per ottenere i dettagli di connessione SSH della sandbox.
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.
In modalità mirror: sincronizza dal locale al remoto prima di exec, esegue, poi sincronizza indietro dopo exec.
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

​Prerequisiti

​Avvio rapido

​Modalità workspace

​mirror

​remote

​Scegliere una modalità

​Riferimento di configurazione

​Esempi

​Configurazione remota minima

​Modalità mirror con GPU

​OpenShell per agente con Gateway personalizzato

​Gestione del ciclo di vita

​Quando usare recreate

​Rafforzamento della sicurezza

​Limitazioni attuali

​Come funziona

​Correlati

Prerequisiti

Avvio rapido

Modalità workspace

`mirror`

`remote`

Scegliere una modalità

Riferimento di configurazione

Esempi

Configurazione remota minima

Modalità mirror con GPU

OpenShell per agente con Gateway personalizzato

Gestione del ciclo di vita

Quando usare recreate

Rafforzamento della sicurezza

Limitazioni attuali

Come funziona

Correlati