2026 OpenClaw auf headless Linux-VPS: Von install.sh zur ersten Kanalantwort mit gateway probe und channels probe

Ohne Desktop auf Ubuntu oder Debian verwechseln Teams oft Installer-Exitcode mit Produktionsreife. Dieser Leitfaden fixiert das Ziel auf die erste zuverlässige Chat-Antwort und zwingt die offizielle Troubleshooting-Reihenfolge ein: CLI, gateway probe, channels probe, erst danach Modelle. Ufw und Cloud-Security-Groups sind eine Schnittmenge; IPv6 und Webhooks brauchen explizite TLS-Endpunkte.

Ohne Desktop auf Ubuntu oder Debian verwechseln Teams leicht den erfolgreichen Exitcode des Installers mit einer produktionsreifen Gateway-Schicht. Dieser Leitfaden verankert das Ziel auf der ersten zuverlässigen Chat-Antwort und zwingt die offizielle Troubleshooting-Reihenfolge: Node und CLI-Pfad, openclaw status, gateway probe, channels-Sonden, erst danach Modellstrings.

Dokumentieren Sie Listener-Bindings, ufw-Regeln und Cloud-Security-Groups in einem Ticket, weil die effektive Policy die Schnittmenge ist, nicht der jeweils optimistischere Screenshot.

1. Falsche Erfolge, die wie Grün aussehen

Schmerz eins: Der Installer legt Binaries ab, während Node unter der unterstützten Major-Version bleibt oder PATH noch auf ein älteres Präfix zeigt. Prüfen Sie node -v und which openclaw direkt nach dem Lauf, dann openclaw status, bevor Sie JSON zusammenführen, damit klar ist, welcher Unix-User die Konfiguration besitzt.

Schmerz zwei: Inbound-Ports in der Cloud öffnen, aber ausgehende DNS- und TLS-Pfade ignorieren. In VPCs mit restriktivem Egress wirken Timeouts oft wie Modell-Throttling; nutzen Sie curl -v zu den Chat-Endpunkten, bevor Sie Quoten verdächtigen.

Schmerz drei: LISTEN mit öffentlicher Erreichbarkeit verwechseln. ss kann Loopback zeigen, während die Security Group weiter blockt oder ufw widerspricht. Halten Sie beide Ebenen im Änderungsprotokoll fest.

1. Parallele Installer und Editoren gegen dieselbe JSON-Datei einfrieren.
2. Konfigurationsbäume vor dem ersten Merge archivieren.
3. Die Leiter-Reihenfolge im Ticketkopf ausdrucken.

Wenn cloud-init Netzwerkregeln bei jedem Boot neu schreibt, kann ein manuell gesetztes iptables-Rule-Set zwischen zwei Sonden verschwinden; versionieren Sie cloud-init-Module im gleichen Repo wie die Gateway-Config.

Profile.d-Skripte, die PATH für interaktive Shells erweitern, täuschen häufig grüne manuelle Tests vor, während systemd-Units weiter das schmale Standard-PATH sehen.

2. Matrix: welches Begleit-Runbook zuerst?

Die Tabelle routet Sie zu den passenden SFTPMAC-Artikeln, statt Docker-Befehle auf Bare-Metal zu mischen.

3. Achtstufige Leiter von install.sh zur ersten Antwort

Schmerz vier: gateway probe überspringen und sofort gateway install --force fahren. Das multipliziert Prozesse und Ports, wenn eigentlich eine Firewallregel oder ein Tokenpfad falsch war. Reservieren Sie Force-Installs für dokumentierte Split-Brain-Fälle nach Snapshots.

Schmerz fünf: Modelle beschuldigen, obwohl Kanäle nie grün sonden. Erst gateway status stabilisieren, dann channels status --probe, Credentials prüfen, Provider-Quoten prüfen. WebSocket-Close-Codes und HTTP-Zeilen ins Ticket.

Schmerz sechs: Bare-Metal- und Compose-Ratschläge mischen. Compose nutzt Bridge-Netze und injizierte Env-Dateien; Bare VPS nutzt sshd, ufw und ggf. systemd-user linger.

node -v
which openclaw
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw status
openclaw gateway probe
openclaw gateway status
openclaw doctor
openclaw channels status --probe

