OpenShell es un backend de sandbox administrado: en lugar de ejecutar contenedores Docker
localmente, OpenClaw delega el ciclo de vida del sandbox a la CLI openshell, que
aprovisiona entornos remotos y ejecuta comandos por SSH.
El Plugin reutiliza el mismo transporte SSH y puente de sistema de archivos remoto que el
backend SSH genérico, y agrega el ciclo de vida de OpenShell
(sandbox create/get/delete/ssh-config) más un modo opcional de sincronización de 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 sandbox
- 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",
},
},
},
},
}
openclaw sandbox list
openclaw sandbox explain
Modos de 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 sandbox.
- Después de
exec, OpenClaw sincroniza el espacio de trabajo remoto de vuelta al local.
- Las herramientas de archivos pasan por el puente del sandbox, pero lo local sigue siendo la fuente de verdad
entre turnos.
Ideal para flujos de trabajo de desarrollo: las ediciones locales fuera de OpenClaw aparecen en el
siguiente exec, y el sandbox se comporta de forma similar al backend de Docker.
Compensación: costo de carga y descarga en cada turno de exec.
remote
mode: "remote" hace que el espacio de trabajo de OpenShell sea canónico:
- En la primera creación del sandbox, OpenClaw inicializa una vez el espacio de trabajo remoto desde el local.
- Después de eso,
exec, read, write, edit y apply_patch operan
directamente sobre el espacio de trabajo remoto. OpenClaw no sincroniza los cambios remotos
de vuelta al local.
- Las lecturas de medios durante el prompt siguen funcionando (las herramientas de archivo/medios leen a través del
puente del sandbox).
Ideal 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.
Editar archivos en el host fuera de OpenClaw después de la inicialización inicial es invisible para el sandbox remoto. Ejecuta openclaw sandbox recreate para volver a inicializar.
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 (carga + descarga) | Menor (operaciones remotas directas) |
| ¿Ediciones locales visibles? | Sí, en el siguiente exec | No, hasta recrear |
| Ideal para | Flujos de trabajo de desarrollo | Agentes de larga duración, CI |
Referencia de configuración
Toda la configuración de OpenShell vive bajo 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" | Origen del sandbox para la primera creación |
gateway | string | sin definir | Nombre del Gateway de OpenShell (nivel superior --gateway) |
gatewayEndpoint | string | sin definir | Endpoint del Gateway de OpenShell (nivel superior --gateway-endpoint) |
policy | string | sin definir | ID de política de OpenShell para la creación del sandbox |
providers | string[] | [] | Nombres de proveedores adjuntos en la creación del sandbox (sin duplicados, una marca --provider por entrada) |
gpu | boolean | false | Solicitar recursos de GPU (--gpu) |
autoProviders | boolean | true | Pasar --auto-providers (o --no-auto-providers cuando sea false) durante la creación |
remoteWorkspaceDir | string | "/sandbox" | Espacio de trabajo escribible principal dentro del sandbox |
remoteAgentWorkspaceDir | string | "/agent" | Ruta de montaje del espacio de trabajo del agente (solo lectura cuando el acceso al espacio de trabajo no es rw) |
timeoutSeconds | number | 120 | Tiempo de espera para operaciones de la CLI openshell |
remoteWorkspaceDir y remoteAgentWorkspaceDir deben ser rutas absolutas y
permanecer bajo las raíces administradas /sandbox o /agent; se rechazan
otras rutas absolutas.
La configuración de nivel de sandbox (mode, scope, workspaceAccess) vive bajo
agents.defaults.sandbox como en 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
# 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
remote, recrear es especialmente importante: elimina el espacio de trabajo
remoto canónico para ese alcance, y el siguiente uso inicializa uno nuevo desde
local. Para el modo mirror, recrear principalmente restablece el entorno de ejecución
remoto, ya que lo local sigue siendo canónico.
Recrea después de cambiar cualquiera de estos valores:
agents.defaults.sandbox.backendplugins.entries.openshell.config.fromplugins.entries.openshell.config.modeplugins.entries.openshell.config.policy
Refuerzo de seguridad
El puente de sistema de archivos en 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, mkdir, eliminación y
cambio de nombre, rechazando enlaces simbólicos en segmentos intermedios de la ruta. Un intercambio de enlace simbólico o un espacio de trabajo remontado
no puede redirigir el acceso a archivos fuera del árbol reflejado.
Limitaciones actuales
- El navegador de sandbox no es compatible con el backend de OpenShell.
sandbox.docker.binds no se aplica a OpenShell; la creación del sandbox falla
si hay binds configurados.- Los controles de runtime específicos de Docker bajo
sandbox.docker.* (excepto env)
se aplican solo al backend de Docker.
Cómo funciona
- OpenClaw ejecuta
sandbox get para el nombre del sandbox (con cualquier
--gateway/--gateway-endpoint configurado); si eso falla, crea uno con
sandbox create, pasando --name, --from, --policy cuando esté definido, --gpu
cuando esté habilitado, --auto-providers/--no-auto-providers, y una marca
--provider por cada proveedor configurado.
- OpenClaw ejecuta
sandbox ssh-config para el nombre del sandbox a fin de obtener los
detalles de conexión SSH.
- Core escribe la configuración SSH en un archivo temporal y abre una sesión SSH a través del
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.
- En modo
remote: inicializa una vez al crear y luego opera directamente sobre el espacio de trabajo
remoto.
Relacionado
