--- read_when: - Vuoi un Gateway containerizzato con Podman invece di Docker summary: Esegui OpenClaw in un contenitore Podman senza privilegi di root title: Podman x-i18n: generated_at: "2026-06-27T17:41:18Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: 3f6950956551dc3c274db33712cf66632fb5facbca4954bf67c30a8bff740c2f source_path: install/podman.md workflow: 16 --- 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 ...` 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 Dalla radice del repository, esegui `./scripts/podman/setup.sh`. Avvia il container con `./scripts/run-openclaw-podman.sh launch`. Esegui `./scripts/run-openclaw-podman.sh launch setup`, quindi apri `http://127.0.0.1:18789/`. Imposta `OPENCLAW_CONTAINER=openclaw`, quindi usa i normali comandi `openclaw` dall'host. 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: ```bash ./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: ```bash ./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: ```bash ./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: ```bash export OPENCLAW_CONTAINER=openclaw ``` Quindi comandi come questi verranno eseguiti automaticamente dentro quel container: ```bash 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--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](/it/gateway/tailscale) - [Control UI](/it/web/control-ui) ## Systemd (Quadlet, opzionale) Se hai eseguito `./scripts/podman/setup.sh --quadlet`, la configurazione installa un file Quadlet in: ```bash ~/.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: ```bash 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 corrente: ```bash 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 :` 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 ...`, oppure esporta `OPENCLAW_CONTAINER=` 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](/it/install/docker) - [Processo in background del Gateway](/it/gateway/background-process) - [Risoluzione dei problemi del Gateway](/it/gateway/troubleshooting)