1. Gleichzeitige menschliche und CI-Änderungen einfrieren.
2. Umgebungsdumps für Login-, Automations- und späteren Service-User exportieren.
3. Node 22+ verifizieren, ggf. aus freigegebenen Paketquellen nachziehen.
4. Installer mit rotierenden Logs ausführen.
5. Vor JSON-Chirurgie status und gateway probe.
6. gateway status und doctor, danach status wiederholen.
7. ufw- und Cloud-Regeln zeitfensterartig mit Rollback-Zeile anpassen.
8. Kanäle sonden, synthetische Nachricht pro Provider mit redigiertem Screenshot.

Ergänzen Sie strukturierte JSON-Logs um Felder probe_step, exit_code und duration_ms, damit CI-Auswertungen Trends über mehrere Nächte erkennen, ohne dass Menschen Screenshots manuell vergleichen.

Speichern Sie vollständige x-ratelimit-*-Header der Chat-APIs neben Gateway-Logs, damit klar bleibt, ob 429 vom Anbieter oder von einem zwischengeschalteten Proxy stammt.

Webhook-Handler sollten Idempotenzschlüssel ausliefern; dokumentieren Sie im Ticket, welcher Schlüssel bei doppelter Zustellung verworfen wurde, sonst fehlinterpretieren Sie erneute Events als neue Nutzeraktionen.

Wenn Sie Artefakte in Objektspeicher legen, messen Sie Warteschlangentiefe und Bandbreite parallel zur Kanalsonde, weil TLS-Erfolg zum Chat-Anbieter nichts über presigned PUT/PATCH zu Ihrem Bucket aussagt.

HSTS-Preload-Listen auf nginx können Browser zwingen, https zu wählen, während interne Healthchecks noch http erwarten; trennen Sie öffentliche und interne Hostnamen konsequent im Ticket.

Prüfen Sie, ob ForceCommand oder Match User in sshd_config die Umgebung für Automation kürzt, die später denselben Host per Ansible erreicht, sonst divergieren Sonden und Cronjobs.

4. Checkliste für Rufbereitschaft

Tickets mit der Ebene labeln, damit niemand Bare-Metal-Fragmente in einen Compose-Stack kopiert. Die Matrix hilft, welchen Artikel man zuerst liest, nicht welchen Anbieter man wählt.

Bare-VPS-Betrieb besitzt Kernel-Rhythmus, OpenSSH-Härtung, Spiegel und Node-Upgrades. Docker-Betrieb besitzt Digests und Token-Ausrichtung.

Ergänzen Sie die Tabelle im Ticket mit einem Kurzkommentar, welche Version des OpenClaw-Pakets gerade installiert war, damit Postmortems nicht raten, ob ein Regression-Bug oder ein Konfig-Merge die Ursache war.

Wenn Sie mehrere Regionen betreiben, notieren Sie die AZ und das Transit-Gateway, über das Management-SSH läuft, getrennt vom Pfad der Webhooks, weil asymmetrisches Routing sonst grüne Sonden und rote Nutzererfahrung erzeugt.

Für TLS-Zertifikate von Let’s Encrypt halten Sie den genauen ACME-Client und die Challenge-Methode fest; HTTP-01 auf Port 80 kollidiert leicht mit temporären Gateway-Tests auf derselben Maschine.

Speichern Sie die Ausgabe von systemd-analyze blame nach dem ersten erfolgreichen Boot, damit spätere Verzögerungen beim Hochfahren nicht fälschlich dem Chat-Transport angelastet werden.

Wenn Sie eBPF-Programme zur Flow-Überwachung nutzen, dokumentieren Sie Kernel-Version und BCC-Commit, weil sonst Kolleginnen nicht reproduzieren können, welche Hook-Punkte aktiv waren.

Halten Sie eine Zeile bereit, die erklärt, ob IPv6 auf dem Host über SLAAC, statisch oder gar deaktiviert ist, damit Dual-Stack-Debatten nicht endlos im Kreis laufen.

5. Firewalls, Dual Stack, Webhooks

Management-Zugang, Gateway-RPC und Kanal-Webhooks sind drei Pfade mit jeweils Quelle, Ziel und Protokoll. Temporär breite Regeln zeitlich begrenzen und nach erster erfolgreicher Antwort wieder zuschneiden.

