openclaw fleet

openclaw fleet gère des instances OpenClaw complètes appelées cellules. Chaque cellule possède son propre Gateway, son propre état, ses propres identifiants, comptes de canaux, conteneur et port hôte accessible uniquement en boucle locale. Utilisez une cellule pour chaque frontière de confiance de locataire ; n'utilisez pas un Gateway partagé comme frontière hostile entre plusieurs locataires.

Fleet est expérimental. Les noms de commandes, les options, les formats de sortie et le profil du conteneur peuvent changer d'une version à l'autre sans période de dépréciation pendant la stabilisation de l'interface.

Fleet prend en charge Docker et Podman. L'image par défaut est ghcr.io/openclaw/openclaw:latest.

Fleet est testé sur les hôtes Linux et macOS. Les hôtes Windows ne sont actuellement pas testés.

Démarrage rapide

openclaw fleet create acmeopenclaw fleet status acmeopenclaw fleet list

fleet create affiche une seule fois le jeton Gateway généré avec l'URL de la cellule. Stockez immédiatement le jeton, puis configurez les comptes de canaux de chaque locataire dans la cellule de ce locataire.

ID de locataire

Les ID de locataire doivent correspondre à :

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

Cela autorise de 1 à 40 lettres minuscules, chiffres et traits d'union internes. Un ID doit commencer et se terminer par une lettre ou un chiffre. Les lettres majuscules, les traits de soulignement, les barres obliques, les points, les espaces et les chaînes de traversée telles que ../acme sont refusés.

L'ID devient une partie du nom du conteneur : openclaw-cell-<tenant>.

fleet create

Créez une cellule et démarrez-la :

openclaw fleet create acme

Créez une cellule Podman sur un port fixe sans la démarrer :

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

Transmettez des variables d'environnement propres au locataire en répétant --env :

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

Les clés d'environnement utilisent des lettres, des chiffres et des traits de soulignement, et ne peuvent pas commencer par un chiffre. Les valeurs doivent tenir sur une seule ligne, car Fleet les transmet au moyen d'un fichier d'environnement d'exécution protégé. Fleet refuse les tentatives de remplacement des variables gérées de chemin de conteneur et de jeton Gateway répertoriées dans Stockage et organisation du conteneur.

Options de création

L'allocation automatique sélectionne le premier port de registre inutilisé supérieur ou égal à 19100. Fleet refuse les ID de locataire en double et les ports explicites déjà attribués à une autre cellule.

Les références d'image sont transmises comme un seul argument à l'environnement d'exécution de conteneur. Les références vides et les valeurs commençant par - sont refusées afin qu'une image ne puisse pas être interprétée comme une option Docker ou Podman.

Le point de terminaison Docker ou Podman sélectionné doit être local. Fleet refuse les contextes Docker distants, les points de terminaison DOCKER_HOST et les services Podman distants avant de réserver un port ou de créer un état local ; les hôtes de cellules distants nécessitent un contrat distinct de stockage et de point de terminaison et sont reportés au-delà de ce MVP.

Lorsque Fleet démarre une nouvelle cellule, la création attend jusqu'à environ une minute que son Gateway réponde sur /healthz. Si la cellule ne devient pas saine, Fleet conserve son conteneur et sa ligne de registre pour fleet status, fleet logs ou une suppression explicite. --no-start ignore ce contrôle d'intégrité. Le jeton Gateway généré d'une nouvelle cellule non saine n'est pas perdu : il reste dans l'environnement du conteneur (docker|podman inspect) et, puisque la cellule n'a encore traité aucun trafic, fleet rm --force suivi d'une nouvelle création constitue toujours une solution sûre.

Épinglage par condensat

Les commandes de création et de mise à niveau acceptent les références d'image épinglées par condensat telles que --image ghcr.io/openclaw/openclaw@sha256:<digest>. Fleet transmet la référence d'image telle quelle à Docker ou Podman, ce qui permet à un opérateur de conserver une cellule sur des octets d'image immuables plutôt que sur une étiquette mouvante.

Le résultat de la création comprend l'ID du locataire, le nom du conteneur, le port hôte, le jeton Gateway et l'URL locale. Même dans une sortie JSON, considérez le résultat comme contenant des informations secrètes, car il contient le jeton.

