Podman

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

Il modello previsto è:

• Podman esegue il container del gateway.
• La CLI openclaw dell'host è il piano di controllo.
• Lo stato persistente risiede sull'host in ~/.openclaw per impostazione predefinita.
• 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
• CLI OpenClaw installata sull'host
• Opzionale: systemd --user se vuoi l'avvio automatico gestito da Quadlet
• Opzionale: sudo solo se vuoi loginctl enable-linger "$(whoami)" per la persistenza all'avvio su un host headless

Avvio rapido

Dettagli della configurazione:

• ./scripts/podman/setup.sh compila openclaw:local nel tuo store Podman rootless per impostazione predefinita, oppure usa OPENCLAW_IMAGE / OPENCLAW_PODMAN_IMAGE se ne imposti uno.
• 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 variabili di ambiente di runtime esplicite al container; non passa l'intero file env a Podman.

Configurazione gestita da Quadlet:

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

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

Puoi anche impostare OPENCLAW_PODMAN_QUADLET=1.

Variabili env opzionali di build/configurazione:

• OPENCLAW_IMAGE o OPENCLAW_PODMAN_IMAGE -- usa un'immagine esistente/scaricata invece di compilare openclaw:local
• OPENCLAW_IMAGE_APT_PACKAGES -- installa pacchetti apt aggiuntivi durante la build dell'immagine (accetta anche il legacy OPENCLAW_DOCKER_APT_PACKAGES)
• OPENCLAW_IMAGE_PIP_PACKAGES -- installa pacchetti Python aggiuntivi durante la build dell'immagine; blocca le versioni e usa solo indici di pacchetti di cui ti fidi
• OPENCLAW_EXTENSIONS -- preinstalla le dipendenze dei Plugin in fase di 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 corrente usando --userns=keep-id e monta in bind lo stato OpenClaw nel container.

Onboarding:

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

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

Autenticazione dei modelli in Podman:

• Usa l'autenticazione gestita da OpenClaw durante la configurazione: chiavi API Anthropic per Anthropic, oppure autenticazione OAuth/device-code da browser OpenAI Codex per OpenAI basato su Codex.
• Il launcher Podman non monta le directory delle credenziali della CLI dell'host, come ~/.claude o ~/.codex, nel container di configurazione o del gateway.
• Gli accessi CLI esistenti sull'host sono percorsi di comodità sullo stesso host. Per le installazioni in container, mantieni l'autenticazione del provider nello stato montato ~/.openclaw gestito dalla configurazione.

Predefinito della CLI host:

export OPENCLAW_CONTAINER=openclaw

Quindi comandi come questi verranno eseguiti automaticamente dentro quel container:

openclaw dashboard --no-openopenclaw gateway status --deep   # includes extra service scanopenclaw doctoropenclaw 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 dal 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 del dispositivo del browser locale non è affidabile, usa l'accesso Tailscale invece di workaround locali ad hoc con tunnel.

Vedi:

• Tailscale
• Control UI

Systemd (Quadlet, opzionale)

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

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

Comandi utili:

• Avvia: systemctl --user start openclaw.service
• Arresta: 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-reloadsystemctl --user restart openclaw.service

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

sudo loginctl enable-linger "$(whoami)"

Configurazione, env e archiviazione

• Directory di configurazione: ~/.openclaw
• Directory del workspace: ~/.openclaw/workspace
• File del 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 sono directory dell'host, non stato anonimo del container, quindi openclaw.json, auth-profiles.json per agente, stato di canali/provider, sessioni e 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 persisterli lì.

Se usi un valore non predefinito di OPENCLAW_CONFIG_DIR o OPENCLAW_WORKSPACE_DIR, 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 repository non persiste gli override di percorso personalizzati tra shell.

Nota su Quadlet:

• Il servizio Quadlet generato mantiene intenzionalmente una forma predefinita fissa e rinforzata: 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 per Podman del launcher manuale.
• Se ti servono porte di pubblicazione, host di pubblicazione o altri flag di esecuzione del container personalizzati, usa il launcher manuale o 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
• Salute/stato tramite CLI host: openclaw gateway status --deep (probe RPC + scansione aggiuntiva 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 di configurazione/workspace sull'host appartengano al tuo utente corrente.
• 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 fallisce con --container: Previsto. Ricompila/scarica l'immagine, quindi riavvia il container o il servizio Quadlet.
• Il servizio Quadlet non si avvia: Esegui systemctl --user daemon-reload, quindi systemctl --user start openclaw.service. Sui sistemi headless potresti anche aver bisogno di 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 è in modalità enforcing o permissive.

Correlati

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