ufw und Cloud-SG schneiden sich: ein Allow und ein Deny ergeben Deny. Beide Screenshots in dasselbe Ticket.

Dual Stack: AAAA und Listener-Familie gemeinsam prüfen, damit Happy-Eyeballs-Flaps nicht als App-Bug enden.

TLS-Terminierung auf nginx versus Gateway dokumentieren, weil Healthchecks und Sonden unterschiedlich ausfallen.

Synchronisieren Sie chrony oder systemd-timesyncd bevor Sie TLS-Fehler interpretieren: mehrminütige Drift macht frische Zertifikate plötzlich „ungültig“ und lenkt Teams auf falsche Modellkonfigurationen.

Wenn journald riesige Anhänge speichert, rotieren Sie früh, sonst füllen sich Inodes, obwohl df -h noch Luft bei Blöcken zeigt; volle Inodes brechen Webhook-Schreibpfade ohne klare Meldung im Gateway-Log.

Überwachen Sie nf_conntrack_count gegen das Maximum, weil bursty WebSocket-Verbindungen den gleichen Symptomcode liefern wie ein falsch gesetztes Sicherheitsgruppenregelwerk.

Testen Sie PMTU bewusst, wenn zwischen Regionen Tunnel oder ältere Router hängen: schwarze Löcher wirken wie hängende Handshakes, obwohl gateway probe von einem kleinen Ping-Paket aus noch grün war.

DNS-Suchlisten aus /etc/resolv.conf können interne Namen nach außen leaken; dokumentieren Sie den final aufgelösten FQDN im Ticket, damit spätere Audits nicht raten, welcher Resolver tatsächlich antwortete.

6. Fünf Wiederholungs-Drills

Drill eins: Home-Baum und Fragmente vor JSON-Edits packen, Checksumme im Ticket.

Drill zwei: gateway probe als derselbe User wie der Dienst, um PATH-Unterschiede zwischen interaktiv und systemd zu entlarven.

Drill drei: Ausgehendes TLS mit curl -v zu Chat-Endpunkten, Handshake-Zeiten notieren.

Drill vier: ufw-Änderungen paarweise mit UTC-Zeitstempel und Rollback-Einzeiler.

Drill fünf: Nach jedem Minor-Bump synthetische Kanalnachricht erneut senden, Screenshots redigieren, Rohlogs separat sichern.

Gemeinsam verkürzen die Drills die Zeit bis zur Schuldbestimmung zwischen Modell-Anbieter und eigenem Perimeter.

Prüfen Sie ulimit -n für den Service-User, bevor Sie parallele Kanaltests fahren; erniedrigte Dateideskriptoren-Grenzen aus PAM-Profilen erzeugen sporadische „too many open files“, die wie Netzwerkinstabilität aussehen.

Wenn cgroup v2 Memory High gesetzt ist, dokumentieren Sie OOM-Ereignisse neben Gateway-Restarts, damit niemand Webhook-Latenzen dem Chat-Provider anlast, obwohl der Kernel den Prozess gedrosselt hat.

Planen Sie unattended-upgrades in Wartungsfenstern, die nicht mit Ihrer ersten Akzeptanznacht kollidieren, und halten Sie Kernel-Neustarts explizit im Ticket, weil offene Control-Ports nach Reboot anders binden können.

Stellen Sie sicher, dass systemd-Units LANG und LC_ALL auf UTF-8 setzen, sonst schlagen JSON-Merges in Logs mit Mojibake fehl und irritieren Forensik.

Kurzlebige Tokens gehören nicht dauerhaft auf world-readable tmpfs; wenn Sie sie dennoch stagingweise ablegen, löschen Sie Pfade im selben Ticket mit Zeitstempel der Löschung.

Vermeiden Sie gemischte seccomp-Profile zwischen nginx und Node, ohne die jeweiligen Syscall-Listen zu vergleichen, weil sonst doctor grün bleibt, während einzelne Healthchecks still fehlschlagen.

7. Grenzen zu Split-Brain, Docker und HOME-Drift

Offizielle Leiter im Gateway-Probe-Leitfaden lesen, bevor Sie Modelle ändern. systemd HOME-Drift gehört nach Upgrades, nicht zur Erstakzeptanz.

