Skip to main content
Voer de OpenClaw Gateway uit in een rootless Podman-container, beheerd door je huidige niet-rootgebruiker. Het model:
  • Podman voert de Gateway-container uit.
  • De openclaw-CLI op je host is het besturingsvlak.
  • Persistente status wordt standaard op de host opgeslagen onder ~/.openclaw.
  • Voor dagelijks beheer gebruik je openclaw --container <name> ... in plaats van sudo -u openclaw, podman exec of een afzonderlijke servicegebruiker.

​
Vereisten

  • Podman in rootless-modus
  • OpenClaw-CLI geïnstalleerd op de host
  • Optioneel: systemd --user als je automatisch starten via Quadlet wilt beheren
  • Optioneel: sudo alleen als je loginctl enable-linger "$(whoami)" wilt voor persistentie tijdens het opstarten op een headless host

​
Snel aan de slag

1

Eenmalige configuratie

Voer vanuit de hoofdmap van de repository ./scripts/podman/setup.sh uit.Hiermee wordt openclaw:local gebouwd in je rootless Podman-opslag (of OPENCLAW_IMAGE / OPENCLAW_PODMAN_IMAGE opgehaald indien ingesteld), wordt ~/.openclaw/openclaw.json met gateway.mode: "local" aangemaakt als deze ontbreekt en wordt ~/.openclaw/.env met een gegenereerde OPENCLAW_GATEWAY_TOKEN aangemaakt als deze ontbreekt.Optionele omgevingsvariabelen voor de build:Voor een door Quadlet beheerde configuratie (alleen Linux + systemd-gebruikersservices):
Of stel OPENCLAW_PODMAN_QUADLET=1 in.
2

De Gateway-container starten

Start de container met je huidige uid/gid en --userns=keep-id en koppelt je OpenClaw-status via een bind-mount aan de container.
3

Onboarding uitvoeren in de container

Open vervolgens http://127.0.0.1:18789/ en gebruik het token uit ~/.openclaw/.env.Modelauthenticatie: gebruik tijdens de configuratie door OpenClaw beheerde authenticatie (Anthropic-API-sleutels of OpenAI Codex-browser-OAuth/apparaatcodeauthenticatie voor door Codex ondersteunde OpenAI). Het Podman-startprogramma koppelt de referentiemappen van de host-CLI, zoals ~/.claude of ~/.codex, niet aan de configuratie- of Gateway-container. Bestaande aanmeldingen van de host-CLI zijn alleen gemakspaden op dezelfde host — bewaar voor containerinstallaties de providerauthenticatie in de gekoppelde ~/.openclaw-status die door de configuratie wordt beheerd.
4

De actieve container beheren via de host-CLI

Normale openclaw-opdrachten worden vervolgens automatisch in die container uitgevoerd:
Op macOS kan Podman machine ervoor zorgen dat de browser voor de Gateway niet-lokaal lijkt. Als de Control UI na het starten fouten voor apparaatauthenticatie meldt, gebruik dan de Tailscale-richtlijnen in Podman en Tailscale.
Het handmatige startprogramma leest slechts een kleine toelatingslijst met Podman-gerelateerde sleutels uit ~/.openclaw/.env en geeft expliciete runtime-omgevingsvariabelen door aan de container; het geeft niet het volledige omgevingsbestand door aan Podman.

​
Podman en Tailscale

Volg voor HTTPS of externe browsertoegang de algemene Tailscale-documentatie. Specifieke opmerkingen voor Podman:
  • Houd de Podman-publicatiehost op 127.0.0.1.
  • Geef de voorkeur aan door de host beheerde tailscale serve boven openclaw gateway --tailscale serve.
  • Gebruik op macOS Tailscale-toegang in plaats van geïmproviseerde lokale tunneloplossingen als de apparaatauthenticatiecontext van de lokale browser onbetrouwbaar is.
Zie Tailscale en Control UI.

​
Systemd (Quadlet, optioneel)

Als je ./scripts/podman/setup.sh --quadlet hebt uitgevoerd, installeert de configuratie een Quadlet-bestand op ~/.config/containers/systemd/openclaw.container. Na het bewerken van het Quadlet-bestand:
Schakel lingering in voor je huidige gebruiker voor persistentie tijdens het opstarten op SSH-/headless hosts:
De gegenereerde Quadlet-service behoudt een vaste, geharde standaardvorm: 127.0.0.1 gepubliceerde poorten (18789 Gateway, 18790 bridge), --bind lan in de container, keep-id gebruikersnaamruimte, OPENCLAW_NO_RESPAWN=1, Restart=on-failure en TimeoutStartSec=300. Deze leest ~/.openclaw/.env als een runtime-EnvironmentFile voor waarden zoals OPENCLAW_GATEWAY_TOKEN, maar gebruikt niet de Podman-specifieke toelatingslijst met overrides van het handmatige startprogramma. Gebruik voor aangepaste publicatiepoorten, een aangepaste publicatiehost of andere vlaggen voor het uitvoeren van containers het handmatige startprogramma, of bewerk ~/.config/containers/systemd/openclaw.container rechtstreeks en laad en herstart vervolgens de service.

