Podman

Executez la passerelle OpenClaw dans un conteneur rootless Podman. Utilise la meme image que Docker (construite depuis le Dockerfile du depot).

Pre-requis

Podman (rootless)
Sudo pour la configuration initiale (creation de l’utilisateur, construction de l’image)

Demarrage rapide

1. Configuration initiale (depuis la racine du depot ; cree l’utilisateur, construit l’image, installe le script de lancement) :

./setup-podman.sh

Cela cree aussi un ~openclaw/.openclaw/openclaw.json minimal (definit gateway.mode="local") pour que la passerelle puisse demarrer sans executer l’assistant.

Par defaut, le conteneur n’est pas installe comme service systemd, vous le demarrez manuellement (voir ci-dessous). Pour une configuration de production avec demarrage automatique et redemarrages, installez-le comme service utilisateur systemd Quadlet :

./setup-podman.sh --quadlet

(Ou definissez OPENCLAW_PODMAN_QUADLET=1 ; utilisez --container pour installer uniquement le conteneur et le script de lancement.)

Variables d’environnement optionnelles au build (a definir avant d’executer setup-podman.sh) :

OPENCLAW_DOCKER_APT_PACKAGES — installer des paquets apt supplementaires pendant la construction de l’image
OPENCLAW_EXTENSIONS — pre-installer les dependances d’extensions (noms d’extensions separes par des espaces, par ex. diagnostics-otel matrix)

2. Demarrer la passerelle (manuel, pour un test rapide) :

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

3. Assistant d’accueil (par ex. pour ajouter des canaux ou fournisseurs) :

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

Puis ouvrez http://127.0.0.1:18789/ et utilisez le token de ~openclaw/.openclaw/.env (ou la valeur affichee par setup).

Systemd (Quadlet, optionnel)

Si vous avez execute ./setup-podman.sh --quadlet (ou OPENCLAW_PODMAN_QUADLET=1), une unite Podman Quadlet est installee pour que la passerelle tourne comme service utilisateur systemd pour l’utilisateur openclaw. Le service est active et demarre a la fin de la configuration.

Demarrer : sudo systemctl --machine openclaw@ --user start openclaw.service
Arreter : sudo systemctl --machine openclaw@ --user stop openclaw.service
Etat : sudo systemctl --machine openclaw@ --user status openclaw.service
Logs : sudo journalctl --machine openclaw@ --user -u openclaw.service -f

Le fichier quadlet reside a ~openclaw/.config/containers/systemd/openclaw.container. Pour changer les ports ou l’environnement, editez ce fichier (ou le .env qu’il source), puis sudo systemctl --machine openclaw@ --user daemon-reload et redemarrez le service. Au boot, le service demarre automatiquement si le lingering est active pour openclaw (la configuration le fait quand loginctl est disponible).

Pour ajouter quadlet apres une configuration initiale qui ne l’utilisait pas, relancez : ./setup-podman.sh --quadlet.

L’utilisateur openclaw (sans connexion)

setup-podman.sh cree un utilisateur systeme dedie openclaw :

Shell : nologin — pas de connexion interactive ; reduit la surface d’attaque.
Home : par ex. /home/openclaw — contient ~/.openclaw (config, espace de travail) et le script de lancement run-openclaw-podman.sh.
Podman rootless : L’utilisateur doit avoir une plage subuid et subgid. Beaucoup de distributions les attribuent automatiquement a la creation de l’utilisateur. Si la configuration affiche un avertissement, ajoutez des lignes a /etc/subuid et /etc/subgid :
```
openclaw:100000:65536
```
Puis demarrez la passerelle en tant que cet utilisateur (par ex. depuis cron ou systemd) :
```
sudo -u openclaw /home/openclaw/run-openclaw-podman.sh
sudo -u openclaw /home/openclaw/run-openclaw-podman.sh setup
```
Configuration : Seuls openclaw et root peuvent acceder a /home/openclaw/.openclaw. Pour editer la configuration : utilisez l’interface de controle une fois la passerelle en fonctionnement, ou sudo -u openclaw $EDITOR /home/openclaw/.openclaw/openclaw.json.

Environnement et configuration

Token : Stocke dans ~openclaw/.openclaw/.env sous OPENCLAW_GATEWAY_TOKEN. setup-podman.sh et run-openclaw-podman.sh le generent s’il manque (utilise openssl, python3, ou od).
Optionnel : Dans ce .env vous pouvez definir des cles de fournisseur (par ex. GROQ_API_KEY, OLLAMA_API_KEY) et d’autres variables d’environnement OpenClaw.
Ports hote : Par defaut, le script mappe 18789 (passerelle) et 18790 (bridge). Surchargez le mapping de port hote avec OPENCLAW_PODMAN_GATEWAY_HOST_PORT et OPENCLAW_PODMAN_BRIDGE_HOST_PORT au lancement.
Liaison passerelle : Par defaut, run-openclaw-podman.sh demarre la passerelle avec --bind loopback pour un acces local securise. Pour exposer sur le LAN, definissez OPENCLAW_GATEWAY_BIND=lan et configurez gateway.controlUi.allowedOrigins (ou activez explicitement le fallback host-header) dans openclaw.json.
Chemins : La configuration et l’espace de travail hote sont par defaut ~openclaw/.openclaw et ~openclaw/.openclaw/workspace. Surchargez les chemins hote utilises par le script de lancement avec OPENCLAW_CONFIG_DIR et OPENCLAW_WORKSPACE_DIR.

