Podman

Exécutez le OpenClaw Gateway dans un conteneur Podman sans privilèges racine (rootless), géré par votre utilisateur non root actuel.

Le modèle prévu est le suivant :

Podman exécute le conteneur de la passerelle.
Votre openclaw hôte CLI est le plan de contrôle.
L’état persistant réside sur l’hôte sous ~/.openclaw par défaut.
La gestion quotidienne utilise openclaw --container <name> ... au lieu de sudo -u openclaw, podman exec ou un utilisateur de service distinct.

Prérequis

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

Démarrage rapide

Configuration unique
À partir de la racine du dépôt, exécutez ./scripts/podman/setup.sh.
Démarrer le conteneur Gateway
Démarrez le conteneur avec ./scripts/run-openclaw-podman.sh launch.
Exécuter l'intégration (onboarding) dans le conteneur
Exécutez ./scripts/run-openclaw-podman.sh launch setup, puis ouvrez http://127.0.0.1:18789/.
Gérer le conteneur en cours d'exécution depuis le CLI de l'hôte
Définissez OPENCLAW_CONTAINER=openclaw, puis utilisez les commandes normales openclaw depuis l’hôte.

Détails de la configuration :

./scripts/podman/setup.sh construit openclaw:local dans votre magasin Podman sans privilèges par défaut, ou utilise OPENCLAW_IMAGE / OPENCLAW_PODMAN_IMAGE si vous en avez défini un.
Il crée ~/.openclaw/openclaw.json avec gateway.mode: "local" s’il est manquant.
Il crée ~/.openclaw/.env avec OPENCLAW_GATEWAY_TOKEN s’il est manquant.
Pour les lancements manuels, l’assistant lit une petite liste d’autorisation de clés liées à Podman à partir de ~/.openclaw/.env et transmet des variables d’environnement d’exécution explicites au conteneur ; il ne transmet pas le fichier d’environnement complet à Podman.

Configuration gérée par Quadlet :

./scripts/podman/setup.sh --quadlet

Quadlet est une option uniquement disponible sur Linux car elle dépend des services utilisateur systemd.

Vous pouvez également définir OPENCLAW_PODMAN_QUADLET=1.

Variables d’environnement de construction/configuration facultatives :

OPENCLAW_IMAGE ou OPENCLAW_PODMAN_IMAGE — utiliser une image existante/tirée au lieu de construire openclaw:local
OPENCLAW_IMAGE_APT_PACKAGES — install extra apt packages during image build (also accepts legacy OPENCLAW_DOCKER_APT_PACKAGES)
OPENCLAW_IMAGE_PIP_PACKAGES — installe des paquets Python supplémentaires lors de la construction de l’image ; épinglez les versions et utilisez uniquement des index de paquets auxquels vous faites confiance
OPENCLAW_EXTENSIONS — pré-installe les dépendances des plugins au moment de la construction
OPENCLAW_INSTALL_BROWSER — pré-installe Chromium et Xvfb pour l’automatisation du navigateur (définissez sur 1 pour activer)

Démarrage du conteneur :

./scripts/run-openclaw-podman.sh launch

Le script démarre le conteneur en tant que votre uid/gid actuel avec --userns=keep-id et monte l’état de votre OpenClaw dans le conteneur.

Onboarding :

./scripts/run-openclaw-podman.sh launch setup

Ensuite, ouvrez http://127.0.0.1:18789/ et utilisez le jeton provenant de ~/.openclaw/.env.

Authentification du modèle dans Podman :

Utilisez l’authentification gérée par OpenClaw lors de la configuration : clés Anthropic API pour Anthropic, ou authentification OAuth/code d’appareil du navigateur Codex OpenAIOAuth pour OpenAI basé sur Codex.
Le lanceur Podman ne monte pas les répertoires d’identification de la CLI de l’hôte tels que ~/.claude ou ~/.codex dans le conteneur de configuration ou de passerelle.
Les connexions CLI de l’hôte existantes sont des chemins pratiques sur le même hôte. Pour les installations de conteneurs, conservez l’authentification du provider dans l’état ~/.openclaw monté que la configuration gère.

Par défaut pour la CLI de l’hôte :

export OPENCLAW_CONTAINER=openclaw

Ensuite, des commandes comme celles-ci s’exécuteront automatiquement à l’intérieur de ce conteneur :

openclaw dashboard --no-open
openclaw gateway status --deep   # includes extra service scan
openclaw doctor
openclaw channels login

Sur macOS, la machine Podman peut faire apparaître le navigateur comme non-local pour la passerelle. Si l’interface de contrôle signale des erreurs d’authentification d’appareil après le lancement, suivez les instructions Tailscale dans Podman et Tailscale.

Podman et Tailscale

Pour un accès HTTPS ou navigateur distant, suivez la documentation principale Tailscale.

Note spécifique à Podman :

Conservez l’hôte de publication Podman à 127.0.0.1.
Préférez le tailscale serve géré par l’hôte plutôt que openclaw gateway --tailscale serve.
Sur macOS, si le contexte d’authentification d’appareil du navigateur local n’est pas fiable, utilisez l’accès Tailscale au lieu des contournements de tunnel local ad hoc.

Voir :

