openclaw fleet

O 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 apenas 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, sinalizadores, formatos de saída e o perfil do contêiner podem mudar entre versões sem um período de descontinuação enquanto essa interface se estabiliza.

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

O fleet create exibe uma única vez o token gerado do Gateway, junto com a URL da célula. Armazene o token imediatamente e, depois, configure as contas de canais de cada locatário dentro da célula desse locatário.

IDs de locatários

Os IDs de locatários 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 hifens 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 do 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 estar em uma única linha porque o Fleet os passa por meio de um arquivo de ambiente protegido 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 no registro que seja igual ou superior a 19100. O Fleet rejeita IDs de locatários 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 de 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. O Fleet rejeita contextos remotos do Docker, endpoints DOCKER_HOST e serviços remotos do Podman antes de reservar uma porta ou criar estado local; hosts remotos de células precisam de um contrato separado de armazenamento e endpoint e estão fora deste MVP.

Quando o Fleet inicia uma nova célula, a criação aguarda por até cerca de um minuto 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 que não ficou íntegra não é perdido — ele permanece no ambiente do contêiner (docker|podman inspect) e, como a célula ainda não atendeu nenhum tráfego, executar fleet rm --force seguido por uma nova criação é sempre uma alternativa segura.

Fixação por digest

Os comandos de criação e atualização aceitam referências de imagem fixadas por digest, como --image ghcr.io/openclaw/openclaw@sha256:<digest>. O Fleet passa a referência da imagem literalmente para o Docker ou Podman, o que permite que um operador mantenha uma célula em bytes imutáveis da imagem, em vez de usar 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 informações secretas, pois ele inclui o token.

Limites de disco

--disk limita apenas a camada gravável do contêiner. Os diretórios de estado e autenticação de cada locatário, montados por bind, permanecem no 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ários:

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; apenas o estado ativo 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 ativa 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 e, portanto, recusa um contêiner externo que use o nome esperado da célula. Pressione Ctrl-C para encerrar --follow sem tratar a interrupção do 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.

O fleet logs não tem o modo --json porque 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 sobre o nome registrado do contêiner. 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 e inicia esse contêiner. A substituição preserva a mesma porta do host, os diretórios de dados, a rede 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 conforme 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 encerra, entra em um ciclo de falhas ou não fica íntegra em cerca de um minuto é removida, e o contêiner anterior é restaurado, para que uma imagem com defeito 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 estiver 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 comandos exigem privilégios de operador do host. Os arquivos contêm o estado do tenant e segredos de autenticação, 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 tenant, troca o token do Gateway e exibe o novo token uma única vez. O Fleet faz backup de um tenant por vez; o backup de todos os tenants é uma ação separada do operador.

Ambos os comandos aceitam --max-bytes <bytes> para limitar os dados de arquivo armazenados ou extraídos, e ambos aplicam o mesmo limite fixo de um milhão de segmentos de caminho no arquivo, para que arquivos maliciosos contendo apenas 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, sockets ou nós de dispositivo; as quantidades 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 o node_modules do workspace, devem ser reinstaladas dentro da célula após uma restauração.

fleet doctor

Audite todas as células ou um tenant 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 verificação que falhar define um código de saída do processo diferente de zero.

fleet rm

Remova uma célula interrompida do runtime e do registro, mantendo os dados do tenant:

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 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 tenant. Cada destino deve ser exatamente o diretório final esperado do tenant, 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 tenants redirecione a exclusão para outro local.

A limpeza pode ser repetida quando um diretório de tenant exatamente esperado 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 tenant no host, dentro do 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 apenas 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, vinculação ao contêiner na LAN e origens da Control UI para a porta alocada no host. 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 node, não root, com UID 1000. O Fleet mantém as montagens bind privadas com modo 0700 graváveis sem torná-las acessíveis a todos. O Docker executado como 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 executado como 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 reclassificação privada :Z. Se você restaurar ou realocar dados da célula, mantenha os caminhos montados via bind 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 executado como root em um daemon 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 o tráfego de saída de rede necessário para provedores e canais. Coloque na frente 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 tenants, mas não protege os tenants contra o operador do Fleet, o administrador do runtime de contêineres ou um host comprometido. Consulte Hospedagem multi-tenant 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 do Gateway com 32 caracteres, criptograficamente aleatório, e o exibe uma única vez no resultado da criação. Armazene-o no gerenciador de segredos aprovado e evite registrar 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 ao Docker ou ao Podman apenas o caminho desse arquivo 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 do ambiente do contêiner não ficam ocultos do operador confiável do host: os administradores do Docker ou do Podman podem lê-los inspecionando o contêiner. A observação "exibido uma única vez" do Fleet descreve a saída normal da CLI, não uma proteção contra o administrador do host.

Relacionados

• Hospedagem multi-tenant
• Docker
• Podman
• Segurança do Gateway