Workers na nuvem

​

O que é executado onde

​

Requisitos

• Um Plugin de provedor de worker. O Plugin crabbox incluído opera a CLI do Crabbox, que intermedeia concessões entre backends de nuvem (AWS, Hetzner e outros). O binário crabbox deve estar em PATH (ou defina settings.binary), com as credenciais do provedor já configuradas. A admissão na AWS exige o Crabbox 0.38.1 ou mais recente.
• Para workers Crabbox na AWS, o aws.instanceProfile efetivo deve estar vazio. O provedor verifica crabbox config show --json antes da alocação e, em seguida, exige que crabbox inspect --json informe providerMetadata.instanceProfileAttached: false nos DescribeInstances da EC2. Concessões com uma função de instância ou sem metadados autoritativos são encerradas e rejeitadas.
• Node.js na máquina concedida. Imagens de nuvem básicas normalmente não o incluem — instale-o no comando setup do perfil.
• Uma sessão com um worktree gerenciado pertencente à sessão (crie um com worktree: true). O despacho move o conteúdo desse worktree; diretórios comuns são sincronizados como um espelho de manifesto.

​

Configuração

{
  "cloudWorkers": {
    "profiles": {
      "aws": {
        "provider": "crabbox",
        "install": "bundle",
        "settings": {
          "provider": "aws",
          "class": "standard",
          "ttl": "8h",
          "idleTimeout": "45m",
          "setup": "test -x /usr/bin/node || (curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs)"
        }
      }
    }
  }
}

​

O comando de configuração

​

Canais de instalação

• bundle empacota o dist do Gateway em execução, um package.json reduzido e todos os pacotes do workspace referenciados pela compilação, todos protegidos por um hash de conteúdo. A máquina verifica o pacote intacto em relação a esse hash e, em seguida, instala as dependências npm de produção (com scripts desativados). É assim que uma compilação de desenvolvimento é executada em um worker.
• npm comprova que a versão existe no registro público, fixa sua integridade SHA-512 e instala o openclaw@<version> correspondente exatamente ao Gateway.

​

Despacho de uma sessão

openclaw gateway call sessions.create \
  --params '{"key":"agent:main:big-refactor","worktree":true,"cwd":"/path/to/repo","worktreeName":"big-refactor"}'

openclaw gateway call sessions.dispatch \
  --timeout 1500000 \
  --params '{"key":"agent:main:big-refactor","profileId":"aws"}'

openclaw gateway call sessions.reclaim \
  --timeout 600000 \
  --params '{"key":"agent:main:big-refactor"}'

​

Modelo de segurança

• Entrada do worker fechada. Os workers se comunicam por um protocolo dedicado no soquete encapsulado, com uma lista fechada de métodos permitidos — um worker não pode chamar RPCs de operador.
• Credenciais emitidas, com hash em repouso. Cada despacho emite uma credencial de worker; o Gateway armazena apenas seu hash. A rotação de credenciais e o isolamento por época do proprietário garantem no máximo um proprietário ativo por sessão — um worker obsoleto que se reconecta é isolado, nunca mesclado.
• Fixação da chave do host. O provedor deve disponibilizar a chave de host SSH da máquina no momento do provisionamento; a inicialização se conecta com fixação estrita e falha de forma segura sem ela.
• Nenhuma credencial permanente de modelo, forge ou nuvem na máquina. A autenticação do modelo permanece no Gateway (a inferência trafega pela referência {provider, model}), os commits do Git do workspace são criados sem credenciais de forge, e os metadados da concessão Crabbox na AWS são verificados de forma autoritativa quanto à presença de uma função de instância antes da configuração. Mantenha também os comandos de configuração livres de credenciais.
• Saída pertencente ao provedor. O túnel reverso elimina qualquer necessidade de acesso direto do OpenClaw ao modelo, mas o OpenClaw não reconfigura os firewalls do provedor. Restrinja o tráfego de saída no provedor do worker quando a tarefa exigir.
• Transcrições duráveis, exatamente uma vez. O worker confirma lotes de transcrição por meio de um protocolo de comparação e troca em relação à folha da sessão; uma base obsoleta interrompe a execução de forma segura, em vez de duplicar ou fazer rebase de uma saída paga.

​

Solução de problemas

• sessions.dispatch é um método desconhecido — nenhum cloudWorkers.profiles está configurado ou o chamador não tem operator.admin.
• “Os turnos de workers na nuvem exigem o runtime do OpenClaw” — escolha um modelo cujo runtime configurado seja o OpenClaw. Runtimes de CLI externos, como claude-cli, não são compatíveis com inferência de workers.
• “A inicialização do worker exige Node.js no host alugado” — adicione uma instalação do Node a settings.setup (veja acima).
• A atestação da função de instância da AWS falha — limpe aws.instanceProfile (e CRABBOX_AWS_INSTANCE_PROFILE, se definido). Instale o Crabbox 0.38.1 ou mais recente; binários mais antigos não expõem o contrato autoritativo providerMetadata.instanceProfileAttached exigido para admissão na AWS.
• O despacho falha com um erro do provedor — o registro de posicionamento e environments.list mantêm o último erro, incluindo o trecho final do stderr da configuração/inicialização. As boxes são destruídas em caso de falha, portanto esse trecho final é a principal fonte forense.
• Tempo limite do cliente durante o despacho — openclaw gateway call usa por padrão um tempo limite de 10s; forneça --timeout com folga (o despacho continua sendo executado no servidor de qualquer forma, e uma nova tentativa durante o provisionamento é rejeitada com session cannot dispatch from placement provisioning).
• Manutenção de leases — crabbox list --provider <backend> mostra leases ativos; crabbox stop --provider <backend> --id <lease> libera um manualmente. Leases ociosos expiram conforme o idleTimeout do perfil.

​

Relacionado

• Sandboxing — redução do raio de impacto da execução local de ferramentas
• CLI de sessões — inspeção das sessões armazenadas
• Referência de configuração