Podman

Esegui il Gateway OpenClaw in un container Podman senza privilegi di root, gestito dall’utente corrente non root. Il modello:

Podman esegue il container del Gateway.
La CLI openclaw dell’host funge da piano di controllo.
Per impostazione predefinita, lo stato persistente risiede sull’host in ~/.openclaw.
La gestione quotidiana utilizza openclaw --container <name> ... anziché sudo -u openclaw, podman exec o un utente di servizio separato.

Prerequisiti

Podman in modalità senza privilegi di root
CLI OpenClaw installata sull’host
Facoltativo: systemd --user se desideri l’avvio automatico gestito da Quadlet
Facoltativo: sudo solo se desideri usare loginctl enable-linger "$(whoami)" per mantenere il servizio attivo all’avvio su un host headless

Avvio rapido

Configurazione iniziale

Dalla radice del repository, esegui ./scripts/podman/setup.sh.Questo comando compila openclaw:local nell’archivio Podman senza privilegi di root (oppure scarica OPENCLAW_IMAGE / OPENCLAW_PODMAN_IMAGE, se impostata), crea ~/.openclaw/openclaw.json con gateway.mode: "local" se non esiste e crea ~/.openclaw/.env con un OPENCLAW_GATEWAY_TOKEN generato se non esiste.Variabili di ambiente facoltative per la compilazione:

Variabile	Effetto
`OPENCLAW_IMAGE` / `OPENCLAW_PODMAN_IMAGE`	Utilizza un’immagine esistente/scaricata anziché compilare `openclaw:local`
`OPENCLAW_IMAGE_APT_PACKAGES`	Installa pacchetti apt aggiuntivi durante la compilazione dell’immagine (accetta anche la variabile precedente `OPENCLAW_DOCKER_APT_PACKAGES`)
`OPENCLAW_IMAGE_PIP_PACKAGES`	Installa pacchetti Python aggiuntivi durante la compilazione dell’immagine; specifica le versioni e utilizza solo indici di pacchetti attendibili
`OPENCLAW_EXTENSIONS`	Compila/crea i pacchetti dei plugin selezionati supportati e installa le relative dipendenze di runtime
`OPENCLAW_INSTALL_BROWSER`	Preinstalla Chromium e Xvfb per l’automazione del browser (imposta su `1`)

In alternativa, per una configurazione gestita da Quadlet (solo Linux con servizi utente systemd):

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

Oppure imposta OPENCLAW_PODMAN_QUADLET=1.

Avvia il container del Gateway

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

Avvia il container con l’uid/gid dell’utente corrente usando --userns=keep-id e monta tramite bind lo stato di OpenClaw nel container.

Esegui la configurazione iniziale nel container

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

Quindi apri http://127.0.0.1:18789/ e usa il token presente in ~/.openclaw/.env.Autenticazione del modello: durante la configurazione usa l’autenticazione gestita da OpenClaw (chiavi API Anthropic oppure autenticazione OAuth tramite browser/codice dispositivo di OpenAI Codex per OpenAI basato su Codex). Il programma di avvio Podman non monta nel container di configurazione o del Gateway le directory delle credenziali delle CLI dell’host, come ~/.claude o ~/.codex. Gli accessi esistenti alle CLI dell’host sono soltanto percorsi pratici sullo stesso host; per le installazioni in container, conserva l’autenticazione dei provider nello stato ~/.openclaw montato e gestito dalla configurazione.

Gestisci il container in esecuzione dalla CLI dell'host

export OPENCLAW_CONTAINER=openclaw

I normali comandi openclaw vengono quindi eseguiti automaticamente all’interno del container:

openclaw dashboard --no-open
openclaw gateway status --deep   # include un'ulteriore scansione dei servizi
openclaw doctor
openclaw channels login

Su macOS, la macchina Podman può far apparire il browser come non locale al Gateway. Se dopo l’avvio l’interfaccia di controllo segnala errori di autenticazione del dispositivo, segui le indicazioni relative a Tailscale in Podman e Tailscale.

