CLI de ambiente isolado

Gerencie runtimes de sandbox para execução isolada de agentes.

Visão geral

O OmeniaClaw pode executar agentes em runtimes de sandbox isolados por segurança. Os comandos sandbox ajudam você a inspecionar e recriar esses runtimes após atualizações ou alterações de configuração.

Hoje isso geralmente significa:

• Contêineres de sandbox do Docker
• Runtimes de sandbox por SSH quando agents.defaults.sandbox.backend = "ssh"
• Runtimes de sandbox do OpenShell quando agents.defaults.sandbox.backend = "openshell"

Para ssh e OpenShell remote, recriar é mais importante do que com Docker:

• o workspace remoto é canônico após a propagação inicial
• OmeniaClaw sandbox recreate exclui esse workspace remoto canônico para o escopo selecionado
• o próximo uso o propaga novamente a partir do workspace local atual

Comandos

OmeniaClaw sandbox explain

Inspecione o modo/escopo/acesso ao workspace de sandbox efetivo, a política de ferramentas de sandbox e os gates elevados (com caminhos de chaves de configuração para correção).

OmeniaClaw sandbox explainOmeniaClaw sandbox explain --session agent:main:mainOmeniaClaw sandbox explain --agent workOmeniaClaw sandbox explain --json

OmeniaClaw sandbox list

Liste todos os runtimes de sandbox com seu status e configuração.

OmeniaClaw sandbox listOmeniaClaw sandbox list --browser  # List only browser containersOmeniaClaw sandbox list --json     # JSON output

A saída inclui:

• Nome e status do runtime
• Backend (docker, openshell, etc.)
• Rótulo de configuração e se ele corresponde à configuração atual
• Idade (tempo desde a criação)
• Tempo ocioso (tempo desde o último uso)
• Sessão/agente associado

OmeniaClaw sandbox recreate

Remova runtimes de sandbox para forçar a recriação com a configuração atualizada.

OmeniaClaw sandbox recreate --all                # Recreate all containersOmeniaClaw sandbox recreate --session main       # Specific sessionOmeniaClaw sandbox recreate --agent mybot        # Specific agentOmeniaClaw sandbox recreate --browser            # Only browser containersOmeniaClaw sandbox recreate --all --force        # Skip confirmation

Opções:

• --all: Recria todos os contêineres de sandbox
• --session <key>: Recria o contêiner de uma sessão específica
• --agent <id>: Recria contêineres de um agente específico
• --browser: Recria somente contêineres de navegador
• --force: Ignora o prompt de confirmação

Casos de uso

Depois de atualizar uma imagem Docker

# Pull new imagedocker pull OmeniaClaw-sandbox:latestdocker tag OmeniaClaw-sandbox:latest OmeniaClaw-sandbox:bookworm-slim # Update config to use new image# Edit config: agents.defaults.sandbox.docker.image (or agents.list[].sandbox.docker.image) # Recreate containersOmeniaClaw sandbox recreate --all

Depois de alterar a configuração de sandbox

# Edit config: agents.defaults.sandbox.* (or agents.list[].sandbox.*) # Recreate to apply new configOmeniaClaw sandbox recreate --all

Depois de alterar o destino SSH ou o material de autenticação SSH

# Edit config:# - agents.defaults.sandbox.backend# - agents.defaults.sandbox.ssh.target# - agents.defaults.sandbox.ssh.workspaceRoot# - agents.defaults.sandbox.ssh.identityFile / certificateFile / knownHostsFile# - agents.defaults.sandbox.ssh.identityData / certificateData / knownHostsData OmeniaClaw sandbox recreate --all

Para o backend ssh principal, recriar exclui a raiz do workspace remoto por escopo no destino SSH. A próxima execução a propaga novamente a partir do workspace local.

Depois de alterar a origem, a política ou o modo do OpenShell

# Edit config:# - agents.defaults.sandbox.backend# - plugins.entries.openshell.config.from# - plugins.entries.openshell.config.mode# - plugins.entries.openshell.config.policy OmeniaClaw sandbox recreate --all

Para o modo remote do OpenShell, recriar exclui o workspace remoto canônico desse escopo. A próxima execução o propaga novamente a partir do workspace local.

Depois de alterar setupCommand

OmeniaClaw sandbox recreate --all# or just one agent:OmeniaClaw sandbox recreate --agent family

Somente para um agente específico

# Update only one agent's containersOmeniaClaw sandbox recreate --agent alfred

Por que isso é necessário

Quando você atualiza a configuração de sandbox:

• Runtimes existentes continuam em execução com as configurações antigas.
• Runtimes só são removidos após 24h de inatividade.
• Agentes usados regularmente mantêm runtimes antigos ativos indefinidamente.

Use OmeniaClaw sandbox recreate para forçar a remoção de runtimes antigos. Eles são recriados automaticamente com as configurações atuais quando forem necessários novamente.

Migração de registro

O OmeniaClaw armazena metadados de runtime de sandbox como um fragmento JSON por entrada de contêiner/navegador no diretório de estado do sandbox. Instalações mais antigas ainda podem ter arquivos legados monolíticos:

• ~/.OmeniaClaw/sandbox/containers.json
• ~/.OmeniaClaw/sandbox/browsers.json

Leituras regulares de runtime de sandbox não reescrevem esses arquivos. Execute OmeniaClaw doctor --fix para migrar entradas legadas válidas para os diretórios de registro fragmentado. Arquivos legados inválidos são colocados em quarentena para que um registro antigo problemático não oculte entradas de runtime atuais.

Configuração

As configurações de sandbox ficam em ~/.OmeniaClaw/OmeniaClaw.json sob agents.defaults.sandbox (substituições por agente ficam em agents.list[].sandbox):

{  "agents": {    "defaults": {      "sandbox": {        "mode": "all", // off, non-main, all        "backend": "docker", // docker, ssh, openshell        "scope": "agent", // session, agent, shared        "docker": {          "image": "OmeniaClaw-sandbox:bookworm-slim",          "containerPrefix": "OmeniaClaw-sbx-",          // ... more Docker options        },        "prune": {          "idleHours": 24, // Auto-prune after 24h idle          "maxAgeDays": 7, // Auto-prune after 7 days        },      },    },  },}

Relacionado

• Referência da CLI
• Sandboxing
• Workspace do agente
• Doctor: verifica a configuração de sandbox.