openclaw fleet
openclaw fleet gerencia instâncias completas do OpenClaw chamadas células. Cada célula tem seu próprio Gateway, estado, credenciais, contas de canais, contêiner e porta do host acessível somente por loopback. Use uma célula para cada limite de confiança de locatário; não use um único Gateway compartilhado como limite multilocatário hostil.
O Fleet é experimental. Nomes de comandos, flags, formatos de saída e o perfil do contêiner podem mudar entre versões sem um período de descontinuação.
O Fleet é compatível com Docker e Podman. A imagem padrão é ghcr.io/openclaw/openclaw:latest.
O Fleet é testado em hosts Linux e macOS. Atualmente, hosts Windows não foram testados.
Início rápido
fleet create exibe uma única vez o token gerado do Gateway junto com a URL da célula. Armazene o token imediatamente e configure as contas de canais de cada locatário dentro da célula correspondente.
IDs de locatário
Os IDs de locatário devem corresponder a:../acme são rejeitados.
O ID passa a fazer parte do nome do contêiner: openclaw-cell-<tenant>.
fleet create
Crie uma célula e inicie-a:
--env:
Opções de criação
A alocação automática seleciona a primeira porta não utilizada do registro igual ou superior a
19100. O Fleet rejeita IDs de locatário duplicados e portas explícitas já atribuídas a outra célula.
As referências de imagem são passadas como um único argumento para o runtime do contêiner. Referências vazias e valores que começam com - são rejeitados para impedir que uma imagem seja interpretada como uma opção do Docker ou Podman.
O endpoint selecionado do Docker ou Podman deve ser local. Antes de reservar uma porta ou criar estado local, o Fleet rejeita contextos remotos do Docker, endpoints DOCKER_HOST e serviços remotos do Podman. Não há suporte para hosts de células remotos.
Quando o Fleet inicia uma nova célula, o comando de criação aguarda até cerca de um minuto para que o Gateway responda a /healthz. Se a célula não ficar íntegra, o Fleet mantém o contêiner e a linha do registro intactos para fleet status, fleet logs ou remoção explícita. --no-start ignora essa verificação de integridade. O token gerado do Gateway de uma nova célula não íntegra não é perdido — ele permanece no ambiente do contêiner (docker|podman inspect) e, como a célula ainda não atendeu a nenhum tráfego, usar fleet rm --force e depois fazer uma nova criação é sempre uma alternativa segura.
Fixação por digest
Os comandos de criação e upgrade aceitam referências de imagem fixadas por digest, como--image ghcr.io/openclaw/openclaw@sha256:<digest>. O Fleet passa a referência da imagem sem alterações para o Docker ou Podman, permitindo que um operador mantenha uma célula com bytes de imagem imutáveis em vez de uma tag variável.
O resultado da criação inclui o ID do locatário, o nome do contêiner, a porta do host, o token do Gateway e a URL local. Mesmo na saída JSON, trate o resultado como contendo dados secretos, pois ele inclui o token.
Limites de disco
--disk limita somente a camada gravável do contêiner. Os diretórios de estado e autenticação de cada locatário montados por vinculação continuam sendo armazenamento do host; use cotas de projeto do sistema de arquivos do host quando esses diretórios também precisarem de um limite rígido.
Política de saída
Para o Docker, mantenha o modo bridge e aplique a política de saída com regras do firewall do host, como a cadeia
DOCKER-USER.
fleet list
Liste as células na ordem dos IDs de locatário:
As linhas do registro permanecem visíveis quando o Docker ou Podman está indisponível; somente o estado atual passa a ser
unknown.
fleet status
Inspecione uma célula:
ok, failed ou skipped. /healthz comprova que o Gateway está ativo, não que todos os canais ou plugins configurados estejam totalmente prontos. A sondagem é ignorada quando não há um endpoint local utilizável para verificar.
fleet logs
Transmita os logs do contêiner de uma célula diretamente para o terminal:
--follow sem tratar a interrupção pelo operador como uma falha do comando. A saída de log passa por um filtro de ocultação que substitui o token atual do Gateway da célula por <redacted> antes que qualquer conteúdo chegue ao terminal.
fleet logs não tem um modo --json, pois os logs do contêiner são um fluxo bruto de stdout/stderr. Para scripts, limite a saída com --tail e use redirecionamentos ou pipelines comuns do shell.
fleet start, fleet stop e fleet restart
Controle uma célula existente com seu runtime registrado:
fleet upgrade
Baixe novamente a imagem registrada e substitua o contêiner da célula:
--env. O estado montado sobrevive à substituição do contêiner; o ambiente padrão da imagem pode mudar de acordo com a imagem de destino.
A substituição só é confirmada depois que seu Gateway responde a /healthz na porta de loopback da célula, de acordo com o contrato de integridade usado pelo arquivo Compose oficial. Uma substituição que encerre, entre em um ciclo de falhas ou não fique íntegra em cerca de um minuto é removida, e o contêiner anterior é restaurado, para que uma imagem defeituosa não derrube uma célula em funcionamento.
O token do Gateway não é armazenado intencionalmente no registro do Fleet. Antes de remover o contêiner antigo, o Fleet lê seu ambiente e transfere OPENCLAW_GATEWAY_TOKEN para o substituto. Não remova manualmente o contêiner antigo antes de uma atualização se o token não existir em nenhum outro local sob seu controle.
fleet backup e fleet restore
Faça backup de uma célula interrompida:
0600 e devem ser armazenados como credenciais. O backup recusa uma célula em execução para que o estado do SQLite seja capturado de forma consistente. A restauração recusa uma célula em execução, a menos que --force seja fornecido, substitui apenas o estado desse locatário, alterna o token do Gateway e imprime o novo token uma única vez. O Fleet faz backup de um locatário por vez; o backup de todos os locatários é uma ação separada do operador.
A restauração precisa de um contêiner existente e interrompido, pois o perfil de runtime inspecionado dele fornece os limites, o mapeamento de usuário, a procedência do ambiente e a imagem para a substituição. Se o contêiner registrado tiver sido removido fora do Fleet, primeiro execute fleet rm <tenant> --force sem --purge-data, recrie a célula com a imagem pretendida e --no-start e tente restaurar novamente. A primeira remoção mantém intactos os dois diretórios de dados do locatário.
Ambos os comandos aceitam --max-bytes <bytes> para limitar os dados de arquivos arquivados ou extraídos, e ambos aplicam o mesmo orçamento fixo de um milhão de segmentos de caminho de arquivo, para que arquivos maliciosos compostos apenas por metadados não possam esgotar os inodes do host e para que todo backup aceito continue restaurável. O backup aceita --out <path>, e ambos os comandos oferecem suporte a --json.
Os arquivos contêm apenas arquivos comuns e diretórios. O backup nunca segue nem armazena links simbólicos, links físicos, soquetes ou nós de dispositivo; as contagens de itens ignorados são informadas no resultado. A restauração rejeita arquivos que contenham qualquer outro tipo de entrada. Árvores de links simbólicos recriáveis, como node_modules do espaço de trabalho, devem ser reinstaladas dentro da célula após uma restauração.
fleet doctor
Audite todas as células ou um locatário sem alterar o estado do runtime ou do sistema de arquivos:
fleet rm
Remova uma célula interrompida do runtime e do registro, mantendo os dados do locatário:
--force:
--purge-data exige --force. Antes da exclusão recursiva, o Fleet resolve as duas raízes pertencentes ao Fleet e os dois diretórios por locatário. Cada destino deve ser exatamente o diretório folha esperado do locatário, estar estritamente dentro de sua raiz e não ser um link simbólico. Essas verificações de contenção impedem que um caminho de registro corrompido ou um link simbólico entre locatários redirecione a exclusão para outro local.
A limpeza pode ser repetida quando um diretório exato e esperado do locatário já estiver ausente. Isso permite que uma invocação posterior conclua a limpeza após uma falha parcial do sistema de arquivos sem flexibilizar as verificações de caminho para os diretórios que ainda existem.
Layout de armazenamento e contêineres
O estado da célula e as chaves de criptografia do perfil de autenticação usam caminhos separados por locatário no host, sob o diretório de estado ativo do OpenClaw:/home/node/.openclaw. O segundo é montado em /home/node/.config/openclaw, correspondendo à montagem da chave de criptografia da configuração oficial do Docker. Portanto, a chave de criptografia não fica exposta sob a montagem de estado comum nem é incluída quando somente o diretório de estado da célula é incluído em backup ou compartilhado. Ambos os diretórios sobrevivem à remoção e à atualização normais; fleet rm --purge-data --force exclui ambos após verificações de contenção separadas.
Antes da primeira inicialização, o Fleet inicializa a configuração da célula com gateway.mode=local, autenticação por token, a vinculação do contêiner à LAN e as origens da Control UI para a porta do host alocada. O valor do token não é gravado nessa configuração; ele permanece no ambiente do contêiner.
O Fleet fixa os caminhos do contêiner da imagem oficial com estes valores de ambiente:
Por padrão, a imagem oficial usa o usuário não root
node, com UID 1000. O Fleet mantém as montagens de vinculação privadas de 0700 graváveis sem torná-las acessíveis a todos. O Docker com root executa a célula com o UID e o GID não root do usuário que fez a invocação; o Docker sem root usa o UID 0 do contêiner, que é mapeado para o usuário não privilegiado do host que fez a invocação dentro do namespace de usuário do daemon. O Podman usa keep-id com o UID e o GID do usuário que fez a invocação. Quando o próprio Fleet é executado como root em um runtime com root, ele mantém o usuário da imagem e atribui os arquivos iniciais da montagem ao UID/GID 1000.
Em hosts com SELinux, as montagens do Docker e do Podman recebem uma nova rotulagem privada :Z. Se restaurar ou realocar os dados da célula, mantenha os caminhos montados por vinculação graváveis pelo usuário efetivo do contêiner. O perfil é compatível com execução sem root, mas o Docker ou o Podman já deve estar configurado para operação sem root no host; o Fleet não converte um daemon com root em um sem root.
Perfil de segurança
O Fleet aplica o seguinte perfil a todas as células:
O Fleet nunca monta
/var/run/docker.sock, usa --privileged ou a rede do host, nem adiciona recursos. A bridge por célula é um limite de separação entre células, não um firewall de saída: as células mantêm a saída de rede necessária para provedores e canais. Coloque diante da porta de loopback um proxy, túnel SSH ou configuração de tailnet que corresponda à sua implantação. http://127.0.0.1:<port> só pode ser acessado diretamente pelo host do Fleet.
Esse perfil separa os contêineres dos locatários, mas não protege os locatários contra o operador do Fleet, o administrador do runtime de contêiner ou um host comprometido. Consulte Hospedagem multilocatário para ver o modelo de confiança completo e opções de isolamento mais fortes.
Tratamento de tokens
Por padrão,fleet create gera um token hexadecimal de Gateway com 32 caracteres, criptograficamente aleatório, e o imprime uma única vez no resultado da criação. Armazene-o no gerenciador de segredos aprovado e evite capturar a saída da criação em logs.
--gateway-token coloca um token personalizado nos argumentos do processo local, que podem ser mantidos no histórico do shell ou ficar visíveis nas listagens de processos. Prefira o token gerado, a menos que um fluxo de trabalho existente de gerenciamento de segredos exija um valor fornecido.
O token e todos os valores passados com --env ficam no ambiente do contêiner. O Fleet os grava em um arquivo de ambiente temporário com modo 0600, passa somente o caminho desse arquivo ao Docker ou ao Podman e o remove depois que o comando do runtime termina. Os valores digitados explicitamente em openclaw fleet create --gateway-token ... ou --env KEY=VALUE ainda podem ficar visíveis nos argumentos do processo externo openclaw e no histórico do shell.
Os valores de ambiente do contêiner não ficam ocultos para o operador confiável do host: administradores do Docker ou Podman podem lê-los por meio da inspeção do contêiner. A observação “exibido uma vez” do Fleet descreve a saída normal da CLI, não a resistência a um administrador do host.