Podman

Uruchom Gateway OpenClaw w kontenerze Podman bez uprawnień roota, zarządzanym przez bieżącego użytkownika bez uprawnień roota.

Model działania:

• Podman uruchamia kontener Gateway.
• CLI openclaw na hoście pełni funkcję płaszczyzny sterowania.
• Trwały stan jest domyślnie przechowywany na hoście w ~/.openclaw.
• Do codziennego zarządzania używa się openclaw --container <name> ... zamiast sudo -u openclaw, podman exec lub osobnego użytkownika usługi.

Wymagania wstępne

• Podman w trybie bez uprawnień roota
• CLI OpenClaw zainstalowane na hoście
• Opcjonalnie: systemd --user, jeśli chcesz automatycznego uruchamiania zarządzanego przez Quadlet
• Opcjonalnie: sudo tylko wtedy, gdy chcesz użyć loginctl enable-linger "$(whoami)", aby zapewnić uruchamianie podczas rozruchu na hoście bez monitora

Szybki start

./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   # obejmuje dodatkowe skanowanie usługopenclaw doctoropenclaw channels login

Ręczny program uruchamiający odczytuje z ~/.openclaw/.env tylko niewielką listę dozwolonych kluczy związanych z Podman i przekazuje do kontenera jawnie określone zmienne środowiskowe środowiska uruchomieniowego; nie przekazuje całego pliku środowiskowego do Podman.

Podman i Tailscale

Aby uzyskać dostęp przez HTTPS lub zdalną przeglądarkę, postępuj zgodnie z główną dokumentacją Tailscale.

Uwagi dotyczące Podman:

• Zachowaj adres publikowania Podman jako 127.0.0.1.
• Preferuj zarządzane przez hosta tailscale serve zamiast openclaw gateway --tailscale serve.
• W systemie macOS, jeśli lokalny kontekst uwierzytelniania urządzenia w przeglądarce jest zawodny, użyj dostępu przez Tailscale zamiast doraźnych obejść z lokalnymi tunelami.

Zobacz Tailscale i interfejs sterowania.

Systemd (Quadlet, opcjonalnie)

Jeśli uruchomiono ./scripts/podman/setup.sh --quadlet, skrypt konfiguracyjny instaluje plik Quadlet w ~/.config/containers/systemd/openclaw.container.

Po edycji pliku Quadlet:

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

Aby zapewnić uruchamianie podczas rozruchu na hostach obsługiwanych przez SSH lub bez monitora, włącz utrzymywanie sesji bieżącego użytkownika:

sudo loginctl enable-linger "$(whoami)"

Wygenerowana usługa Quadlet zachowuje stałą, wzmocnioną konfigurację domyślną: porty publikowane na 127.0.0.1 (18789 dla Gateway, 18790 dla mostu), --bind lan wewnątrz kontenera, przestrzeń nazw użytkownika keep-id, OPENCLAW_NO_RESPAWN=1, Restart=on-failure oraz TimeoutStartSec=300. Odczytuje ~/.openclaw/.env jako plik EnvironmentFile środowiska uruchomieniowego dla wartości takich jak OPENCLAW_GATEWAY_TOKEN, ale nie używa listy dozwolonych nadpisań specyficznych dla Podman z ręcznego programu uruchamiającego. Aby użyć niestandardowych publikowanych portów, adresu publikowania lub innych flag uruchamiania kontenera, skorzystaj z ręcznego programu uruchamiającego albo bezpośrednio edytuj ~/.config/containers/systemd/openclaw.container, a następnie przeładuj i ponownie uruchom usługę.

Konfiguracja, środowisko i pamięć masowa

• Katalog konfiguracji: ~/.openclaw
• Katalog przestrzeni roboczej: ~/.openclaw/workspace
• Plik tokenu: ~/.openclaw/.env
• Skrypt uruchamiający: ./scripts/run-openclaw-podman.sh