Limites de disque

--disk limite uniquement la couche inscriptible du conteneur. Les répertoires d'état et d'authentification propres au locataire montés par liaison restent stockés sur l'hôte ; utilisez des quotas de projet du système de fichiers hôte lorsque ces répertoires doivent également être soumis à une limite stricte.

Politique de trafic sortant

Pour Docker, conservez le mode bridge et appliquez la politique de trafic sortant avec des règles de pare-feu de l'hôte telles que la chaîne DOCKER-USER.

fleet list

Répertoriez les cellules par ordre d'ID de locataire :

openclaw fleet listopenclaw fleet lsopenclaw fleet list --json

Le tableau contient :

Les lignes du registre restent visibles lorsque Docker ou Podman est indisponible ; seul l'état actif devient unknown.

fleet status

Inspectez une cellule :

openclaw fleet status acmeopenclaw fleet status acme --json

L'état combine la ligne du registre Fleet, l'inspection active du conteneur et une courte requête au mieux vers :

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

Le résultat du contrôle d'intégrité est ok, failed ou skipped. /healthz prouve que le Gateway est actif, et non que chaque canal ou Plugin configuré est entièrement prêt. La sonde est ignorée lorsqu'aucun point de terminaison local utilisable n'est disponible pour la vérification.

fleet logs

Diffusez directement dans le terminal les journaux du conteneur d'une cellule :

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

Fleet vérifie les étiquettes de propriété du conteneur enregistré avant de lire les journaux ; il refuse donc un conteneur étranger utilisant le nom de cellule attendu. Appuyez sur Ctrl-C pour arrêter --follow sans considérer l'arrêt par l'opérateur comme un échec de commande. La sortie des journaux passe par un filtre de masquage qui remplace le jeton Gateway actuel de la cellule par <redacted> avant que quoi que ce soit n'atteigne le terminal.

fleet logs ne possède pas de mode --json, car les journaux du conteneur constituent un flux stdout/stderr brut. Pour les scripts, limitez la sortie avec --tail et utilisez une redirection ou des pipelines shell ordinaires.

fleet start, fleet stop et fleet restart

Contrôlez une cellule existante avec son environnement d'exécution enregistré :

openclaw fleet start acmeopenclaw fleet stop acmeopenclaw fleet restart acme

Ces commandes agissent sur le nom de conteneur enregistré. Elles échouent si le locataire est inconnu ou si l'environnement d'exécution enregistré ne peut pas effectuer l'opération.

fleet upgrade

Téléchargez à nouveau l'image enregistrée et remplacez le conteneur de la cellule :

openclaw fleet upgrade acme

Déplacer la cellule vers une autre image :

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

La mise à niveau récupère l’image cible, inspecte le conteneur existant et le réseau propre à la cellule, arrête et supprime le conteneur, puis le recrée et le démarre. Le remplacement conserve le même port hôte, les répertoires de données, le réseau pont propre à la cellule, le profil d’exécution, les limites de ressources, la politique de redémarrage, l’environnement géré par Fleet et les valeurs initialement fournies avec --env. L’état monté subsiste après le remplacement du conteneur ; l’environnement par défaut de l’image peut changer avec l’image cible.

Le remplacement n’est validé qu’après que son Gateway répond à /healthz sur le port de bouclage de la cellule, conformément au contrat d’intégrité utilisé par le fichier Compose officiel. Un remplacement qui s’arrête, redémarre en boucle après un plantage ou ne devient pas opérationnel au bout d’environ une minute est supprimé et le conteneur précédent est restauré, afin qu’une image défectueuse ne mette pas hors service une cellule fonctionnelle.

Le jeton du Gateway n’est volontairement pas stocké dans le registre Fleet. Avant de supprimer l’ancien conteneur, Fleet lit son environnement et transmet OPENCLAW_GATEWAY_TOKEN au remplacement. Ne supprimez pas manuellement l’ancien conteneur avant une mise à niveau si le jeton n’existe nulle part ailleurs sous votre contrôle.

fleet backup et fleet restore

