Pular para o conteúdo principal
OpenShell é um backend de sandbox gerenciado para OpenClaw. Em vez de executar contêineres Docker localmente, o OpenClaw delega o ciclo de vida do sandbox à CLI openshell, que provisiona ambientes remotos com execução de comandos baseada em SSH. O Plugin OpenShell reutiliza o mesmo transporte SSH central e a mesma ponte de sistema de arquivos remoto que o backend SSH genérico. Ele adiciona um ciclo de vida específico do OpenShell (sandbox create/get/delete, sandbox ssh-config) e um modo opcional de workspace mirror.

​
Pré-requisitos

  • Plugin OpenShell instalado (openclaw plugins install @openclaw/openshell-sandbox)
  • A CLI openshell instalada e no PATH (ou defina um caminho personalizado via plugins.entries.openshell.config.command)
  • Uma conta OpenShell com acesso a sandbox
  • OpenClaw Gateway em execução no host

​
Início rápido

  1. Instale e habilite o plugin, depois defina o 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",
        },
      },
    },
  },
}
  1. Reinicie o Gateway. No próximo turno do agente, o OpenClaw cria um sandbox OpenShell e roteia a execução de ferramentas por ele.
  2. Verifique: 
openclaw sandbox list
openclaw sandbox explain

​
Modos de workspace

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

​
mirror

Use plugins.entries.openshell.config.mode: "mirror" quando quiser que o workspace local permaneça canônico. Comportamento:
  • Antes de exec, o OpenClaw sincroniza o workspace local para o sandbox OpenShell.
  • Depois de exec, o OpenClaw sincroniza o workspace remoto de volta para o workspace local.
  • As ferramentas de arquivo ainda operam pela ponte de sandbox, mas o workspace local permanece a fonte da verdade entre turnos.
Ideal para:
  • Você edita arquivos localmente fora do OpenClaw e quer que essas alterações fiquem visíveis no sandbox automaticamente.
  • Você quer que o sandbox OpenShell se comporte o mais parecido possível com o backend Docker.
  • Você quer que o workspace do host reflita as gravações do sandbox após cada turno de exec.
Trade-off: custo extra de sincronização antes e depois de cada exec.

​
remote

Use plugins.entries.openshell.config.mode: "remote" quando quiser que o workspace OpenShell se torne canônico. Comportamento:
  • Quando o sandbox é criado pela primeira vez, o OpenClaw semeia o workspace remoto a partir do workspace local uma vez.
  • Depois disso, exec, read, write, edit e apply_patch operam diretamente no workspace remoto do OpenShell.
  • O OpenClaw não sincroniza alterações remotas de volta para o workspace local.
  • Leituras de mídia no momento do prompt ainda funcionam porque as ferramentas de arquivo e mídia leem pela ponte de sandbox.
Ideal para:
  • O sandbox deve ficar principalmente no lado remoto.
  • Você quer menor sobrecarga de sincronização por turno.
  • Você não quer que edições locais no host sobrescrevam silenciosamente o estado remoto do sandbox.
Se você editar arquivos no host fora do OpenClaw após a semeadura inicial, o sandbox remoto não verá essas alterações. Use openclaw sandbox recreate para semear novamente.

​
Escolhendo um modo

mirrorremote
Workspace canônicoHost localOpenShell remoto
Direção da sincronizaçãoBidirecional (cada exec)Semeadura única
Sobrecarga por turnoMaior (upload + download)Menor (operações remotas diretas)
Edições locais visíveis?Sim, no próximo execNão, até recriar
Ideal paraFluxos de desenvolvimentoAgentes de longa duração, CI

​
Referência de configuração

Toda a configuração do OpenShell fica em plugins.entries.openshell.config:
ChaveTipoPadrãoDescrição
mode"mirror" ou "remote""mirror"Modo de sincronização do workspace
commandstring"openshell"Caminho ou nome da CLI openshell
fromstring"openclaw"Origem do sandbox para criação inicial
gatewaystring—Nome do gateway OpenShell (--gateway)
gatewayEndpointstring—URL do endpoint do gateway OpenShell (--gateway-endpoint)
policystring—ID da política OpenShell para criação do sandbox
providersstring[][]Nomes de provedores a anexar quando o sandbox for criado
gpubooleanfalseSolicitar recursos de GPU
autoProvidersbooleantruePassar --auto-providers durante a criação do sandbox
remoteWorkspaceDirstring"/sandbox"Workspace gravável primário dentro do sandbox
remoteAgentWorkspaceDirstring"/agent"Caminho de montagem do workspace do agente (para acesso somente leitura)
timeoutSecondsnumber120Tempo limite para operações da CLI openshell
As configurações no nível do sandbox (mode, scope, workspaceAccess) são configuradas em agents.defaults.sandbox, como em qualquer backend. Consulte Sandboxing para 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

Sandboxes OpenShell são gerenciados pela CLI normal de sandbox: 
# 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
Para o modo remote, recriar é especialmente importante: ele exclui o workspace remoto canônico desse escopo. O próximo uso semeia um novo workspace remoto a partir do workspace local. Para o modo mirror, recriar principalmente redefine o ambiente remoto de execução, porque o workspace local permanece canônico.

​
Quando recriar

Recrie após alterar qualquer um destes:
  • agents.defaults.sandbox.backend
  • plugins.entries.openshell.config.from
  • plugins.entries.openshell.config.mode
  • plugins.entries.openshell.config.policy
openclaw sandbox recreate --all

​
Reforço de segurança

O OpenShell fixa o fd da raiz do workspace e verifica novamente a identidade do sandbox antes de cada leitura, portanto trocas de symlink ou um workspace remontado não conseguem redirecionar leituras para fora do workspace remoto pretendido.

​
Limitações atuais

  • O navegador de sandbox não é compatível com o backend OpenShell.
  • sandbox.docker.binds não se aplica ao OpenShell.
  • Ajustes de runtime específicos do Docker em sandbox.docker.* aplicam-se apenas ao backend Docker.

​
Como funciona

  1. O OpenClaw chama openshell sandbox create (com as flags --from, --gateway, --policy, --providers, --gpu conforme configurado).
  2. O OpenClaw chama openshell sandbox ssh-config <name> para obter os detalhes de conexão SSH do sandbox.
  3. O núcleo grava a configuração SSH em um arquivo temporário e abre uma sessão SSH usando a mesma ponte de sistema de arquivos remoto do backend SSH genérico.
  4. No modo mirror: sincroniza local para remoto antes do exec, executa, sincroniza de volta depois do exec.
  5. No modo remote: semeia uma vez na criação, depois opera diretamente no workspace remoto.

​
Relacionados