Podman

Esegui il gateway OpenClaw in un container Podman rootless. Usa la stessa immagine di Docker (compilata dal Dockerfile del repository).

Requisiti

Podman (rootless)
Sudo per il setup iniziale (creazione utente, build immagine)

Avvio rapido

1. Setup iniziale (dalla root del repository; crea l’utente, compila l’immagine, installa lo script di avvio):

./setup-podman.sh

Questo crea anche un file minimale ~openclaw/.openclaw/openclaw.json (imposta gateway.mode="local") cosi il gateway puo avviarsi senza eseguire il wizard.

Per impostazione predefinita il container non viene installato come servizio systemd: lo avvii manualmente (vedi sotto). Per un setup in stile produzione con avvio automatico e riavvii, installalo come servizio utente systemd Quadlet:

./setup-podman.sh --quadlet

(Oppure imposta OPENCLAW_PODMAN_QUADLET=1; usa --container per installare solo il container e lo script di avvio.)

Variabili d’ambiente opzionali al momento della build (da impostare prima di eseguire setup-podman.sh):

OPENCLAW_DOCKER_APT_PACKAGES — installa pacchetti apt aggiuntivi durante la build dell’immagine
OPENCLAW_EXTENSIONS — pre-installa le dipendenze delle estensioni (nomi separati da spazi, es. diagnostics-otel matrix)

2. Avvia il gateway (manuale, per un test rapido):

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

3. Wizard di onboarding (es. per aggiungere canali o provider):

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

Poi apri http://127.0.0.1:18789/ e usa il token da ~openclaw/.openclaw/.env (o il valore stampato dal setup).

Systemd (Quadlet, opzionale)

Se hai eseguito ./setup-podman.sh --quadlet (o OPENCLAW_PODMAN_QUADLET=1), viene installata un’unita Podman Quadlet cosi il gateway gira come servizio utente systemd per l’utente openclaw. Il servizio viene abilitato e avviato al termine del setup.

Avvio: sudo systemctl --machine openclaw@ --user start openclaw.service
Arresto: sudo systemctl --machine openclaw@ --user stop openclaw.service
Stato: sudo systemctl --machine openclaw@ --user status openclaw.service
Log: sudo journalctl --machine openclaw@ --user -u openclaw.service -f

Il file quadlet si trova in ~openclaw/.config/containers/systemd/openclaw.container. Per cambiare porte o variabili d’ambiente, modifica quel file (o il .env che include), poi esegui sudo systemctl --machine openclaw@ --user daemon-reload e riavvia il servizio. Al boot, il servizio si avvia automaticamente se il lingering e abilitato per openclaw (il setup lo fa quando loginctl e disponibile).

Per aggiungere quadlet dopo un setup iniziale che non lo ha usato, riesegui: ./setup-podman.sh --quadlet.

setup-podman.sh crea un utente di sistema dedicato openclaw:

Shell: nologin — nessun login interattivo; riduce la superficie d’attacco.
Home: es. /home/openclaw — contiene ~/.openclaw (configurazione, workspace) e lo script di avvio run-openclaw-podman.sh.
Podman rootless: L’utente deve avere un range subuid e subgid. Molte distribuzioni li assegnano automaticamente alla creazione dell’utente. Se il setup mostra un avviso, aggiungi le righe a /etc/subuid e /etc/subgid:
```
openclaw:100000:65536
```
Poi avvia il gateway come quell’utente (es. da cron o systemd):
```
sudo -u openclaw /home/openclaw/run-openclaw-podman.sh
sudo -u openclaw /home/openclaw/run-openclaw-podman.sh setup
```
Configurazione: Solo openclaw e root possono accedere a /home/openclaw/.openclaw. Per modificare la configurazione: usa la Control UI una volta che il gateway e in esecuzione, oppure sudo -u openclaw $EDITOR /home/openclaw/.openclaw/openclaw.json.

Ambiente e configurazione

Token: Salvato in ~openclaw/.openclaw/.env come OPENCLAW_GATEWAY_TOKEN. setup-podman.sh e run-openclaw-podman.sh lo generano se mancante (usa openssl, python3 o od).
Opzionale: Nel .env puoi impostare chiavi provider (es. GROQ_API_KEY, OLLAMA_API_KEY) e altre variabili d’ambiente OpenClaw.
Porte host: Per impostazione predefinita lo script mappa 18789 (gateway) e 18790 (bridge). Sovrascrivi il mapping delle porte host con OPENCLAW_PODMAN_GATEWAY_HOST_PORT e OPENCLAW_PODMAN_BRIDGE_HOST_PORT all’avvio.
Binding del gateway: Per impostazione predefinita, run-openclaw-podman.sh avvia il gateway con --bind loopback per un accesso locale sicuro. Per esporre sulla LAN, imposta OPENCLAW_GATEWAY_BIND=lan e configura gateway.controlUi.allowedOrigins (o abilita esplicitamente il fallback dell’header host) in openclaw.json.
Percorsi: La configurazione host e il workspace usano per default ~openclaw/.openclaw e ~openclaw/.openclaw/workspace. Sovrascrivi i percorsi host usati dallo script di avvio con OPENCLAW_CONFIG_DIR e OPENCLAW_WORKSPACE_DIR.

