Skip to main content
Exécutez le Gateway OpenClaw dans un conteneur Podman sans privilèges root, géré par votre utilisateur non-root actuel. Le modèle :
  • Podman exécute le conteneur du Gateway.
  • La CLI openclaw de votre hôte constitue le plan de contrôle.
  • Par défaut, l’état persistant réside sur l’hôte sous ~/.openclaw.
  • La gestion quotidienne utilise openclaw --container <name> ... au lieu de sudo -u openclaw, podman exec ou d’un utilisateur de service distinct.

​
Prérequis

  • Podman en mode sans privilèges root
  • CLI OpenClaw installée sur l’hôte
  • Facultatif : systemd --user si vous souhaitez un démarrage automatique géré par Quadlet
  • Facultatif : sudo uniquement si vous souhaitez utiliser loginctl enable-linger "$(whoami)" pour assurer la persistance au démarrage sur un hôte sans interface graphique

​
Démarrage rapide

1

Configuration initiale

Depuis la racine du dépôt, exécutez ./scripts/podman/setup.sh.Cette commande construit openclaw:local dans votre stockage Podman sans privilèges root (ou récupère OPENCLAW_IMAGE / OPENCLAW_PODMAN_IMAGE si la variable est définie), crée ~/.openclaw/openclaw.json avec gateway.mode: "local" s’il manque, et crée ~/.openclaw/.env avec un OPENCLAW_GATEWAY_TOKEN généré s’il manque.Variables d’environnement facultatives lors de la construction :Pour utiliser plutôt une configuration gérée par Quadlet (Linux et services utilisateur systemd uniquement) :
Vous pouvez aussi définir OPENCLAW_PODMAN_QUADLET=1.
2

Démarrer le conteneur du Gateway

Démarre le conteneur avec vos uid/gid actuels à l’aide de --userns=keep-id et monte par liaison votre état OpenClaw dans le conteneur.
3

Exécuter la configuration initiale dans le conteneur

Ouvrez ensuite http://127.0.0.1:18789/ et utilisez le jeton figurant dans ~/.openclaw/.env.Authentification du modèle : utilisez l’authentification gérée par OpenClaw pendant la configuration initiale (clés d’API Anthropic, ou authentification OAuth par navigateur/par code d’appareil d’OpenAI Codex pour OpenAI reposant sur Codex). Le lanceur Podman ne monte pas les répertoires d’identifiants de CLI de l’hôte, tels que ~/.claude ou ~/.codex, dans le conteneur de configuration initiale ou du Gateway. Les connexions existantes des CLI de l’hôte ne sont que des moyens pratiques utilisables sur le même hôte : pour les installations en conteneur, conservez l’authentification des fournisseurs dans l’état ~/.openclaw monté que la configuration initiale gère.
4

Gérer le conteneur en cours d’exécution depuis la CLI de l’hôte

Les commandes openclaw ordinaires s’exécutent alors automatiquement dans ce conteneur :
Sous macOS, la machine Podman peut donner au navigateur l’apparence d’un client non local pour le Gateway. Si l’interface de contrôle signale des erreurs d’authentification de l’appareil après le lancement, suivez les recommandations relatives à Tailscale dans Podman et Tailscale.
Le lanceur manuel lit uniquement une petite liste autorisée de clés liées à Podman dans ~/.openclaw/.env et transmet explicitement les variables d’environnement d’exécution au conteneur ; il ne transmet pas l’intégralité du fichier d’environnement à Podman.

​
Podman et Tailscale

Pour un accès HTTPS ou un accès distant depuis un navigateur, suivez la documentation principale de Tailscale. Remarques propres à Podman :
  • Conservez l’hôte de publication Podman sur 127.0.0.1.
  • Préférez un tailscale serve géré par l’hôte à openclaw gateway --tailscale serve.
  • Sous macOS, si le contexte local d’authentification de l’appareil dans le navigateur n’est pas fiable, utilisez l’accès Tailscale au lieu de solutions de contournement improvisées avec un tunnel local.
Consultez Tailscale et Interface de contrôle.

​
Systemd (Quadlet, facultatif)

Si vous avez exécuté ./scripts/podman/setup.sh --quadlet, la configuration initiale installe un fichier Quadlet dans ~/.config/containers/systemd/openclaw.container. Après avoir modifié le fichier Quadlet :
Pour assurer la persistance au démarrage sur les hôtes accessibles par SSH ou sans interface graphique, activez la persistance des services utilisateur pour votre utilisateur actuel :
Le service Quadlet généré conserve une configuration par défaut fixe et renforcée : ports publiés sur 127.0.0.1 (18789 pour le Gateway, 18790 pour le pont), --bind lan dans le conteneur, espace de noms utilisateur keep-id, OPENCLAW_NO_RESPAWN=1, Restart=on-failure et TimeoutStartSec=300. Il lit ~/.openclaw/.env comme EnvironmentFile d’exécution pour des valeurs telles que OPENCLAW_GATEWAY_TOKEN, mais n’utilise pas la liste autorisée de substitutions propres à Podman du lanceur manuel. Pour personnaliser les ports publiés, l’hôte de publication ou d’autres options d’exécution du conteneur, utilisez plutôt le lanceur manuel, ou modifiez directement ~/.config/containers/systemd/openclaw.container, puis rechargez et redémarrez le service.

