OpenShell

OpenShell es un backend de sandbox gestionado para OpenClaw. En lugar de ejecutar contenedores Docker localmente, OpenClaw delega el ciclo de vida del sandbox en la CLI openshell, que aprovisiona entornos remotos con ejecución de comandos basada en SSH. El Plugin de OpenShell reutiliza el mismo transporte SSH central y el puente de sistema de archivos remoto que el backend SSH genérico. Añade ciclo de vida específico de OpenShell (sandbox create/get/delete, sandbox ssh-config) y un modo de espacio de trabajo mirror opcional.

Requisitos previos

La CLI openshell instalada y en PATH (o define una ruta personalizada mediante plugins.entries.openshell.config.command)
Una cuenta de OpenShell con acceso a sandbox
OpenClaw Gateway ejecutándose en el host

Inicio rápido

Habilita el Plugin y define el backend de sandbox:

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

Reinicia el Gateway. En el siguiente turno del agente, OpenClaw crea un sandbox de OpenShell y enruta la ejecución de herramientas a través de él.
Verifica:

openclaw sandbox list
openclaw sandbox explain

Modos de espacio de trabajo

Esta es la decisión más importante al usar OpenShell.

`mirror`

Usa plugins.entries.openshell.config.mode: "mirror" cuando quieras que el espacio de trabajo local siga siendo canónico. Comportamiento:

Antes de exec, OpenClaw sincroniza el espacio de trabajo local con el sandbox de OpenShell.
Después de exec, OpenClaw sincroniza el espacio de trabajo remoto de vuelta al espacio de trabajo local.
Las herramientas de archivos siguen operando mediante el puente de sandbox, pero el espacio de trabajo local sigue siendo la fuente de verdad entre turnos.

Ideal para:

Editas archivos localmente fuera de OpenClaw y quieres que esos cambios sean visibles automáticamente en el sandbox.
Quieres que el sandbox de OpenShell se comporte de la forma más parecida posible al backend de Docker.
Quieres que el espacio de trabajo del host refleje las escrituras del sandbox después de cada turno de exec.

Contrapartida: coste de sincronización adicional antes y después de cada exec.

`remote`

Usa plugins.entries.openshell.config.mode: "remote" cuando quieras que el espacio de trabajo de OpenShell pase a ser canónico. Comportamiento:

Cuando se crea el sandbox por primera vez, OpenClaw inicializa una vez el espacio de trabajo remoto a partir del espacio de trabajo local.
Después, exec, read, write, edit y apply_patch operan directamente sobre el espacio de trabajo remoto de OpenShell.
OpenClaw no sincroniza los cambios remotos de vuelta al espacio de trabajo local.
Las lecturas de medios en tiempo de prompt siguen funcionando porque las herramientas de archivos y medios leen mediante el puente de sandbox.

Ideal para:

El sandbox debe residir principalmente en el lado remoto.
Quieres menor sobrecarga de sincronización por turno.
No quieres que las ediciones locales del host sobrescriban silenciosamente el estado del sandbox remoto.

Si editas archivos en el host fuera de OpenClaw después de la inicialización inicial, el sandbox remoto no ve esos cambios. Usa openclaw sandbox recreate para volver a inicializarlo.

Elegir un modo

	`mirror`	`remote`
Espacio de trabajo canónico	Host local	OpenShell remoto
Dirección de sincronización	Bidireccional (cada exec)	Inicialización única
Sobrecarga por turno	Mayor (subida + descarga)	Menor (operaciones remotas directas)
¿Ediciones locales visibles?	Sí, en el siguiente exec	No, hasta recrear
Ideal para	Flujos de desarrollo	Agentes de larga duración, CI

Referencia de configuración

Toda la configuración de OpenShell se encuentra en plugins.entries.openshell.config:

Clave	Tipo	Predeterminado	Descripción
`mode`	`"mirror"` o `"remote"`	`"mirror"`	Modo de sincronización del espacio de trabajo
`command`	`string`	`"openshell"`	Ruta o nombre de la CLI `openshell`
`from`	`string`	`"openclaw"`	Fuente del sandbox para la primera creación
`gateway`	`string`	—	Nombre del gateway de OpenShell (`--gateway`)
`gatewayEndpoint`	`string`	—	URL del endpoint del gateway de OpenShell (`--gateway-endpoint`)
`policy`	`string`	—	ID de política de OpenShell para la creación del sandbox
`providers`	`string[]`	`[]`	Nombres de proveedores que se adjuntan al crear el sandbox
`gpu`	`boolean`	`false`	Solicitar recursos de GPU
`autoProviders`	`boolean`	`true`	Pasar `--auto-providers` durante la creación del sandbox
`remoteWorkspaceDir`	`string`	`"/sandbox"`	Espacio de trabajo principal con escritura dentro del sandbox
`remoteAgentWorkspaceDir`	`string`	`"/agent"`	Ruta de montaje del espacio de trabajo del agente (para acceso de solo lectura)
`timeoutSeconds`	`number`	`120`	Tiempo de espera para operaciones de la CLI `openshell`

Los ajustes de nivel de sandbox (mode, scope, workspaceAccess) se configuran en agents.defaults.sandbox, como con cualquier backend. Consulta Sandboxing para ver la matriz completa.

Ejemplos

Configuración remota mínima

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

Modo 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 por agente con gateway personalizado

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

Gestión del ciclo de vida

Los sandboxes de OpenShell se gestionan mediante la CLI de sandbox normal:

# 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

Para el modo remote, recrear es especialmente importante: elimina el espacio de trabajo remoto canónico de ese ámbito. El siguiente uso inicializa un espacio de trabajo remoto nuevo a partir del espacio de trabajo local. Para el modo mirror, recrear principalmente restablece el entorno de ejecución remoto porque el espacio de trabajo local sigue siendo canónico.

Cuándo recrear

Recrea después de cambiar cualquiera de estos:

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

openclaw sandbox recreate --all

Refuerzo de seguridad

OpenShell fija el fd raíz del espacio de trabajo y vuelve a comprobar la identidad del sandbox antes de cada lectura, por lo que los cambios de enlaces simbólicos o un espacio de trabajo vuelto a montar no pueden redirigir lecturas fuera del espacio de trabajo remoto previsto.

Limitaciones actuales

El navegador de sandbox no es compatible con el backend de OpenShell.
sandbox.docker.binds no se aplica a OpenShell.
Los ajustes de runtime específicos de Docker en sandbox.docker.* solo se aplican al backend de Docker.

Cómo funciona

OpenClaw llama a openshell sandbox create (con los flags --from, --gateway, --policy, --providers, --gpu según la configuración).
OpenClaw llama a openshell sandbox ssh-config <name> para obtener los detalles de conexión SSH del sandbox.
Core escribe la configuración SSH en un archivo temporal y abre una sesión SSH usando el mismo puente de sistema de archivos remoto que el backend SSH genérico.
En modo mirror: sincroniza local a remoto antes de exec, ejecuta y sincroniza de vuelta después de exec.
En modo remote: inicializa una vez al crear y luego opera directamente sobre el espacio de trabajo remoto.

Relacionado

Sandboxing — modos, ámbitos y comparación de backend
Sandbox vs Política de herramientas vs Elevado — depuración de herramientas bloqueadas
Sandbox y herramientas multiagente — anulaciones por agente
CLI de sandbox — comandos openclaw sandbox

Gateway

Remote access

Security

Nodes and media

Web interfaces

Requisitos previos

Inicio rápido

Modos de espacio de trabajo

`mirror`

`remote`

Elegir un modo

Referencia de configuración

Ejemplos

Configuración remota mínima

Modo mirror con GPU

OpenShell por agente con gateway personalizado

Gestión del ciclo de vida

Cuándo recrear

Refuerzo de seguridad

Limitaciones actuales

Cómo funciona

Relacionado

Gateway

Remote access

Security

Nodes and media

Web interfaces

Documentation Index

​Requisitos previos

​Inicio rápido

​Modos de espacio de trabajo

​mirror

​remote

​Elegir un modo

​Referencia de configuración

​Ejemplos

​Configuración remota mínima

​Modo mirror con GPU

​OpenShell por agente con gateway personalizado

​Gestión del ciclo de vida

​Cuándo recrear

​Refuerzo de seguridad

​Limitaciones actuales

​Cómo funciona

​Relacionado

Requisitos previos

Inicio rápido

Modos de espacio de trabajo

`mirror`

`remote`

Elegir un modo

Referencia de configuración

Ejemplos

Configuración remota mínima

Modo mirror con GPU

OpenShell por agente con gateway personalizado

Gestión del ciclo de vida

Cuándo recrear

Refuerzo de seguridad

Limitaciones actuales

Cómo funciona

Relacionado