OpenShell

OpenShell é um backend de sandbox gerenciado: em vez de executar contêineres Docker localmente, o OpenClaw delega o ciclo de vida da sandbox à CLI openshell, que provisiona ambientes remotos e executa comandos por SSH.

O plugin reutiliza o mesmo transporte SSH e a mesma ponte de sistema de arquivos remoto do backend SSH genérico e adiciona o ciclo de vida do OpenShell (sandbox create/get/delete/ssh-config), além de um modo opcional de sincronização do espaço de trabalho chamado mirror.

Pré-requisitos

• Plugin do OpenShell instalado (openclaw plugins install @openclaw/openshell-sandbox)
• CLI openshell no PATH (ou um caminho personalizado por meio de plugins.entries.openshell.config.command)
• Uma conta do OpenShell com acesso a sandboxes
• Gateway do OpenClaw em execução no host

Início 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 o Gateway. No próximo turno do agente, o OpenClaw criará uma sandbox do OpenShell e encaminhará a execução de ferramentas por ela. Verifique com:

openclaw sandbox listopenclaw sandbox explain

Modos do espaço de trabalho

Esta é a decisão mais importante ao usar o OpenShell.

mirror (padrão)

plugins.entries.openshell.config.mode: "mirror" mantém o espaço de trabalho local como canônico:

• Antes de exec, o OpenClaw sincroniza o espaço de trabalho local com a sandbox.
• Depois de exec, o OpenClaw sincroniza o espaço de trabalho remoto de volta para o local.
• As ferramentas de arquivos passam pela ponte da sandbox, mas o local continua sendo a fonte da verdade entre os turnos.

É mais indicado para fluxos de trabalho de desenvolvimento: edições locais feitas fora do OpenClaw aparecem na próxima execução, e a sandbox se comporta de forma semelhante ao backend do Docker.

Desvantagem: custo de upload e download em cada turno de execução.

remote

mode: "remote" torna o espaço de trabalho do OpenShell canônico:

• Na primeira criação da sandbox, o OpenClaw copia uma única vez o espaço de trabalho local para o remoto.
• Depois disso, exec, read, write, edit e apply_patch operam diretamente no espaço de trabalho remoto. O OpenClaw não sincroniza as alterações remotas de volta para o local.
• As leituras de mídia durante a preparação do prompt continuam funcionando (as ferramentas de arquivos e mídia leem pela ponte da sandbox).

É mais indicado para agentes de longa duração e CI: menor sobrecarga por turno, e edições locais no host não podem sobrescrever silenciosamente o estado remoto.

Escolha de um modo

Referência de configuração

Toda a configuração do OpenShell fica em plugins.entries.openshell.config:

remoteWorkspaceDir e remoteAgentWorkspaceDir devem ser caminhos absolutos e permanecer sob as raízes gerenciadas /sandbox ou /agent; outros caminhos absolutos são rejeitados.

As configurações no nível da sandbox (mode, scope, workspaceAccess) ficam em agents.defaults.sandbox, como em qualquer backend. Consulte Sandbox para ver a matriz completa.

Exemplos

Configuração remota mínima

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

Modo mirror com 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 com 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",        },      },    },  },}

Gerenciamento do ciclo de vida

# Lista todos os runtimes de sandbox (Docker + OpenShell)openclaw sandbox list # Inspeciona a política efetivaopenclaw sandbox explain # Recria (exclui o espaço de trabalho remoto e copia novamente no próximo uso)openclaw sandbox recreate --all

No modo remote, a recriação é especialmente importante: ela exclui o espaço de trabalho remoto canônico daquele escopo, e o próximo uso copia um novo a partir do local. No modo mirror, a recriação redefine principalmente o ambiente de execução remoto, pois o local continua sendo canônico.

Recrie após alterar qualquer um destes itens:

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

Reforço da segurança

A ponte do sistema de arquivos no modo mirror fixa a raiz do espaço de trabalho local e verifica novamente os caminhos canônicos (por meio de realpath) antes de cada leitura, gravação, criação de diretório, remoção e renomeação, rejeitando links simbólicos no meio do caminho. Uma troca de link simbólico ou uma remontagem do espaço de trabalho não pode redirecionar o acesso a arquivos para fora da árvore espelhada.

Limitações atuais

• O navegador da sandbox não é compatível com o backend do OpenShell.
• sandbox.docker.binds não se aplica ao OpenShell; a criação da sandbox falha se houver montagens configuradas.
• As opções de runtime específicas do Docker em sandbox.docker.* (exceto env) aplicam-se somente ao backend do Docker.

Como funciona

1. O OpenClaw executa sandbox get para o nome da sandbox (com qualquer --gateway/--gateway-endpoint configurado); se isso falhar, cria uma com sandbox create, passando --name, --from, --policy quando definido, --gpu quando habilitado, --auto-providers/--no-auto-providers e uma opção --provider por provedor configurado.
2. O OpenClaw executa sandbox ssh-config para o nome da sandbox a fim de obter os detalhes da conexão SSH.
3. O núcleo grava a configuração SSH em um arquivo temporário e abre uma sessão SSH por meio da mesma ponte de sistema de arquivos remoto usada pelo backend SSH genérico.
4. No modo mirror: sincroniza do local para o remoto antes da execução, executa e sincroniza de volta depois.
5. No modo remote: copia uma vez na criação e depois opera diretamente no espaço de trabalho remoto.

Relacionados

• Sandbox - modos, escopos e comparação de backends
• Sandbox vs. política de ferramentas vs. modo elevado - depuração de ferramentas bloqueadas
• Sandbox e ferramentas multiagente - substituições por agente
• CLI de sandbox - comandos openclaw sandbox