Sauvegarder une cellule arrêtée :

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

Restaurer cette archive dans la cellule enregistrée :

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

Ces commandes nécessitent les privilèges de l’opérateur hôte. Les archives contiennent l’état du locataire et des secrets d’authentification, sont créées avec le mode 0600 et doivent être stockées comme des identifiants. La sauvegarde refuse une cellule en cours d’exécution afin de capturer l’état SQLite de manière cohérente. La restauration refuse une cellule en cours d’exécution sauf si --force est fourni, remplace uniquement l’état de ce locataire, renouvelle le jeton du Gateway et affiche le nouveau jeton une seule fois. Fleet sauvegarde un locataire à la fois ; la sauvegarde de tous les locataires constitue une action distincte de l’opérateur.

Les deux commandes acceptent --max-bytes <bytes> pour limiter les données de fichiers archivées ou extraites, et appliquent toutes deux la même limite fixe d’un million de segments de chemin d’archive afin que les bombes d’archive composées uniquement de métadonnées ne puissent pas épuiser les inodes de l’hôte et que chaque sauvegarde acceptée reste restaurable. La sauvegarde accepte --out <path> et les deux commandes prennent en charge --json.

Les archives contiennent uniquement des fichiers ordinaires et des répertoires. La sauvegarde ne suit ni ne stocke jamais les liens symboliques, les liens physiques, les sockets ou les nœuds de périphérique ; le nombre d’éléments ignorés est indiqué dans le résultat. La restauration rejette les archives contenant tout autre type d’entrée. Les arborescences de liens symboliques pouvant être recréées, telles que le répertoire node_modules de l’espace de travail, doivent être réinstallées dans la cellule après une restauration.

fleet doctor

Auditer toutes les cellules ou un seul locataire sans modifier l’état du système d’exécution ni celui du système de fichiers :

openclaw fleet doctoropenclaw fleet doctor acme --json

Doctor vérifie la localité du système d’exécution, les étiquettes de propriété, l’intégrité, le durcissement, les limites de ressources, la liaison du port de bouclage, la présence du jeton, la propriété du réseau et le mode de sortie réseau, ainsi que les autorisations des répertoires d’état privés. Les avertissements décrivent les cellules arrêtées ou les différences de propriété ; tout constat en échec attribue au processus un code de sortie non nul.

fleet rm

Supprimer une cellule arrêtée du système d’exécution et du registre tout en conservant les données du locataire :

openclaw fleet rm acme

Un conteneur en cours d’exécution nécessite --force :

openclaw fleet rm acme --force

Supprimer également définitivement les données de la cellule :

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

Fleet supprime le conteneur de la cellule avant de supprimer son réseau pont dédié. --purge-data nécessite --force. Avant la suppression récursive, Fleet résout les deux racines appartenant à Fleet et les deux répertoires propres au locataire. Chaque cible doit correspondre exactement au répertoire terminal attendu du locataire, se trouver strictement à l’intérieur de sa racine et ne pas être un lien symbolique. Ces vérifications de confinement empêchent qu’un chemin de registre corrompu ou qu’un lien symbolique entre locataires redirige la suppression ailleurs.

La purge peut être relancée lorsqu’un répertoire de locataire correspondant exactement à celui attendu est déjà absent. Cela permet à une exécution ultérieure de terminer le nettoyage après une défaillance partielle du système de fichiers, sans assouplir les vérifications de chemin pour les répertoires qui existent encore.

Disposition du stockage et des conteneurs

L’état des cellules et les clés de chiffrement des profils d’authentification utilisent des chemins hôtes distincts pour chaque locataire sous le répertoire d’état OpenClaw actif :

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

Le premier répertoire est monté dans /home/node/.openclaw. Le second est monté dans /home/node/.config/openclaw, conformément au montage des clés de chiffrement de la configuration Docker officielle. La clé de chiffrement n’est donc pas exposée sous le montage d’état ordinaire ni incluse lorsque seul le répertoire d’état de la cellule est sauvegardé ou partagé. Les deux répertoires subsistent après une suppression normale et une mise à niveau ; fleet rm --purge-data --force les supprime tous les deux après des vérifications de confinement distinctes.