​
Configuration, environnement et stockage

  • Répertoire de configuration : ~/.openclaw
  • Répertoire de l’espace de travail : ~/.openclaw/workspace
  • Fichier du jeton : ~/.openclaw/.env
  • Assistant de lancement : ./scripts/run-openclaw-podman.sh
Le script de lancement et Quadlet montent par liaison l’état de l’hôte dans le conteneur : OPENCLAW_CONFIG_DIR -> /home/node/.openclaw, OPENCLAW_WORKSPACE_DIR -> /home/node/.openclaw/workspace. Par défaut, il s’agit de répertoires de l’hôte, et non d’un état anonyme du conteneur ; ainsi, openclaw.json, les fichiers auth-profiles.json propres à chaque agent, l’état des canaux et des fournisseurs, les sessions et l’espace de travail survivent au remplacement du conteneur. La configuration initiale renseigne également gateway.controlUi.allowedOrigins pour 127.0.0.1 et localhost sur le port publié du Gateway afin que le tableau de bord local fonctionne avec l’adresse d’écoute non locale du conteneur. Variables d’environnement utiles pour le lanceur manuel (conservez-les dans ~/.openclaw/.env ; le lanceur lit ce fichier avant de déterminer les valeurs par défaut finales du conteneur et de l’image) : Si vous utilisez une valeur non standard pour OPENCLAW_CONFIG_DIR ou OPENCLAW_WORKSPACE_DIR, définissez les mêmes variables à la fois pour ./scripts/podman/setup.sh et pour les commandes ./scripts/run-openclaw-podman.sh launch ultérieures : le lanceur local au dépôt ne conserve pas les substitutions de chemins personnalisées entre les sessions de shell.

​
Mise à niveau des images

Après avoir reconstruit ou récupéré une nouvelle image, redémarrez le conteneur ou le service Quadlet. Lors du premier démarrage d’une nouvelle version d’OpenClaw, le Gateway effectue des réparations sûres de l’état et des plugins avant de signaler qu’il est prêt. Si le Gateway s’arrête au lieu de devenir prêt, exécutez une fois la même image avec openclaw doctor --fix sur le même état et la même configuration montés, puis redémarrez normalement le Gateway :
Sur les hôtes SELinux, ajoutez ,Z aux deux montages par liaison si Podman bloque l’accès à l’état monté.

​
Commandes utiles

  • Journaux du conteneur : podman logs -f openclaw
  • Arrêter le conteneur : podman stop openclaw
  • Supprimer le conteneur : podman rm -f openclaw
  • Ouvrir l’URL du tableau de bord depuis la CLI de l’hôte : openclaw dashboard --no-open
  • État de santé/état via la CLI de l’hôte : openclaw gateway status --deep (sonde RPC + analyse supplémentaire des services)

​
Résolution des problèmes

  • Permission refusée (EACCES) sur la configuration ou l’espace de travail : Le conteneur s’exécute par défaut avec --userns=keep-id et --user <your uid>:<your gid>. Vérifiez que les chemins de configuration et d’espace de travail de l’hôte appartiennent à votre utilisateur actuel.
  • Démarrage du Gateway bloqué (gateway.mode=local manquant) : Vérifiez que ~/.openclaw/openclaw.json existe et définit gateway.mode="local". scripts/podman/setup.sh le crée s’il manque.
  • Le conteneur redémarre après une mise à jour de l’image : Exécutez la commande ponctuelle openclaw doctor --fix décrite dans Mise à niveau des images, puis redémarrez le Gateway.
  • Les commandes de la CLI du conteneur ciblent la mauvaise instance : Utilisez explicitement openclaw --container <name> ..., ou exportez OPENCLAW_CONTAINER=<name> dans votre shell.
  • Échec de openclaw update avec --container : C’est normal. Reconstruisez ou récupérez l’image, puis redémarrez le conteneur ou le service Quadlet.
  • Le service Quadlet ne démarre pas : Exécutez systemctl --user daemon-reload, puis systemctl --user start openclaw.service. Sur les systèmes sans interface graphique, vous devrez peut-être aussi exécuter sudo loginctl enable-linger "$(whoami)".
  • SELinux bloque les montages par liaison : Conservez le comportement de montage par défaut ; le lanceur ajoute automatiquement :Z sous Linux lorsque SELinux est en mode enforcing ou permissive.

​
Voir aussi