OpenClaw mit Podman ausführen: Rootless Setup in Minuten

Kennst du das Problem? Du möchtest eine neue Software testen, aber die Abhängigkeiten kollidieren mit deinem restlichen System. Oft endet das in einem Chaos aus Konfigurationsdateien und unklaren Berechtigungen, die man später mühsam aufräumen muss.

Podman bietet hier eine saubere Lösung. Mit rootless Containern isolierst du deine Umgebung, ohne deinem System unnötige Sicherheitsrisiken durch Root-Rechte auszusetzen. In dieser Anleitung zeige ich dir, wie du das OpenClaw Gateway sicher und effizient mit Podman betreibst.

Podman

Betreibe das OpenClaw Gateway in einem rootless Podman-Container. Es wird dasselbe Image wie für Docker verwendet (erstellt aus dem Dockerfile im Repo).

Voraussetzungen

• Podman (rootless)
• Sudo für das einmalige Setup (User anlegen, Image builden)

Schnellstart

1. Einmaliges Setup (vom Repo-Root aus; erstellt den User, baut das Image und installiert das Launch-Script):

./setup-podman.sh

Dabei wird auch eine minimale ~openclaw/.openclaw/openclaw.json erstellt (setzt gateway.mode="local"), damit das Gateway ohne den Wizard starten kann.

Standardmäßig wird der Container nicht als systemd-Service installiert; du startest ihn manuell (siehe unten). Für ein produktives Setup mit automatischem Start und Restarts solltest du ihn stattdessen als systemd Quadlet User-Service installieren:

./setup-podman.sh --quadlet

(Alternativ kannst du OPENCLAW_PODMAN_QUADLET=1 setzen; verwende --container, um nur den Container und das Launch-Script zu installieren.)

Optionale Umgebungsvariablen für den Build (vor dem Ausführen von setup-podman.sh setzen):

• OPENCLAW_DOCKER_APT_PACKAGES — installiert zusätzliche apt-Pakete während des Image-Builds
• OPENCLAW_EXTENSIONS — installiert Extension-Abhängigkeiten vorab (leerzeichengetrennte Namen, z. B. diagnostics-otel matrix)

2. Gateway starten (manuell, für einen schnellen Test):

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

3. Onboarding-Wizard (z. B. um Channels oder Provider hinzuzufügen):

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

Öffne dann http://127.0.0.1:18789/ und verwende das Token aus ~openclaw/.openclaw/.env (oder den Wert, der beim Setup ausgegeben wurde).

Systemd (Quadlet, optional)

Wenn du ./setup-podman.sh --quadlet (oder OPENCLAW_PODMAN_QUADLET=1) ausgeführt hast, wird eine Podman Quadlet Unit installiert. So läuft das Gateway als systemd User-Service für den openclaw-User. Der Service wird am Ende des Setups aktiviert und gestartet.

• Start: sudo systemctl --machine openclaw@ --user start openclaw.service
• Stop: sudo systemctl --machine openclaw@ --user stop openclaw.service
• Status: sudo systemctl --machine openclaw@ --user status openclaw.service
• Logs: sudo journalctl --machine openclaw@ --user -u openclaw.service -f

Die Quadlet-Datei liegt unter ~openclaw/.config/containers/systemd/openclaw.container. Um Ports oder die Umgebung zu ändern, bearbeite diese Datei (oder die .env, die sie einbindet). Führe danach sudo systemctl --machine openclaw@ --user daemon-reload aus und starte den Service neu. Beim Booten startet der Service automatisch, sofern “Lingering” für den openclaw-User aktiviert ist (das Setup erledigt das, wenn loginctl verfügbar ist).

Um Quadlet nach einem initialen Setup ohne diese Option hinzuzufügen, führe den Befehl erneut aus: ./setup-podman.sh --quadlet.

Der openclaw-User (non-login)

setup-podman.sh erstellt einen dedizierten System-User namens openclaw:

• Shell: nologin — kein interaktiver Login möglich; das reduziert die Angriffsfläche.

• Home: z. B. /home/openclaw — enthält ~/.openclaw (Konfiguration, Workspace) und das Launch-Script run-openclaw-podman.sh.

• Rootless Podman: Der User benötigt eine subuid und subgid Range. Viele Distributionen weisen diese automatisch zu, wenn der User erstellt wird. Falls das Setup eine Warnung ausgibt, füge Zeilen zu /etc/subuid und /etc/subgid hinzu:

  openclaw:100000:65536

  Starte das Gateway dann als dieser User (z. B. via Cron oder systemd):

  sudo -u openclaw /home/openclaw/run-openclaw-podman.sh
  sudo -u openclaw /home/openclaw/run-openclaw-podman.sh setup

• Konfiguration: Nur openclaw und Root können auf /home/openclaw/.openclaw zugreifen. Um die Konfiguration zu bearbeiten: Nutze das Control UI, sobald das Gateway läuft, oder verwende sudo -u openclaw $EDITOR /home/openclaw/.openclaw/openclaw.json.

Umgebung und Konfiguration

