OpenShell

OpenShell es un backend gestionado de entornos aislados: 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 mirror de sincronización del espacio de trabajo.

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

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

openclaw sandbox listopenclaw sandbox explain

Modos del espacio de trabajo

Esta es la decisión más importante al usar 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 operan mediante el puente del entorno aislado, pero el entorno local sigue siendo la fuente de verdad entre turnos.

Es la mejor opción para los 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: el 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:

• Cuando se crea por primera vez el entorno aislado, OpenClaw inicializa una vez el espacio de trabajo remoto a partir del local.
• Después, exec, read, write, edit y apply_patch operan directamente en el espacio de trabajo remoto. OpenClaw no sincroniza los cambios remotos con el entorno local.
• La lectura de contenido multimedia durante la preparación del 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: reduce la sobrecarga por turno y las ediciones locales del host no pueden sobrescribir silenciosamente el estado remoto.

Elegir 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; se rechazan otras rutas absolutas.

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

# 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

En el modo remote, volver a crear el entorno 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 crearlo principalmente restablece el entorno de ejecución remoto, ya que el entorno local sigue siendo canónico.

Vuelve a crear el entorno después de cambiar cualquiera de los siguientes valores:

• 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 espejo 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 intercambio de enlaces simbólicos o un espacio de trabajo montado de nuevo 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 se configuran montajes.
• Los ajustes de ejecución específicos de Docker en sandbox.docker.* (excepto 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é configurado, --gpu cuando esté habilitado, --auto-providers/--no-auto-providers y una opción --provider por cada proveedor configurado.
2. OpenClaw ejecuta sandbox ssh-config para el nombre del entorno aislado y obtiene los detalles 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 del entorno local al remoto antes de la ejecución, ejecuta y vuelve a sincronizar después.
5. En el modo remote: inicializa una vez al crear el entorno y después 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 modo elevado - depuración de herramientas bloqueadas
• Entornos aislados y herramientas multiagente - anulaciones por agente
• CLI de entornos aislados - comandos de openclaw sandbox