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 list
openclaw 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.

As edições de arquivos feitas no host fora do OpenClaw após a cópia inicial não ficam visíveis para a sandbox remota. Execute openclaw sandbox recreate para copiar novamente.

Escolha de um modo

	`mirror`	`remote`
Espaço de trabalho canônico	Host local	OpenShell remoto
Direção da sincronização	Bidirecional (a cada execução)	Cópia inicial única
Sobrecarga por turno	Maior (upload e download)	Menor (operações remotas diretas)
Edições locais visíveis?	Sim, na próxima execução	Não, até recriar
Mais indicado para	Fluxos de trabalho de desenvolvimento	Agentes de longa duração, CI

Referência de configuração

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

Chave	Tipo	Padrão	Descrição
`mode`	`"mirror"` ou `"remote"`	`"mirror"`	Modo de sincronização do espaço de trabalho
`command`	`string`	`"openshell"`	Caminho ou nome da CLI `openshell`
`from`	`string`	`"openclaw"`	Origem da sandbox na primeira criação
`gateway`	`string`	não definido	Nome do gateway do OpenShell (`--gateway` no nível superior)
`gatewayEndpoint`	`string`	não definido	Endpoint do gateway do OpenShell (`--gateway-endpoint` no nível superior)
`policy`	`string`	não definido	ID da política do OpenShell para criação da sandbox
`providers`	`string[]`	`[]`	Nomes dos provedores associados na criação da sandbox (sem duplicatas, uma opção `--provider` por entrada)
`gpu`	`boolean`	`false`	Solicita recursos de GPU (`--gpu`)
`autoProviders`	`boolean`	`true`	Passa `--auto-providers` (ou `--no-auto-providers` quando falso) durante a criação
`remoteWorkspaceDir`	`string`	`"/sandbox"`	Espaço de trabalho gravável principal dentro da sandbox
`remoteAgentWorkspaceDir`	`string`	`"/agent"`	Caminho de montagem do espaço de trabalho do agente (somente leitura quando o acesso ao espaço de trabalho não é `rw`)
`timeoutSeconds`	`number`	`120`	Tempo limite das operações da CLI `openshell`

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 efetiva
openclaw 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

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.
O OpenClaw executa sandbox ssh-config para o nome da sandbox a fim de obter os detalhes da conexão SSH.
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.
No modo mirror: sincroniza do local para o remoto antes da execução, executa e sincroniza de volta depois.
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

Gateway

Remote access

Security

Nodes and media

Web interfaces

Pré-requisitos

Início rápido

Modos do espaço de trabalho

mirror (padrão)

remote

Escolha de um modo

Referência de configuração

Exemplos

Configuração remota mínima

Modo mirror com GPU

OpenShell por agente com gateway personalizado

Gerenciamento do ciclo de vida

Reforço da segurança

Limitações atuais

Como funciona

Relacionados

​Pré-requisitos

​Início rápido

​Modos do espaço de trabalho

​mirror (padrão)

​remote

​Escolha de um modo

​Referência de configuração

​Exemplos

​Configuração remota mínima

​Modo mirror com GPU

​OpenShell por agente com gateway personalizado

​Gerenciamento do ciclo de vida

​Reforço da segurança

​Limitações atuais

​Como funciona

​Relacionados

Pré-requisitos

Início rápido

Modos do espaço de trabalho

mirror (padrão)

remote

Escolha de um modo

Referência de configuração

Exemplos

Configuração remota mínima

Modo mirror com GPU

OpenShell por agente com gateway personalizado

Gerenciamento do ciclo de vida

Reforço da segurança

Limitações atuais

Como funciona

Relacionados