Il programma di avvio manuale legge da ~/.openclaw/.env soltanto un piccolo elenco consentito di chiavi relative a Podman e passa al container variabili di ambiente di runtime esplicite; non fornisce a Podman l’intero file di ambiente.

Podman e Tailscale

Per l’accesso HTTPS o remoto tramite browser, segui la documentazione principale di Tailscale. Note specifiche per Podman:

Mantieni l’host di pubblicazione Podman su 127.0.0.1.
Preferisci tailscale serve gestito dall’host a openclaw gateway --tailscale serve.
Su macOS, se il contesto locale di autenticazione del dispositivo tramite browser non è affidabile, utilizza l’accesso tramite Tailscale anziché soluzioni temporanee basate su tunnel locali.

Consulta Tailscale e Interfaccia di controllo.

Systemd (Quadlet, facoltativo)

Se hai eseguito ./scripts/podman/setup.sh --quadlet, la configurazione installa un file Quadlet in ~/.config/containers/systemd/openclaw.container.

Azione	Comando
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-reload
systemctl --user restart openclaw.service

Per mantenere il servizio attivo all’avvio sugli host SSH/headless, abilita il lingering per l’utente corrente:

sudo loginctl enable-linger "$(whoami)"

Il servizio Quadlet generato mantiene una configurazione predefinita fissa e rafforzata: porte pubblicate su 127.0.0.1 (18789 per il Gateway, 18790 per il bridge), --bind lan all’interno del container, spazio dei nomi utente keep-id, OPENCLAW_NO_RESPAWN=1, Restart=on-failure e TimeoutStartSec=300. Legge ~/.openclaw/.env come EnvironmentFile di runtime per valori come OPENCLAW_GATEWAY_TOKEN, ma non utilizza l’elenco consentito di sostituzioni specifiche di Podman del programma di avvio manuale. Per porte di pubblicazione personalizzate, un host di pubblicazione personalizzato o altri flag di esecuzione del container, usa invece il programma di avvio manuale oppure modifica direttamente ~/.config/containers/systemd/openclaw.container, quindi ricarica e riavvia il servizio.

Configurazione, ambiente e archiviazione

Directory di configurazione: ~/.openclaw
Directory dell’area di lavoro: ~/.openclaw/workspace
File del token: ~/.openclaw/.env
Script ausiliario di avvio: ./scripts/run-openclaw-podman.sh

Lo script di avvio e Quadlet montano tramite bind lo stato dell’host nel container: OPENCLAW_CONFIG_DIR -> /home/node/.openclaw, OPENCLAW_WORKSPACE_DIR -> /home/node/.openclaw/workspace. Per impostazione predefinita, si tratta di directory dell’host e non di stato anonimo del container; pertanto openclaw.json, i file auth-profiles.json dei singoli agenti, lo stato dei canali/provider, le sessioni e l’area di lavoro persistono dopo la sostituzione del container. La configurazione inizializza inoltre gateway.controlUi.allowedOrigins per 127.0.0.1 e localhost sulla porta pubblicata del Gateway, affinché la dashboard locale funzioni con il binding non-local loopback del container. Variabili di ambiente utili per il programma di avvio manuale (salvale in ~/.openclaw/.env; il programma di avvio legge questo file prima di determinare le impostazioni predefinite definitive del container e dell’immagine):

Variabile	Valore predefinito	Effetto
`OPENCLAW_PODMAN_CONTAINER`	`openclaw`	Nome del container
`OPENCLAW_PODMAN_IMAGE` / `OPENCLAW_IMAGE`	`openclaw:local`	Immagine da eseguire
`OPENCLAW_PODMAN_GATEWAY_HOST_PORT`	`18789`	Porta dell’host associata alla porta `18789` del container
`OPENCLAW_PODMAN_BRIDGE_HOST_PORT`	`18790`	Porta dell’host associata alla porta `18790` del container
`OPENCLAW_PODMAN_PUBLISH_HOST`	`127.0.0.1`	Interfaccia dell’host per le porte pubblicate
`OPENCLAW_GATEWAY_BIND`	`lan`	Modalità di binding del Gateway nel container
`OPENCLAW_PODMAN_USERNS`	`keep-id`	`keep-id`, `auto` o `host`

