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 un ciclo de vida específico de OpenShell (sandbox create/get/delete, sandbox ssh-config) y un modo opcional de espacio de trabajo mirror.

Requisitos previos

• Plugin de OpenShell instalado (openclaw plugins install @openclaw/openshell-sandbox)
• La CLI openshell instalada y en PATH (o establece 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

1. Instala y habilita el Plugin, luego establece el backend de 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. 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.

3. Verifica:

openclaw sandbox listopenclaw 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 archivo siguen operando a través del 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 en el sandbox automáticamente.
• Quieres que el sandbox de OpenShell se comporte lo más parecido posible al backend Docker.
• Quieres que el espacio de trabajo del host refleje las escrituras del sandbox después de cada turno de exec.

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

remote

Usa plugins.entries.openshell.config.mode: "remote" cuando quieras que el espacio de trabajo de OpenShell se vuelva canónico.

Comportamiento:

• Cuando se crea el sandbox por primera vez, OpenClaw inicializa el espacio de trabajo remoto desde el espacio de trabajo local una sola vez.
• Después de eso, exec, read, write, edit y apply_patch operan directamente contra 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 a través del puente de sandbox.

Ideal para:

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

Elegir un modo

Referencia de configuración

Toda la configuración de OpenShell vive bajo plugins.entries.openshell.config:

La configuración de nivel de sandbox (mode, scope, workspaceAccess) se configura bajo 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 normal de 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

Para el modo remote, recreate es especialmente importante: elimina el espacio de trabajo remoto canónico para ese ámbito. El siguiente uso inicializa un espacio de trabajo remoto nuevo desde el espacio de trabajo local.

Para el modo mirror, recreate 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 symlink o un espacio de trabajo remontado 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 controles específicos de runtime de Docker bajo sandbox.docker.* se aplican solo al backend Docker.

Cómo funciona

1. OpenClaw llama a openshell sandbox create (con los flags --from, --gateway, --policy, --providers, --gpu según la configuración).
2. OpenClaw llama a openshell sandbox ssh-config <name> para obtener los detalles de conexión SSH del sandbox.
3. El núcleo 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.
4. En modo mirror: sincroniza de local a remoto antes de exec, ejecuta, sincroniza de vuelta después de exec.
5. 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 backends
• Sandbox vs Tool Policy vs Elevated -- depuración de herramientas bloqueadas
• Sandbox multiagente y herramientas -- anulaciones por agente
• CLI de sandbox -- comandos openclaw sandbox