Modello di storage

Dati host persistenti: OPENCLAW_CONFIG_DIR e OPENCLAW_WORKSPACE_DIR sono montati via bind nel container e mantengono lo stato sull’host.
Tmpfs sandbox effimero: se abiliti agents.defaults.sandbox, i container sandbox degli strumenti montano tmpfs su /tmp, /var/tmp e /run. Quei percorsi sono in memoria e scompaiono con il container sandbox; il setup del container Podman principale non aggiunge mount tmpfs propri.
Hotspot di crescita disco: i percorsi principali da tenere sotto controllo sono media/, agents/<agentId>/sessions/sessions.json, file transcript JSONL, cron/runs/*.jsonl e i file di log a rotazione sotto /tmp/openclaw/ (o il logging.file configurato).

setup-podman.sh ora prepara il tar dell’immagine in una directory temp privata e stampa la directory base scelta durante il setup. Per esecuzioni non-root accetta TMPDIR solo quando la base e sicura da usare; altrimenti ricade su /var/tmp, poi /tmp. Il tar salvato resta riservato al proprietario e viene trasmesso in streaming nel podman load dell’utente destinatario, cosi le directory temp private del chiamante non bloccano il setup.

Comandi utili

Log: Con quadlet: sudo journalctl --machine openclaw@ --user -u openclaw.service -f. Con script: sudo -u openclaw podman logs -f openclaw
Arresto: Con quadlet: sudo systemctl --machine openclaw@ --user stop openclaw.service. Con script: sudo -u openclaw podman stop openclaw
Riavvio: Con quadlet: sudo systemctl --machine openclaw@ --user start openclaw.service. Con script: riesegui lo script di avvio o podman start openclaw
Rimozione container: sudo -u openclaw podman rm -f openclaw — la configurazione e il workspace sull’host vengono conservati

Risoluzione problemi

Permesso negato (EACCES) su configurazione o profili auth: Il container usa --userns=keep-id per default e gira con lo stesso uid/gid dell’utente host che esegue lo script. Assicurati che OPENCLAW_CONFIG_DIR e OPENCLAW_WORKSPACE_DIR sull’host siano di proprieta di quell’utente.
Avvio del gateway bloccato (manca gateway.mode=local): Assicurati che ~openclaw/.openclaw/openclaw.json esista e imposti gateway.mode="local". setup-podman.sh crea questo file se mancante.
Podman rootless fallisce per l’utente openclaw: Controlla che /etc/subuid e /etc/subgid contengano una riga per openclaw (es. openclaw:100000:65536). Aggiungila se mancante e riavvia.
Nome container gia in uso: Lo script di avvio usa podman run --replace, quindi il container esistente viene sostituito quando riavvii. Per pulizia manuale: podman rm -f openclaw.
Script non trovato durante l’esecuzione come openclaw: Assicurati che setup-podman.sh sia stato eseguito, cosi che run-openclaw-podman.sh sia copiato nella home di openclaw (es. /home/openclaw/run-openclaw-podman.sh).
Servizio quadlet non trovato o non si avvia: Esegui sudo systemctl --machine openclaw@ --user daemon-reload dopo aver modificato il file .container. Quadlet richiede cgroups v2: podman info --format '{{.Host.CgroupsVersion}}' deve mostrare 2.

Opzionale: esegui come il tuo utente

Per eseguire il gateway come il tuo utente normale (senza utente openclaw dedicato): compila l’immagine, crea ~/.openclaw/.env con OPENCLAW_GATEWAY_TOKEN, ed esegui il container con --userns=keep-id e i mount verso la tua ~/.openclaw. Lo script di avvio e pensato per il flusso con l’utente openclaw; per un setup a utente singolo puoi invece eseguire manualmente il comando podman run dallo script, puntando configurazione e workspace verso la tua home. Consigliato per la maggior parte degli utenti: usa setup-podman.sh ed esegui come l’utente openclaw cosi configurazione e processo sono isolati.