​
Configuratie, omgeving en opslag

  • Configuratiemap: ~/.openclaw
  • Werkruimtemap: ~/.openclaw/workspace
  • Tokenbestand: ~/.openclaw/.env
  • Starthulpprogramma: ./scripts/run-openclaw-podman.sh
Het startscript en Quadlet koppelen de hoststatus via bind-mounts aan de container: OPENCLAW_CONFIG_DIR -> /home/node/.openclaw, OPENCLAW_WORKSPACE_DIR -> /home/node/.openclaw/workspace. Dit zijn standaard hostmappen, geen anonieme containerstatus, zodat openclaw.json, auth-profiles.json per agent, kanaal-/providerstatus, sessies en de werkruimte behouden blijven wanneer de container wordt vervangen. De configuratie vult ook gateway.controlUi.allowedOrigins vooraf in voor 127.0.0.1 en localhost op de gepubliceerde Gateway-poort, zodat het lokale dashboard werkt met de niet-loopbackbinding van de container. Nuttige omgevingsvariabelen voor het handmatige startprogramma (bewaar deze in ~/.openclaw/.env; het startprogramma leest dit bestand voordat het de standaardwaarden voor de container/image definitief maakt): Als je een niet-standaard OPENCLAW_CONFIG_DIR of OPENCLAW_WORKSPACE_DIR gebruikt, stel dan dezelfde variabelen in voor zowel ./scripts/podman/setup.sh als latere ./scripts/run-openclaw-podman.sh launch-opdrachten — het repositorylokale startprogramma bewaart aangepaste padoverschrijvingen niet tussen shells.

​
Images upgraden

Start de container of Quadlet-service opnieuw nadat je een nieuwe image hebt gebouwd of opgehaald. Bij de eerste start van een nieuwe OpenClaw-versie voert de Gateway veilige reparaties aan de status en plugins uit voordat deze meldt dat hij gereed is. Als de Gateway afsluit in plaats van gereed te worden, voer je dezelfde image eenmaal uit met openclaw doctor --fix voor dezelfde gekoppelde status/configuratie en start je de Gateway vervolgens normaal opnieuw:
Voeg op SELinux-hosts ,Z toe aan beide bind-mounts als Podman de toegang tot de gekoppelde status blokkeert.

​
Nuttige opdrachten

  • Containerlogboeken: podman logs -f openclaw
  • Container stoppen: podman stop openclaw
  • Container verwijderen: podman rm -f openclaw
  • Dashboard-URL openen vanuit de host-CLI: openclaw dashboard --no-open
  • Gezondheid/status via de host-CLI: openclaw gateway status --deep (RPC-probe + extra servicescan)

​
Problemen oplossen

  • Toegang geweigerd (EACCES) voor configuratie of werkruimte: De container wordt standaard uitgevoerd met --userns=keep-id en --user <your uid>:<your gid>. Zorg dat de configuratie-/werkruimtepaden op de host eigendom zijn van je huidige gebruiker.
  • Starten van Gateway geblokkeerd (gateway.mode=local ontbreekt): Zorg dat ~/.openclaw/openclaw.json bestaat en gateway.mode="local" instelt. scripts/podman/setup.sh maakt dit aan als het ontbreekt.
  • Container wordt opnieuw gestart na een image-update: Voer de eenmalige openclaw doctor --fix-opdracht uit in Images upgraden en start de Gateway vervolgens opnieuw.
  • CLI-opdrachten voor de container bereiken het verkeerde doel: Gebruik openclaw --container <name> ... expliciet of exporteer OPENCLAW_CONTAINER=<name> in je shell.
  • openclaw update mislukt met --container: Dit is te verwachten. Bouw de image opnieuw of haal deze op en start vervolgens de container of Quadlet-service opnieuw.
  • Quadlet-service start niet: Voer systemctl --user daemon-reload uit en daarna systemctl --user start openclaw.service. Op headless systemen heb je mogelijk ook sudo loginctl enable-linger "$(whoami)" nodig.
  • SELinux blokkeert bind-mounts: Laat het standaard mountgedrag ongewijzigd; het startprogramma voegt op Linux automatisch :Z toe wanneer SELinux in enforcing- of permissive-modus staat.

​
Gerelateerd