Systemd (Quadlet, facultatif)

Si vous avez exécuté ./scripts/podman/setup.sh --quadlet, la configuration installe un fichier Quadlet à :

~/.config/containers/systemd/openclaw.container

Commandes utiles :

Démarrer : systemctl --user start openclaw.service
Arrêter : systemctl --user stop openclaw.service
État : systemctl --user status openclaw.service
Journaux : journalctl --user -u openclaw.service -f

Après avoir modifié le fichier Quadlet :

systemctl --user daemon-reload
systemctl --user restart openclaw.service

Pour la persistance au démarrage sur les hôtes SSH/headless, activez le maintien (lingering) pour votre utilisateur actuel :

sudo loginctl enable-linger "$(whoami)"

Configuration, variables d’environnement et stockage

Répertoire de config : ~/.openclaw
Répertoire de travail : ~/.openclaw/workspace
Fichier de jeton : ~/.openclaw/.env
Assistant de lancement : ./scripts/run-openclaw-podman.sh

Le script de lancement et Quadlet montent l’état de l’hôte dans le conteneur via bind-mount :

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, donc openclaw.json, auth-profiles.json par agent, l’état du channel/provider, les sessions et l’espace de travail survivent au remplacement du conteneur. La configuration Podman initialise également gateway.controlUi.allowedOrigins pour 127.0.0.1 et localhost sur le port de la passerelle publiée afin que le tableau de bord local fonctionne avec la liaison non bouclée (non-loopback) du conteneur.

Variables d’environnement utiles pour le lanceur manuel :

OPENCLAW_PODMAN_CONTAINER — nom du conteneur (openclaw par défaut)
OPENCLAW_PODMAN_IMAGE / OPENCLAW_IMAGE — image à exécuter
OPENCLAW_PODMAN_GATEWAY_HOST_PORT — port hôte mappé au port conteneur 18789
OPENCLAW_PODMAN_BRIDGE_HOST_PORT — port hôte mappé au port conteneur 18790
OPENCLAW_PODMAN_PUBLISH_HOST — interface hôte pour les ports publiés ; la valeur par défaut est 127.0.0.1
OPENCLAW_GATEWAY_BIND — mode de liaison de la passerelle à l’intérieur du conteneur ; la valeur par défaut est lan
OPENCLAW_PODMAN_USERNS — keep-id (par défaut), auto ou host

Le lanceur manuel lit ~/.openclaw/.env avant de finaliser les valeurs par défaut du conteneur/de l’image, vous pouvez donc les y rendre persistants.

Si vous utilisez un OPENCLAW_CONFIG_DIR ou un OPENCLAW_WORKSPACE_DIR non défini par défaut, définissez les mêmes variables pour les commandes ./scripts/podman/setup.sh et ultérieures ./scripts/run-openclaw-podman.sh launch. Le lanceur local au dépôt ne conserve pas les substitutions de chemin personnalisées d’un shell à l’autre.

Note Quadlet :

Le service Quadlet généré conserve intentionnellement une forme par défaut fixe et durcie : 127.0.0.1 ports publiés, --bind lan à l’intérieur du conteneur et keep-id espace de noms utilisateur.
Il fige OPENCLAW_NO_RESPAWN=1, Restart=on-failure et TimeoutStartSec=300.
Il publie à la fois 127.0.0.1:18789:18789 (passerelle) et 127.0.0.1:18790:18790 (pont).
Il lit ~/.openclaw/.env comme EnvironmentFile d’exécution pour des valeurs telles que OPENCLAW_GATEWAY_TOKEN, mais il ne consomme pas la liste blanche de substitution spécifique à Podman du lanceur manuel.
Si vous avez besoin de ports de publication personnalisés, d’un hôte de publication ou d’autres indicateurs d’exécution de conteneur, utilisez le lanceur manuel ou modifiez directement ~/.config/containers/systemd/openclaw.container, puis rechargez et redémarrez le service.

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 le CLI de l’hôte : openclaw dashboard --no-open
Santé/état via le CLI de l’hôte : openclaw gateway status --deep (sonde RPC + analyse de service supplémentaire)

Dépannage

Permission refusée (EACCES) sur la configuration ou l’espace de travail : Le conteneur s’exécute avec --userns=keep-id et --user <your uid>:<your gid> par défaut. Assurez-vous que les chemins de configuration/d’espace de travail de l’hôte appartiennent à votre utilisateur actuel.
Démarrage du Gateway bloqué (gateway.mode=local manquant) : Assurez-vous que ~/.openclaw/openclaw.json existe et définit gateway.mode="local". scripts/podman/setup.sh le crée s’il est manquant.
Les commandes CLI du conteneur atteignent la mauvaise cible : Utilisez explicitement openclaw --container <name> ..., ou exportez OPENCLAW_CONTAINER=<name> dans votre shell.
openclaw update échoue avec --container : Attendu. Reconstruisez/tirez 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 pouvez également avoir besoin de sudo loginctl enable-linger "$(whoami)".
SELinux bloque les montages de liaison : Laissez le comportement de montage par défaut tel quel ; le lanceur ajoute automatiquement :Z sur Linux lorsque SELinux est en mode appliqué ou permissif.