Pular para o conteúdo principal

​
OpenShell

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

​
Pré-requisitos

  • A CLI openshell instalada e disponível em 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. Ative o plugin e defina o backend de 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 criará um sandbox OpenShell e roteará a execução das ferramentas por ele.
  2. Verifique: 
openclaw sandbox list
openclaw sandbox explain

​
Modos de workspace

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

​
mirror

Use plugins.entries.openshell.config.mode: "mirror" quando quiser que o workspace local continue sendo o canônico. Comportamento:
  • Antes de exec, o OpenClaw sincroniza o workspace local com o sandbox OpenShell.
  • Depois de exec, o OpenClaw sincroniza o workspace remoto de volta para o workspace local.
  • As ferramentas de arquivo ainda operam por meio da ponte do sandbox, mas o workspace local permanece como fonte da verdade entre turnos.
Ideal para:
  • Você editar arquivos localmente fora do OpenClaw e quiser que essas alterações fiquem visíveis no sandbox automaticamente.
  • Você quiser que o sandbox OpenShell se comporte o máximo possível como o backend Docker.
  • Você quiser 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 o canônico. Comportamento:
  • Quando o sandbox é criado pela primeira vez, o OpenClaw inicializa o workspace remoto a partir do workspace local uma vez.
  • Depois disso, exec, read, write, edit e apply_patch operam diretamente sobre o 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 continuam funcionando porque ferramentas de arquivo e mídia leem por meio da ponte do sandbox.
Ideal para:
  • O sandbox deve viver 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.
Importante: se você editar arquivos no host fora do OpenClaw após a inicialização inicial, o sandbox remoto não verá essas alterações. Use openclaw sandbox recreate para reinicializar.

​
Escolhendo um modo

mirrorremote
Workspace canônicoHost localOpenShell remoto
Direção da sincronizaçãoBidirecional (cada exec)Inicialização única
Sobrecarga por turnoMaior (upload + download)Menor (operações remotas diretas)
Edições locais visíveis?Sim, no próximo execNão, até recreate
Ideal paraFluxos de trabalho 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 na primeira vez
gatewaystring—Nome do gateway OpenShell (--gateway)
gatewayEndpointstring—URL do endpoint do gateway OpenShell (--gateway-endpoint)
policystring—ID da policy OpenShell para criação do sandbox
providersstring[][]Nomes de providers a anexar quando o sandbox é criado
gpubooleanfalseSolicita recursos de GPU
autoProvidersbooleantruePassa --auto-providers durante sandbox create
remoteWorkspaceDirstring"/sandbox"Workspace gravável principal dentro do sandbox
remoteAgentWorkspaceDirstring"/agent"Caminho de montagem do workspace do agente (para acesso somente leitura)
timeoutSecondsnumber120Timeout para operações da CLI openshell
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: 
# Lista todos os runtimes de sandbox (Docker + OpenShell)
openclaw sandbox list

# Inspeciona a policy efetiva
openclaw sandbox explain

# Recria (exclui o workspace remoto, reinicializa no próximo uso)
openclaw sandbox recreate --all
Para o modo remote, recreate é especialmente importante: ele exclui o workspace remoto canônico para esse escopo. No próximo uso, um novo workspace remoto é inicializado a partir do workspace local. Para o modo mirror, recreate principalmente redefine o ambiente de execução remoto 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

​
Limitações atuais

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

​
Como funciona

  1. O OpenClaw chama openshell sandbox create (com flags --from, --gateway, --policy, --providers, --gpu conforme configurado).
  2. O OpenClaw chama openshell sandbox ssh-config <name> para obter 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 de local para remoto antes de exec, executa, sincroniza de volta após exec.
  5. No modo remote: inicializa uma vez na criação e então opera diretamente no workspace remoto.

​
Consulte também