Podman

Esegui OpenClaw Gateway in un container Podman rootless, gestito dal tuo attuale utente non root.

Il modello previsto è:

• Podman esegue il container del Gateway.
• La openclaw CLI dell'host è il piano di controllo.
• Per impostazione predefinita, lo stato persistente risiede sull'host in ~/.openclaw.
• La gestione quotidiana usa openclaw --container <name> ... invece di sudo -u openclaw, podman exec o un utente di servizio separato.

# Prerequisiti

• Podman in modalità rootless
• OpenClaw CLI installata sull'host
• Facoltativo: systemd --user se vuoi l'avvio automatico gestito da Quadlet
• Facoltativo: sudo solo se vuoi loginctl enable-linger "$(whoami)" per la persistenza all'avvio su un host headless

# Avvio rapido

Dettagli di configurazione:

• ./scripts/podman/setup.sh crea openclaw:local nel tuo store Podman rootless per impostazione predefinita, oppure usa OPENCLAW_IMAGE / OPENCLAW_PODMAN_IMAGE se ne imposti una.
• Crea ~/.openclaw/openclaw.json con gateway.mode: "local" se manca.
• Crea ~/.openclaw/.env con OPENCLAW_GATEWAY_TOKEN se manca.
• Per gli avvii manuali, l'helper legge solo una piccola allowlist di chiavi relative a Podman da ~/.openclaw/.env e passa al container variabili env di runtime esplicite; non passa l'intero file env a Podman.

Configurazione gestita da Quadlet:

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

Quadlet è un'opzione solo Linux perché dipende dai servizi utente systemd.

Puoi anche impostare OPENCLAW_PODMAN_QUADLET=1.

Variabili env facoltative per build/configurazione:

• OPENCLAW_IMAGE o OPENCLAW_PODMAN_IMAGE -- usa un'immagine esistente/scaricata invece di crearere openclaw:local
• OPENCLAW_DOCKER_APT_PACKAGES -- installa pacchetti apt aggiuntivi durante la build dell'immagine
• OPENCLAW_EXTENSIONS -- preinstalla le dipendenze dei plugin al momento della build
• OPENCLAW_INSTALL_BROWSER -- preinstalla Chromium e Xvfb per l'automazione del browser (imposta a 1 per abilitare)

Avvio del container:

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

Lo script avvia il container con il tuo uid/gid attuale usando --userns=keep-id e monta in bind lo stato di OpenClaw nel container.

Onboarding:

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

Poi apri http://127.0.0.1:18789/ e usa il token da ~/.openclaw/.env.

Predefinito della CLI host:

export OPENCLAW_CONTAINER=openclaw

Poi comandi come questi verranno eseguiti automaticamente dentro quel container:

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

Su macOS, la macchina Podman può far apparire il browser come non locale al Gateway. Se la Control UI segnala errori di autenticazione del dispositivo dopo l'avvio, usa le indicazioni su Tailscale in Podman e Tailscale.

# Podman e Tailscale

Per HTTPS o accesso remoto da browser, segui la documentazione principale di Tailscale.

Nota specifica per Podman:

• Mantieni l'host di pubblicazione Podman su 127.0.0.1.
• Preferisci tailscale serve gestito dall'host rispetto a openclaw gateway --tailscale serve.
• Su macOS, se il contesto di autenticazione dispositivo del browser locale è inaffidabile, usa l'accesso tramite Tailscale invece di soluzioni alternative ad hoc con tunnel locali.

Vedi:

• Tailscale
• Control UI

# Systemd (Quadlet, facoltativo)

Se hai eseguito ./scripts/podman/setup.sh --quadlet, la configurazione installa un file Quadlet in:

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

Comandi utili:

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

Dopo aver modificato il file Quadlet:

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

Per la persistenza all'avvio su host SSH/headless, abilita il lingering per il tuo utente attuale:

sudo loginctl enable-linger "$(whoami)"

# Configurazione, env e archiviazione

• Directory di configurazione: ~/.openclaw
• Directory workspace: ~/.openclaw/workspace
• File token: ~/.openclaw/.env
• Helper di avvio: ./scripts/run-openclaw-podman.sh

Lo script di avvio e Quadlet montano in bind lo stato dell'host nel container:

• OPENCLAW_CONFIG_DIR -> /home/node/.openclaw
• OPENCLAW_WORKSPACE_DIR -> /home/node/.openclaw/workspace