• Token: Gespeichert in ~openclaw/.openclaw/.env als OPENCLAW_GATEWAY_TOKEN. setup-podman.sh und run-openclaw-podman.sh generieren es, falls es fehlt (verwendet openssl, python3 oder od).
• Optional: In dieser .env kannst du Provider-Keys (z. B. GROQ_API_KEY, OLLAMA_API_KEY) und andere OpenClaw-Umgebungsvariablen setzen.
• Host-Ports: Standardmäßig mappt das Script 18789 (Gateway) und 18790 (Bridge). Du kannst das Host-Port-Mapping beim Start mit OPENCLAW_PODMAN_GATEWAY_HOST_PORT und OPENCLAW_PODMAN_BRIDGE_HOST_PORT überschreiben.
• Gateway Bind: Standardmäßig startet run-openclaw-podman.sh das Gateway mit --bind loopback für sicheren lokalen Zugriff. Um es im LAN freizugeben, setze OPENCLAW_GATEWAY_BIND=lan und konfiguriere gateway.controlUi.allowedOrigins (oder aktiviere explizit den Host-Header-Fallback) in der openclaw.json.
• Pfade: Host-Konfiguration und Workspace liegen standardmäßig unter ~openclaw/.openclaw und ~openclaw/.openclaw/workspace. Du kannst die vom Launch-Script verwendeten Host-Pfade mit OPENCLAW_CONFIG_DIR und OPENCLAW_WORKSPACE_DIR überschreiben.

Speichermodell

• Persistente Host-Daten: OPENCLAW_CONFIG_DIR und OPENCLAW_WORKSPACE_DIR werden per Bind-Mount in den Container eingebunden und behalten ihren Zustand auf dem Host.
• Ephemerer Sandbox-tmpfs: Wenn du agents.defaults.sandbox aktivierst, mounten die Tool-Sandbox-Container tmpfs unter /tmp, /var/tmp und /run. Diese Pfade sind speicherbasiert und verschwinden mit dem Sandbox-Container; das Podman-Setup auf oberster Ebene fügt keine eigenen tmpfs-Mounts hinzu.
• Speicher-Hotspots: Die wichtigsten Pfade, die du im Auge behalten solltest, sind media/, agents/<agentId>/sessions/sessions.json, Transkript-JSONL-Dateien, cron/runs/*.jsonl und rollierende Logdateien unter /tmp/openclaw/ (oder deinem konfigurierten logging.file).

setup-podman.sh legt das Image-Tar jetzt in einem privaten temporären Verzeichnis ab und gibt das gewählte Basisverzeichnis während des Setups aus. Bei Ausführungen ohne Root-Rechte wird TMPDIR nur akzeptiert, wenn diese Basis sicher nutzbar ist; ansonsten erfolgt ein Fallback auf /var/tmp und dann /tmp. Das gespeicherte Tar bleibt nur für den Besitzer zugänglich und wird per Stream in das podman load des Ziel-Users geladen, sodass private temporäre Verzeichnisse des Aufrufers das Setup nicht blockieren.

Nützliche Befehle

• Logs: Mit Quadlet: sudo journalctl --machine openclaw@ --user -u openclaw.service -f. Mit Script: sudo -u openclaw podman logs -f openclaw
• Stop: Mit Quadlet: sudo systemctl --machine openclaw@ --user stop openclaw.service. Mit Script: sudo -u openclaw podman stop openclaw
• Erneut starten: Mit Quadlet: sudo systemctl --machine openclaw@ --user start openclaw.service. Mit Script: Führe das Launch-Script erneut aus oder nutze podman start openclaw
• Container entfernen: sudo -u openclaw podman rm -f openclaw — Konfiguration und Workspace auf dem Host bleiben erhalten.

Fehlerbehebung

• Permission denied (EACCES) bei Config oder Auth-Profiles: Der Container nutzt standardmäßig --userns=keep-id und läuft mit derselben UID/GID wie der Host-User, der das Script ausführt. Stelle sicher, dass deine Host-Verzeichnisse OPENCLAW_CONFIG_DIR und OPENCLAW_WORKSPACE_DIR diesem User gehören.
• Gateway-Start blockiert (fehlendes gateway.mode=local): Prüfe, ob ~openclaw/.openclaw/openclaw.json existiert und gateway.mode="local" gesetzt ist. setup-podman.sh erstellt diese Datei, falls sie fehlt.
• Rootless Podman schlägt für User openclaw fehl: Prüfe, ob /etc/subuid und /etc/subgid eine Zeile für openclaw enthalten (z. B. openclaw:100000:65536). Füge sie bei Bedarf hinzu und starte neu.
• Container-Name bereits vergeben: Das Launch-Script verwendet podman run --replace, sodass der existierende Container beim Neustart ersetzt wird. Zum manuellen Aufräumen: podman rm -f openclaw.
• Script nicht gefunden beim Ausführen als openclaw: Stelle sicher, dass setup-podman.sh ausgeführt wurde, damit run-openclaw-podman.sh in das Home-Verzeichnis von openclaw kopiert wurde (z. B. /home/openclaw/run-openclaw-podman.sh).
• Quadlet-Service nicht gefunden oder startet nicht: Führe sudo systemctl --machine openclaw@ --user daemon-reload aus, nachdem du die .container-Datei bearbeitet hast. Quadlet erfordert cgroups v2: podman info --format '{{.Host.CgroupsVersion}}' sollte 2 anzeigen.

Optional: Als eigener User ausführen

Um das Gateway als dein normaler User auszuführen (ohne dedizierten openclaw-User): Baue das Image, erstelle ~/.openclaw/.env mit OPENCLAW_GATEWAY_TOKEN und starte den Container mit --userns=keep-id sowie Mounts auf dein ~/.openclaw. Das Launch-Script ist für den Flow mit dem openclaw-User optimiert; für ein Single-User-Setup kannst du stattdessen den podman run-Befehl aus dem Script manuell ausführen und dabei Config und Workspace auf dein Home-Verzeichnis zeigen lassen. Empfehlung für die meisten Nutzer: Verwende setup-podman.sh und lass es als openclaw-User laufen, damit Konfiguration und Prozesse isoliert sind.

Nächste Schritte

• Schau dir die Konfigurations-Referenz an, um dein Gateway anzupassen.
• Erfahre mehr über die Sicherheits-Best-Practices für den Betrieb im LAN.

Du hast Fragen zum Setup? Nutze den AI Setup Assistant.