Avant le premier démarrage, Fleet initialise la configuration de la cellule avec gateway.mode=local, l’authentification par jeton, la liaison au réseau local du conteneur et les origines de la Control UI pour le port hôte attribué. La valeur du jeton n’est pas écrite dans cette configuration ; elle reste dans l’environnement du conteneur.

Fleet fixe les chemins du conteneur de l’image officielle avec les valeurs d’environnement suivantes :

L’image officielle utilise par défaut l’utilisateur non-root node avec l’UID 1000. Fleet maintient les montages liés privés 0700 accessibles en écriture sans les rendre accessibles à tous. Docker en mode privilégié exécute la cellule avec l’UID et le GID de l’utilisateur non-root appelant ; Docker sans privilèges utilise l’UID de conteneur 0, qui correspond à l’utilisateur hôte non privilégié appelant dans l’espace de noms utilisateur du démon. Podman utilise keep-id avec l’UID et le GID appelants. Lorsque Fleet lui-même s’exécute en tant que root avec un système d’exécution privilégié, il conserve l’utilisateur de l’image et attribue les fichiers initiaux des montages à l’UID/GID 1000.

Sur les hôtes SELinux, les montages Docker et Podman reçoivent un réétiquetage privé :Z. Si vous restaurez ou déplacez les données d’une cellule, veillez à ce que l’utilisateur effectif du conteneur puisse écrire dans les chemins montés par liaison. Le profil est adapté à une exécution sans privilèges, mais Docker ou Podman doit déjà être configuré pour fonctionner sans privilèges sur l’hôte ; Fleet ne convertit pas un démon privilégié en démon sans privilèges.

Profil de sécurité

Fleet applique le profil suivant à chaque cellule :

Fleet ne monte jamais /var/run/docker.sock, n’utilise jamais --privileged ni le réseau de l’hôte, et n’ajoute aucune capacité. Le pont propre à chaque cellule constitue une limite de séparation entre cellules, et non un pare-feu sortant : les cellules conservent l’accès réseau sortant nécessaire aux fournisseurs et aux canaux. Placez devant le port de bouclage un proxy, un tunnel SSH ou une configuration de réseau privé correspondant à votre déploiement. http://127.0.0.1:<port> n’est directement accessible que depuis l’hôte Fleet.

Ce profil sépare les conteneurs des locataires, mais il ne protège pas les locataires contre l’opérateur Fleet, l’administrateur du système d’exécution des conteneurs ou un hôte compromis. Consultez Hébergement multilocataire pour connaître le modèle de confiance complet et les options d’isolation renforcée.

Gestion des jetons

Par défaut, fleet create génère un jeton Gateway hexadécimal de 32 caractères, aléatoire et cryptographiquement sûr, puis l’affiche une seule fois dans le résultat de la création. Stockez-le dans votre gestionnaire de secrets approuvé et évitez de consigner la sortie de la création dans les journaux.

--gateway-token place un jeton personnalisé dans les arguments du processus local, qui peuvent être conservés dans l’historique de l’interpréteur de commandes ou visibles dans les listes de processus. Préférez le jeton généré, sauf si un processus existant de gestion des secrets exige une valeur fournie.

Le jeton et chaque valeur transmise avec --env résident dans l’environnement du conteneur. Fleet les écrit dans un fichier d’environnement temporaire de mode 0600, transmet uniquement le chemin de ce fichier à Docker ou Podman, puis le supprime une fois la commande du système d’exécution terminée. Les valeurs explicitement saisies dans openclaw fleet create --gateway-token ... ou --env KEY=VALUE peuvent néanmoins rester visibles dans les arguments du processus openclaw externe et dans l’historique de l’interpréteur de commandes.

Les valeurs de l’environnement du conteneur ne sont pas masquées à l’opérateur hôte de confiance : les administrateurs Docker ou Podman peuvent les lire en inspectant le conteneur. La mention « affiché une seule fois » de Fleet décrit la sortie normale de la CLI, et non une protection contre un administrateur de l’hôte.

Pages connexes

• Hébergement multilocataire
• Docker
• Podman
• Sécurité du Gateway