Se utilizzi valori non predefiniti per 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 programma di avvio locale del repository non mantiene le sostituzioni personalizzate dei percorsi tra una shell e l’altra.

Aggiornamento delle immagini

Dopo aver ricompilato o scaricato una nuova immagine, riavvia il container o il servizio Quadlet. Al primo avvio di una nuova versione di OpenClaw, il Gateway esegue riparazioni sicure dello stato e dei plugin prima di segnalare di essere pronto. Se il Gateway termina anziché diventare pronto, esegui una volta la stessa immagine con openclaw doctor --fix sullo stesso stato/configurazione montato, quindi riavvia normalmente il Gateway:

OPENCLAW_CONFIG_DIR="${OPENCLAW_CONFIG_DIR:-$HOME/.openclaw}"
OPENCLAW_WORKSPACE_DIR="${OPENCLAW_WORKSPACE_DIR:-$OPENCLAW_CONFIG_DIR/workspace}"
OPENCLAW_PODMAN_IMAGE="${OPENCLAW_PODMAN_IMAGE:-${OPENCLAW_IMAGE:-openclaw:local}}"

podman run --rm -it \
  --userns=keep-id \
  --user "$(id -u):$(id -g)" \
  -e HOME=/home/node \
  -e NPM_CONFIG_CACHE=/home/node/.openclaw/.npm \
  -v "$OPENCLAW_CONFIG_DIR:/home/node/.openclaw:rw" \
  -v "$OPENCLAW_WORKSPACE_DIR:/home/node/.openclaw/workspace:rw" \
  "$OPENCLAW_PODMAN_IMAGE" \
  openclaw doctor --fix

Sugli host SELinux, aggiungi ,Z a entrambi i montaggi bind se Podman blocca l’accesso allo stato montato.

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 dell’host: openclaw dashboard --no-open
Integrità/stato tramite la CLI dell’host: openclaw gateway status --deep (sonda RPC + ulteriore scansione dei servizi)

Risoluzione dei problemi

Permesso negato (EACCES) per la configurazione o l’area di lavoro: Per impostazione predefinita, il container viene eseguito con --userns=keep-id e --user <il tuo uid>:<il tuo gid>. Assicurati che i percorsi di configurazione/area di lavoro sull’host appartengano all’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.
Il container si riavvia dopo l’aggiornamento di un’immagine: Esegui il comando monouso openclaw doctor --fix descritto in Aggiornamento delle immagini, quindi avvia nuovamente il Gateway.
I comandi della CLI del container raggiungono la destinazione errata: Usa esplicitamente openclaw --container <name> ... oppure esporta OPENCLAW_CONTAINER=<name> nella shell.
openclaw update non riesce 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 potrebbe essere necessario anche eseguire sudo loginctl enable-linger "$(whoami)".
SELinux blocca i montaggi bind: Non modificare il comportamento predefinito dei montaggi; il programma di avvio aggiunge automaticamente :Z su Linux quando SELinux è in modalità enforcing o permissive.

Install overview

Maintenance

Containers

Hosting

Advanced setup

Prerequisiti

Avvio rapido

Podman e Tailscale

Systemd (Quadlet, facoltativo)

Configurazione, ambiente e archiviazione

Aggiornamento delle immagini

Comandi utili

Risoluzione dei problemi

Risorse correlate

​Prerequisiti

​Avvio rapido

​Podman e Tailscale

​Systemd (Quadlet, facoltativo)

​Configurazione, ambiente e archiviazione

​Aggiornamento delle immagini

​Comandi utili

​Risoluzione dei problemi

​Risorse correlate

Prerequisiti

Avvio rapido

Podman e Tailscale

Systemd (Quadlet, facoltativo)

Configurazione, ambiente e archiviazione

Aggiornamento delle immagini

Comandi utili

Risoluzione dei problemi

Risorse correlate