Podman

Führen Sie das OpenClaw Gateway in einem Rootless-Podman-Container aus, der von Ihrem aktuellen Benutzer ohne Root-Rechte verwaltet wird.

Das Modell:

• Podman führt den Gateway-Container aus.
• Ihre hostseitige openclaw-CLI dient als Steuerungsebene.
• Persistenter Zustand wird standardmäßig auf dem Host unter ~/.openclaw gespeichert.
• Für die tägliche Verwaltung verwenden Sie openclaw --container <name> ... anstelle von sudo -u openclaw, podman exec oder einem separaten Dienstbenutzer.

Voraussetzungen

• Podman im Rootless-Modus
• OpenClaw-CLI auf dem Host installiert
• Optional: systemd --user, wenn Sie einen von Quadlet verwalteten automatischen Start wünschen
• Optional: sudo nur, wenn Sie loginctl enable-linger "$(whoami)" für den dauerhaften Start beim Hochfahren auf einem Monitor-losen Host verwenden möchten

Schnellstart

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

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

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

export OPENCLAW_CONTAINER=openclaw

openclaw dashboard --no-openopenclaw gateway status --deep   # umfasst eine zusätzliche Dienstsucheopenclaw doctoropenclaw channels login

Der manuelle Starter liest nur eine kleine Positivliste Podman-bezogener Schlüssel aus ~/.openclaw/.env und übergibt dem Container explizite Laufzeit-Umgebungsvariablen; er übergibt nicht die vollständige Umgebungsdatei an Podman.

Podman und Tailscale

Für HTTPS oder den Remote-Browserzugriff folgen Sie der Hauptdokumentation zu Tailscale.

Podman-spezifische Hinweise:

• Belassen Sie den Podman-Veröffentlichungshost auf 127.0.0.1.
• Bevorzugen Sie ein vom Host verwaltetes tailscale serve gegenüber openclaw gateway --tailscale serve.
• Wenn unter macOS der Geräteauthentifizierungskontext des lokalen Browsers unzuverlässig ist, verwenden Sie den Tailscale-Zugriff anstelle improvisierter lokaler Tunnel-Workarounds.

Siehe Tailscale und Control UI.

Systemd (Quadlet, optional)

Wenn Sie ./scripts/podman/setup.sh --quadlet ausgeführt haben, installiert das Setup eine Quadlet-Datei unter ~/.config/containers/systemd/openclaw.container.

Nach dem Bearbeiten der Quadlet-Datei:

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

Aktivieren Sie für die Startpersistenz auf SSH-/Headless-Hosts das Lingering für Ihren aktuellen Benutzer:

sudo loginctl enable-linger "$(whoami)"

Der generierte Quadlet-Dienst behält eine feste, gehärtete Standardkonfiguration bei: auf 127.0.0.1 veröffentlichte Ports (18789 für den Gateway, 18790 für die Bridge), --bind lan innerhalb des Containers, keep-id-Benutzernamensraum, OPENCLAW_NO_RESPAWN=1, Restart=on-failure und TimeoutStartSec=300. Er liest ~/.openclaw/.env als Laufzeit-EnvironmentFile für Werte wie OPENCLAW_GATEWAY_TOKEN, verwendet jedoch nicht die Podman-spezifische Überschreibungs-Zulassungsliste des manuellen Launchers. Verwenden Sie für benutzerdefinierte Veröffentlichungsports, einen benutzerdefinierten Veröffentlichungshost oder andere Container-Ausführungsflags stattdessen den manuellen Launcher, oder bearbeiten Sie ~/.config/containers/systemd/openclaw.container direkt und laden Sie anschließend den Dienst neu und starten Sie ihn neu.

Konfiguration, Umgebungsvariablen und Speicher

• Konfigurationsverzeichnis: ~/.openclaw
• Arbeitsbereichsverzeichnis: ~/.openclaw/workspace
• Token-Datei: ~/.openclaw/.env
• Starthilfe: ./scripts/run-openclaw-podman.sh

