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

openclaw fleet create acmeopenclaw fleet status acmeopenclaw fleet list

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:

^[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$

Isso permite de 1 a 40 letras minúsculas, dígitos e hífens internos. Um ID deve começar e terminar com uma letra ou um dígito. Letras maiúsculas, sublinhados, barras, pontos, espaços em branco e strings de travessia como ../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:

openclaw fleet create acme

Crie uma célula Podman em uma porta fixa sem iniciá-la:

openclaw fleet create acme \  --runtime podman \  --port 19125 \  --no-start

Passe variáveis de ambiente específicas do locatário repetindo --env:

openclaw fleet create acme \  --env TZ=America/Los_Angeles \  --env OPENCLAW_DISABLE_BONJOUR=1

As chaves de ambiente usam letras, dígitos e sublinhados e não podem começar com um dígito. Os valores devem ocupar uma única linha, pois o Fleet os transmite por meio de um arquivo protegido de ambiente do runtime. O Fleet rejeita tentativas de substituir as variáveis gerenciadas de caminho do contêiner e de token do Gateway listadas em Armazenamento e layout do contêiner.

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:

openclaw fleet listopenclaw fleet lsopenclaw fleet list --json

A tabela contém:

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:

openclaw fleet status acmeopenclaw fleet status acme --json

O status combina a linha do registro do Fleet, a inspeção atual do contêiner e uma breve solicitação de melhor esforço para:

http://127.0.0.1:<host-port>/healthz

O resultado da verificação de integridade é 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:

openclaw fleet logs acmeopenclaw fleet logs acme --followopenclaw fleet logs acme --tail 200openclaw fleet logs acme --since 10m

O Fleet verifica os rótulos de propriedade do contêiner registrado antes de ler qualquer log, recusando assim um contêiner externo que use o nome esperado da célula. O fluxo é fixado ao ID do contêiner inspecionado, portanto uma substituição simultânea não pode redirecioná-lo para uma geração mais recente. Pressione Ctrl-C para encerrar --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:

openclaw fleet start acmeopenclaw fleet stop acmeopenclaw fleet restart acme

Esses comandos operam no nome de contêiner registrado. Eles falham se o locatário for desconhecido ou se o runtime registrado não puder executar a operação.

fleet upgrade

Baixe novamente a imagem registrada e substitua o contêiner da célula:

openclaw fleet upgrade acme

Mova a célula para outra imagem:

openclaw fleet upgrade acme --image ghcr.io/openclaw/openclaw:<version>

A atualização baixa a imagem de destino, inspeciona o contêiner existente e a rede por célula, interrompe e remove o contêiner e, em seguida, recria-o e o inicia. A substituição preserva a mesma porta do host, os diretórios de dados, a rede de bridge por célula, o perfil de runtime, os limites de recursos, a política de reinicialização, o ambiente gerenciado pelo Fleet e os valores originalmente fornecidos com --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:

openclaw fleet stop acmeopenclaw fleet backup acme --out ./acme.tgz

Restaure esse arquivo na célula registrada:

openclaw fleet restore acme --from ./acme.tgz

Esses são comandos privilegiados do operador do host. Os arquivos contêm o estado e os segredos de autenticação do locatário, são criados com o modo 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:

openclaw fleet doctoropenclaw fleet doctor acme --json

O Doctor verifica a localidade do runtime, os rótulos de propriedade, a integridade, o reforço de segurança, os limites de recursos, a vinculação da porta de loopback, a presença do token, a propriedade da rede e o modo de saída, além das permissões do diretório de estado privado. Os avisos descrevem células interrompidas ou diferenças de propriedade; qualquer constatação com falha define um código de saída de processo diferente de zero.

fleet rm

Remova uma célula interrompida do runtime e do registro, mantendo os dados do locatário:

openclaw fleet rm acme

Um contêiner em execução exige --force:

openclaw fleet rm acme --force

Remova permanentemente também os dados da célula:

openclaw fleet rm acme --purge-data --force

O Fleet remove o contêiner da célula antes de remover sua rede de bridge dedicada. --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:

<state-dir>/fleet/cells/<tenant>/<state-dir>/fleet/auth-profile-secrets/<tenant>/

O primeiro diretório é montado em /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.

Relacionado

• Hospedagem multilocatário
• Docker
• Podman
• Segurança do Gateway