Eine kleine Textdatei auf dem Host mit exakten Sondenbefehlen, Exit-Codes und Initialen spart bei Rebuilds einen Tag Netzwerk-Archäologie.

Automation mit Ansible oder Terraform soll diese Datei idempotent nachziehen, statt jedes Quartal neu zu raten.

Belege gehören zur Grenzziehung: erste Bildschirmseite jeder Sonde, nicht nur die letzte ok-Zeile; absoluter Node-Pfad für systemd versus interaktive Shell; Flow-Log-Auszüge mit SYN/RST falls vorhanden.

ProxyJump kann lokale Checks grün zeigen, während die Produktions-SG falsch bleibt; IPv4-only-Anbieter explizit nennen.

Disaster-Recovery vom kalten Snapshot üben, quartalsweise Egress nach Zertifikatsrotation testen, grünes gateway mit synthetischem Objektspeicher-Fetch koppeln, fail2ban-Fenster mit CI-Runner-IP-Ranges korrelieren.

In Ansible unterscheidet become_user strikt von der Login-Shell, die Sie per SSH testen; variieren Sie deshalb ansible_user und become_user nicht still, ohne die Leiter erneut zu fahren.

Terraform-ignore_changes auf Firewall-Ressourcen birgt das Risiko, dass echte Drifts nie mehr ins State-File wandern und Ihre Sonden grün bleiben, während die Konsole rot ist; kommentieren Sie solche Ausnahmen im Modul mit Ticket-ID.

Für Postmortems sollte ein dedizierter Kanal nur die chronologische Befehlsliste ohne Side-Threads führen, damit Management die Reihenfolge der Sonden nachvollzieht, ohne Slack-Reaktionen zu durchsuchen.

Wenn Sie Node aus Vendor-Paketen pin-nen, notieren Sie die Quelle (Nodesource, Distro, asdf), weil gemischte Upgrades sonst zwei Binaries im PATH hinterlassen, die jeweils andere OpenSSL-Backends laden.

Zusätzliche Kernel-Module für Netzwerk-Tuning (BBR, fq) gehören in denselben Änderungsdatensatz wie Gateway-Ports, damit Rollbacks nicht halb Kernel, halb Userspace zurückbleiben.

8. FAQ

F Installer ok, probe rot? A Listener, ufw, DNS/Egress, Cloud-Regeln vor Modellstrings.

F Sofort systemd-Dienst? A Gateway im Vordergrund zur Akzeptanz, dann daemonisieren mit Snapshots.

F API-Schlüssel rotiert? A Leiter einmal komplett wiederholen; gestern grün garantiert nicht morgen.

F Alles grün, aber Nutzer sehen dennoch Verzögerungen? A Messen Sie CPU-Steal der Hypervisor-Schicht, prüfen Sie, ob der VPS auf burst-fähigen Credits läuft, und ziehen Sie Latenzhistogramme der Chat-API getrennt von Gateway-Roundtrips heran, damit weder Kernel noch Provider unsichtbar bleiben.

9. Fazit und Remote-Mac-Option

Geordnete Akzeptanz senkt Wochenendarbeit auf headless Linux und macht die fehlgeschlagene Schicht sichtbar. Wenn Sie denselben Host später an ein internes Finanz- oder Healthcare-Rechenzentrum verschieben, exportieren Sie die Ticketkette als PDF-Anhang, damit Auditorinnen die Reihenfolge der Sonden ohne Shell-Zugang prüfen können.

Self-hosted VPS bleibt mächtig, kostet aber laufend Kernel-, Distro- und Policy-Aufmerksamkeit.

Kurz vor Produktionsfreigabe lohnt ein abschließender Diff zwischen openclaw doctor --json und der menschlich lesbaren Ausgabe, damit CI und Mensch dieselben Blocker sehen; speichern Sie beide Streams nebeneinander im Ticket.

Webhook-Secrets wie Datenbankpasswörter rotieren, mit Dual-Write-Fenster und Rollback-Notiz. Tickets farbig nach dev/stage/prod markieren, damit Firewall-Diffs nicht im falschen VPC landen.

Wenn Always-on-Gateways und Apple-nahe Pfade wichtiger sind als jedes Kernel-Knob, SFTPMAC Remote Mac vergleichen und die geschätzten Stunden für wiederkehrende Firewall-Reviews explizit einpreisen.