Das Startskript und Quadlet binden den Hostzustand per Bind-Mount in den Container ein: OPENCLAW_CONFIG_DIR -> /home/node/.openclaw, OPENCLAW_WORKSPACE_DIR -> /home/node/.openclaw/workspace. Standardmäßig handelt es sich dabei um Hostverzeichnisse und nicht um anonymen Containerzustand, sodass openclaw.json, agentenspezifische auth-profiles.json, Kanal-/Provider-Zustand, Sitzungen und der Arbeitsbereich den Austausch des Containers überstehen. Das Setup befüllt außerdem gateway.controlUi.allowedOrigins für 127.0.0.1 und localhost am veröffentlichten Gateway-Port, damit das lokale Dashboard mit der Nicht-Loopback-Bindung des Containers funktioniert.

Nützliche Umgebungsvariablen für den manuellen Launcher (speichern Sie diese dauerhaft in ~/.openclaw/.env; der Launcher liest diese Datei, bevor er die Container-/Image-Standardwerte festlegt):

Wenn Sie ein vom Standard abweichendes OPENCLAW_CONFIG_DIR oder OPENCLAW_WORKSPACE_DIR verwenden, setzen Sie dieselben Variablen sowohl für ./scripts/podman/setup.sh als auch für spätere ./scripts/run-openclaw-podman.sh launch-Befehle -- der repository-lokale Launcher speichert benutzerdefinierte Pfadüberschreibungen nicht über Shell-Sitzungen hinweg.

Images aktualisieren

Nachdem Sie ein neues Image erstellt oder abgerufen haben, starten Sie den Container oder den Quadlet-Dienst neu. Beim ersten Start einer neuen OpenClaw-Version führt der Gateway sichere Reparaturen des Zustands und der Plugins durch, bevor er seine Bereitschaft meldet.

Wenn der Gateway beendet wird, anstatt betriebsbereit zu werden, führen Sie dasselbe Image einmal mit openclaw doctor --fix für denselben eingebundenen Zustand und dieselbe Konfiguration aus und starten Sie anschließend den Gateway normal neu:

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

Fügen Sie auf SELinux-Hosts beiden Bind-Mounts ,Z hinzu, wenn Podman den Zugriff auf den eingebundenen Zustand blockiert.

Nützliche Befehle

• Containerprotokolle: podman logs -f openclaw
• Container stoppen: podman stop openclaw
• Container entfernen: podman rm -f openclaw
• Dashboard-URL über die Host-CLI öffnen: openclaw dashboard --no-open
• Integrität/Status über die Host-CLI: openclaw gateway status --deep (RPC-Prüfung + zusätzlicher Dienstscan)

Fehlerbehebung

• Zugriff verweigert (EACCES) bei Konfiguration oder Arbeitsbereich: Der Container wird standardmäßig mit --userns=keep-id und --user <your uid>:<your gid> ausgeführt. Stellen Sie sicher, dass die Konfigurations-/Arbeitsbereichspfade auf dem Host Ihrem aktuellen Benutzer gehören.
• Gateway-Start blockiert (gateway.mode=local fehlt): Stellen Sie sicher, dass ~/.openclaw/openclaw.json vorhanden ist und gateway.mode="local" setzt. scripts/podman/setup.sh erstellt dies, falls es fehlt.
• Container startet nach einer Image-Aktualisierung wiederholt neu: Führen Sie den einmaligen Befehl openclaw doctor --fix unter Images aktualisieren aus und starten Sie anschließend den Gateway erneut.
• Container-CLI-Befehle verwenden das falsche Ziel: Verwenden Sie ausdrücklich openclaw --container <name> ..., oder exportieren Sie OPENCLAW_CONTAINER=<name> in Ihrer Shell.
• openclaw update schlägt mit --container fehl: Dies ist erwartetes Verhalten. Erstellen oder laden Sie das Image neu und starten Sie anschließend den Container oder den Quadlet-Dienst neu.
• Quadlet-Dienst startet nicht: Führen Sie systemctl --user daemon-reload und anschließend systemctl --user start openclaw.service aus. Auf Headless-Systemen müssen Sie möglicherweise außerdem sudo loginctl enable-linger "$(whoami)" ausführen.
• SELinux blockiert Bind-Mounts: Behalten Sie das standardmäßige Mount-Verhalten bei; der Launcher fügt unter Linux automatisch :Z hinzu, wenn SELinux im Enforcing- oder Permissive-Modus ausgeführt wird.

Verwandte Themen

• Docker
• Gateway-Hintergrundprozess
• Gateway-Fehlerbehebung