Skrypt uruchamiający i Quadlet montują stan hosta w kontenerze: OPENCLAW_CONFIG_DIR -> /home/node/.openclaw, OPENCLAW_WORKSPACE_DIR -> /home/node/.openclaw/workspace. Domyślnie są to katalogi hosta, a nie anonimowy stan kontenera, dlatego openclaw.json, pliki auth-profiles.json poszczególnych agentów, stan kanałów i dostawców, sesje oraz przestrzeń robocza pozostają zachowane po zastąpieniu kontenera. Konfiguracja początkowa dodaje również wartości 127.0.0.1 i localhost do gateway.controlUi.allowedOrigins dla publikowanego portu Gateway, dzięki czemu lokalny pulpit działa z powiązaniem kontenera innym niż local loopback.

Przydatne zmienne środowiskowe ręcznego programu uruchamiającego (zapisz je w ~/.openclaw/.env; program uruchamiający odczytuje ten plik przed ostatecznym ustaleniem domyślnych ustawień kontenera i obrazu):

Jeśli używasz niestandardowego OPENCLAW_CONFIG_DIR lub OPENCLAW_WORKSPACE_DIR, ustaw te same zmienne zarówno dla poleceń ./scripts/podman/setup.sh, jak i późniejszych poleceń ./scripts/run-openclaw-podman.sh launch — program uruchamiający z repozytorium nie zachowuje niestandardowych nadpisań ścieżek między sesjami powłoki.

Uaktualnianie obrazów

Po ponownym zbudowaniu lub pobraniu nowego obrazu uruchom ponownie kontener albo usługę Quadlet. Podczas pierwszego uruchomienia nowej wersji OpenClaw Gateway wykonuje bezpieczne naprawy stanu i pluginów, zanim zgłosi gotowość.

Jeśli Gateway zakończy działanie zamiast osiągnąć stan gotowości, uruchom ten sam obraz jednorazowo z poleceniem openclaw doctor --fix dla tego samego zamontowanego stanu i konfiguracji, a następnie uruchom Gateway ponownie w zwykły sposób:

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

Na hostach z SELinux dodaj ,Z do obu montowań, jeśli Podman blokuje dostęp do zamontowanego stanu.

Przydatne polecenia

• Dzienniki kontenera: podman logs -f openclaw
• Zatrzymanie kontenera: podman stop openclaw
• Usunięcie kontenera: podman rm -f openclaw
• Otwarcie adresu URL pulpitu za pomocą CLI hosta: openclaw dashboard --no-open
• Kondycja i stan za pomocą CLI hosta: openclaw gateway status --deep (sonda RPC i dodatkowe skanowanie usług)

Rozwiązywanie problemów

• Odmowa dostępu (EACCES) do konfiguracji lub przestrzeni roboczej: Kontener domyślnie działa z --userns=keep-id i --user <identyfikator uid użytkownika>:<identyfikator gid użytkownika>. Upewnij się, że ścieżki konfiguracji i przestrzeni roboczej na hoście należą do bieżącego użytkownika.
• Uruchomienie Gateway zablokowane (brak gateway.mode=local): Upewnij się, że plik ~/.openclaw/openclaw.json istnieje i ustawia gateway.mode="local". Skrypt scripts/podman/setup.sh tworzy go, jeśli nie istnieje.
• Kontener uruchamia się ponownie po aktualizacji obrazu: Uruchom jednorazowe polecenie openclaw doctor --fix opisane w sekcji Uaktualnianie obrazów, a następnie ponownie uruchom Gateway.
• Polecenia CLI kontenera trafiają do niewłaściwego celu: Użyj jawnie openclaw --container <name> ... albo wyeksportuj OPENCLAW_CONTAINER=<name> w powłoce.
• Polecenie openclaw update kończy się niepowodzeniem z --container: Jest to oczekiwane zachowanie. Ponownie zbuduj lub pobierz obraz, a następnie ponownie uruchom kontener albo usługę Quadlet.
• Usługa Quadlet nie uruchamia się: Uruchom systemctl --user daemon-reload, a następnie systemctl --user start openclaw.service. W systemach bez monitora może być również potrzebne sudo loginctl enable-linger "$(whoami)".
• SELinux blokuje montowania: Pozostaw domyślne działanie montowania bez zmian; program uruchamiający automatycznie dodaje :Z w systemie Linux, gdy SELinux działa w trybie wymuszającym lub zezwalającym.

Powiązane materiały

• Docker
• Proces Gateway działający w tle
• Rozwiązywanie problemów z Gateway