Per impostazione predefinita queste sono directory host, non stato anonimo del container, quindi openclaw.json, i file auth-profiles.json per agente, lo stato di canali/provider, le sessioni e il workspace sopravvivono alla sostituzione del container. La configurazione Podman inizializza anche gateway.controlUi.allowedOrigins per 127.0.0.1 e localhost sulla porta Gateway pubblicata, così la dashboard locale funziona con il bind non local loopback del container.

Variabili env utili per il launcher manuale:

• OPENCLAW_PODMAN_CONTAINER -- nome del container (openclaw per impostazione predefinita)
• OPENCLAW_PODMAN_IMAGE / OPENCLAW_IMAGE -- immagine da eseguire
• OPENCLAW_PODMAN_GATEWAY_HOST_PORT -- porta host mappata alla porta container 18789
• OPENCLAW_PODMAN_BRIDGE_HOST_PORT -- porta host mappata alla porta container 18790
• OPENCLAW_PODMAN_PUBLISH_HOST -- interfaccia host per le porte pubblicate; il valore predefinito è 127.0.0.1
• OPENCLAW_GATEWAY_BIND -- modalità di bind del Gateway dentro il container; il valore predefinito è lan
• OPENCLAW_PODMAN_USERNS -- keep-id (predefinito), auto o host

Il launcher manuale legge ~/.openclaw/.env prima di finalizzare i valori predefiniti di container/immagine, quindi puoi renderli persistenti lì.

Se usi un OPENCLAW_CONFIG_DIR o OPENCLAW_WORKSPACE_DIR non predefinito, imposta le stesse variabili sia per ./scripts/podman/setup.sh sia per i successivi comandi ./scripts/run-openclaw-podman.sh launch. Il launcher locale del repo non persiste override di percorsi personalizzati tra shell.

Nota su Quadlet:

• Il servizio Quadlet generato mantiene intenzionalmente una forma predefinita fissa e rafforzata: porte pubblicate su 127.0.0.1, --bind lan dentro il container e namespace utente keep-id.
• Imposta OPENCLAW_NO_RESPAWN=1, Restart=on-failure e TimeoutStartSec=300.
• Pubblica sia 127.0.0.1:18789:18789 (Gateway) sia 127.0.0.1:18790:18790 (bridge).
• Legge ~/.openclaw/.env come EnvironmentFile di runtime per valori come OPENCLAW_GATEWAY_TOKEN, ma non consuma la allowlist di override specifici di Podman del launcher manuale.
• Se ti servono porte di pubblicazione personalizzate, un host di pubblicazione personalizzato o altri flag di esecuzione del container, usa il launcher manuale oppure modifica direttamente ~/.config/containers/systemd/openclaw.container, quindi ricarica e riavvia il servizio.

# Comandi utili

• Log del container: podman logs -f openclaw
• Arresta il container: podman stop openclaw
• Rimuovi il container: podman rm -f openclaw
• Apri l'URL della dashboard dalla CLI host: openclaw dashboard --no-open
• Integrità/stato tramite CLI host: openclaw gateway status --deep (probe RPC + scansione extra del servizio)

# Risoluzione dei problemi

• Permesso negato (EACCES) su configurazione o workspace: Il container viene eseguito con --userns=keep-id e --user <your uid>:<your gid> per impostazione predefinita. Assicurati che i percorsi host di configurazione/workspace siano di proprietà del tuo utente attuale.
• Avvio del Gateway bloccato (gateway.mode=local mancante): Assicurati che ~/.openclaw/openclaw.json esista e imposti gateway.mode="local". scripts/podman/setup.sh lo crea se manca.
• I comandi CLI del container raggiungono il target sbagliato: Usa esplicitamente openclaw --container <name> ..., oppure esporta OPENCLAW_CONTAINER=<name> nella tua shell.
• openclaw update non riesce con --container: Previsto. Ricrea/scarica l'immagine, quindi riavvia il container o il servizio Quadlet.
• Il servizio Quadlet non si avvia: Esegui systemctl --user daemon-reload, poi systemctl --user start openclaw.service. Sui sistemi headless potrebbe servirti anche sudo loginctl enable-linger "$(whoami)".
• SELinux blocca i mount bind: Lascia invariato il comportamento di mount predefinito; il launcher aggiunge automaticamente :Z su Linux quando SELinux è enforcing o permissive.

# Correlati

• Docker
• Processo in background del Gateway
• Risoluzione dei problemi del Gateway