Modele de stockage

Donnees hote persistantes : OPENCLAW_CONFIG_DIR et OPENCLAW_WORKSPACE_DIR sont montes en bind dans le conteneur et conservent l’etat sur l’hote.
tmpfs sandbox ephemere : si vous activez agents.defaults.sandbox, les conteneurs sandbox d’outils montent tmpfs a /tmp, /var/tmp et /run. Ces chemins sont en memoire et disparaissent avec le conteneur sandbox ; la configuration du conteneur Podman principal n’ajoute pas ses propres montages tmpfs.
Points chauds de croissance disque : les principaux chemins a surveiller sont media/, agents/<agentId>/sessions/sessions.json, les fichiers JSONL de transcription, cron/runs/*.jsonl et les logs fichier rotatifs sous /tmp/openclaw/ (ou votre logging.file configure).

setup-podman.sh stage desormais le tar de l’image dans un repertoire temporaire prive et affiche le repertoire de base choisi pendant la configuration. Pour les executions non-root, il accepte TMPDIR uniquement quand cette base est sure a utiliser ; sinon il se rabat sur /var/tmp, puis /tmp. Le tar sauvegarde reste en acces proprietaire uniquement et est streame dans le podman load de l’utilisateur cible, de sorte que les repertoires temporaires prives de l’appelant ne bloquent pas la configuration.

Commandes utiles

Logs : Avec quadlet : sudo journalctl --machine openclaw@ --user -u openclaw.service -f. Avec script : sudo -u openclaw podman logs -f openclaw
Arreter : Avec quadlet : sudo systemctl --machine openclaw@ --user stop openclaw.service. Avec script : sudo -u openclaw podman stop openclaw
Redemarrer : Avec quadlet : sudo systemctl --machine openclaw@ --user start openclaw.service. Avec script : relancez le script de lancement ou podman start openclaw
Supprimer le conteneur : sudo -u openclaw podman rm -f openclaw — la configuration et l’espace de travail sur l’hote sont conserves

Depannage

Permission refusee (EACCES) sur la config ou les profils d’auth : Le conteneur utilise par defaut --userns=keep-id et s’execute avec le meme uid/gid que l’utilisateur hote executant le script. Assurez-vous que vos OPENCLAW_CONFIG_DIR et OPENCLAW_WORKSPACE_DIR hote appartiennent a cet utilisateur.
Demarrage de la passerelle bloque (manque gateway.mode=local) : Assurez-vous que ~openclaw/.openclaw/openclaw.json existe et definit gateway.mode="local". setup-podman.sh cree ce fichier s’il manque.
Podman rootless echoue pour l’utilisateur openclaw : Verifiez que /etc/subuid et /etc/subgid contiennent une ligne pour openclaw (par ex. openclaw:100000:65536). Ajoutez-la si manquante et redemarrez.
Nom de conteneur deja utilise : Le script de lancement utilise podman run --replace, donc le conteneur existant est remplace au demarrage. Pour nettoyer manuellement : podman rm -f openclaw.
Script introuvable lors de l’execution en tant qu’openclaw : Assurez-vous que setup-podman.sh a ete execute pour que run-openclaw-podman.sh soit copie dans le home d’openclaw (par ex. /home/openclaw/run-openclaw-podman.sh).
Service quadlet introuvable ou ne demarre pas : Executez sudo systemctl --machine openclaw@ --user daemon-reload apres avoir edite le fichier .container. Quadlet necessite cgroups v2 : podman info --format '{{.Host.CgroupsVersion}}' devrait afficher 2.

Optionnel : executer en tant que votre propre utilisateur

Pour executer la passerelle en tant que votre utilisateur normal (pas d’utilisateur openclaw dedie) : construisez l’image, creez ~/.openclaw/.env avec OPENCLAW_GATEWAY_TOKEN, et executez le conteneur avec --userns=keep-id et des montages vers votre ~/.openclaw. Le script de lancement est concu pour le flux utilisateur openclaw ; pour une configuration mono-utilisateur, vous pouvez plutot executer la commande podman run du script manuellement, en pointant la config et l’espace de travail vers votre home. Recommande pour la plupart des utilisateurs : utilisez setup-podman.sh et executez en tant qu’utilisateur openclaw pour que la config et le processus soient isoles.