OpenShell

OpenShell es un backend de entorno aislado gestionado: en lugar de ejecutar contenedores Docker localmente, OpenClaw delega el ciclo de vida del entorno aislado a la CLI openshell, que aprovisiona entornos remotos y ejecuta comandos mediante SSH.

El plugin reutiliza el mismo transporte SSH y puente del sistema de archivos remoto que el backend SSH genérico, y añade el ciclo de vida de OpenShell (sandbox create/get/delete/ssh-config), además de un modo opcional de sincronización del espacio de trabajo mirror.

Requisitos previos

• Plugin de OpenShell instalado (openclaw plugins install @openclaw/openshell-sandbox)
• CLI openshell en PATH (o una ruta personalizada mediante plugins.entries.openshell.config.command)
• Una cuenta de OpenShell con acceso a entornos aislados
• Gateway de OpenClaw ejecutándose en el host

Inicio rápido

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

Reinicie el Gateway. En el siguiente turno del agente, OpenClaw crea un entorno aislado de OpenShell y dirige a través de él la ejecución de herramientas. Verifíquelo con:

openclaw sandbox listopenclaw sandbox explain

Modos del espacio de trabajo

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

mirror (predeterminado)

plugins.entries.openshell.config.mode: "mirror" mantiene el espacio de trabajo local como canónico:

• Antes de exec, OpenClaw sincroniza el espacio de trabajo local con el entorno aislado.
• Después de exec, OpenClaw vuelve a sincronizar el espacio de trabajo remoto con el local.
• Las herramientas de archivos utilizan el puente del entorno aislado, pero el entorno local sigue siendo la fuente de verdad entre turnos.

Es la mejor opción para flujos de trabajo de desarrollo: las ediciones locales realizadas fuera de OpenClaw aparecen en la siguiente ejecución, y el entorno aislado se comporta de forma similar al backend de Docker.

Desventaja: coste de carga y descarga en cada turno de ejecución.

remote

mode: "remote" hace que el espacio de trabajo de OpenShell sea canónico:

• Durante la primera creación del entorno aislado, OpenClaw inicializa una vez el espacio de trabajo remoto a partir del local.
• A partir de entonces, exec, read, write, edit y apply_patch operan directamente en el espacio de trabajo remoto. OpenClaw no vuelve a sincronizar los cambios remotos con el entorno local.
• La lectura de contenido multimedia al generar el prompt sigue funcionando (las herramientas de archivos y contenido multimedia leen mediante el puente del entorno aislado).

Es la mejor opción para agentes de larga duración y CI: menor sobrecarga por turno y las ediciones locales del host no pueden sobrescribir silenciosamente el estado remoto.

Elección de un modo

Referencia de configuración

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

remoteWorkspaceDir y remoteAgentWorkspaceDir deben ser rutas absolutas y permanecer bajo las raíces gestionadas /sandbox o /agent; las demás rutas absolutas se rechazan.

Los ajustes del entorno aislado (mode, scope, workspaceAccess) se encuentran en agents.defaults.sandbox, como con cualquier backend. Consulte Entornos aislados 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

# Enumerar todos los entornos de ejecución aislados (Docker + OpenShell)openclaw sandbox list # Inspeccionar la política efectivaopenclaw sandbox explain # Volver a crear (elimina el espacio de trabajo remoto y vuelve a inicializarlo en el siguiente uso)openclaw sandbox recreate --all

En el modo remote, volver a crear es especialmente importante: elimina el espacio de trabajo remoto canónico de ese ámbito, y el siguiente uso inicializa uno nuevo a partir del entorno local. En el modo mirror, volver a crear restablece principalmente el entorno de ejecución remoto, ya que el entorno local sigue siendo canónico.

Vuelva a crear el entorno después de cambiar cualquiera de estos elementos:

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

Refuerzo de la seguridad

El puente del sistema de archivos del modo mirror fija la raíz del espacio de trabajo local y vuelve a comprobar las rutas canónicas (mediante realpath) antes de cada lectura, escritura, creación de directorio, eliminación y cambio de nombre, y rechaza los enlaces simbólicos en puntos intermedios de la ruta. Un cambio de enlace simbólico o un espacio de trabajo vuelto a montar no puede redirigir el acceso a archivos fuera del árbol reflejado.

Limitaciones actuales

• El navegador del entorno aislado no es compatible con el backend de OpenShell.
• sandbox.docker.binds no se aplica a OpenShell; la creación del entorno aislado falla si hay enlaces configurados.
• Los ajustes de ejecución específicos de Docker en sandbox.docker.* (salvo env) solo se aplican al backend de Docker.

Cómo funciona

1. OpenClaw ejecuta sandbox get para el nombre del entorno aislado (con cualquier --gateway/--gateway-endpoint configurado); si falla, crea uno con sandbox create, pasando --name, --from, --policy cuando estén definidos, --gpu cuando esté habilitado, --auto-providers/--no-auto-providers y una marca --provider por cada proveedor configurado.
2. OpenClaw ejecuta sandbox ssh-config para el nombre del entorno aislado a fin de obtener los datos de conexión SSH.
3. El núcleo escribe la configuración SSH en un archivo temporal y abre una sesión SSH mediante el mismo puente del sistema de archivos remoto que el backend SSH genérico.
4. En el modo mirror: sincroniza el entorno local con el remoto antes de la ejecución, ejecuta y vuelve a sincronizar después.
5. En el modo remote: inicializa una vez durante la creación y luego opera directamente en el espacio de trabajo remoto.

Contenido relacionado

• Entornos aislados - modos, ámbitos y comparación de backends
• Entorno aislado frente a política de herramientas frente a privilegios elevados - depuración de herramientas bloqueadas
• Entornos aislados y herramientas multiagente - anulaciones por agente
• CLI de entornos aislados - comandos openclaw sandbox