Preflight · Arzt · Fehlermatrix · Reproduzierbare Bereitstellung
Bauherren verkabeln ihren ersten Kanalbleibt normalerweise bei „Gateway startet nicht“ stehen – keine schwachen Modelle. Knotenversionen, Verzeichnisberechtigungen,.envvs. YAML-Drift, ausgelastete Ports, Proxys und DNS können jeweils zu roten Protokollen führen. Dieser Leitfaden gibt eineCheckliste vor dem Flug, AMinimal vs. MehrkanalVergleich,sechs Diagnoseschritte(einschließlichopenclaw doctor), einFehlersymptommatrix, und aSelbstcheck zur Cloud-Migration. Informationen zu PM2- und Always-On-Baselines finden Sie imPlaybook zur persistenten Cloud-Bereitstellung; für Preiskontext, öffnenMietpreise.
Installationsskripte sehen kurz aus; Der kostspielige Teil besteht darin, Laufzeitannahmen zu schreiben: welcher Benutzer Gateway startet, wo Konfigurationen aufgelöst werden, Standardprotokollpfade, welche Ports frei sein müssen und wer Proxy/DNS besitzt. Bei vielen „Gateway startet nicht“-Vorfällen handelt es sich um Node-plus-MacOS-Berechtigungsinteraktionen und nicht um OpenClaw-Logik. Die folgenden fünf Lücken tauchen ständig in Community-Threads auf – erfassen Sie sie in einem Runbook, um eine dreimalige Neuinstallation zu vermeiden, bevor Sie eine PATH-Abweichung bemerken.
Entscheiden Sie, ob Sie als nächstes Slack oder Telegram planenToken-RotationUndVerzeichnisse mit den geringsten Privilegienfrüh; Der Erfolg des ersten Kanals mit veralteten Umgebungsvariablen macht die zweite Rotation schmerzhaft.
Drift des Knoten- und Paketmanagers:OpenClaw erwartet ein modernes Node LTS. Das Mischen von NVM, FNM und Systemknoten führt häufig zu korrekten Ergebnissennode -vin einem Terminal, sondern in einer alten Binärdatei unter Ihrem Prozessleiter. Pinnen Sie einen goldenen Aufruf und überprüfen Sie die echte Binärdatei in der Doctor-Ausgabe.
Arbeitsverzeichnis und Berechtigungsgrenzen:Das Klonen in Desktop- oder iCloud-gestützte Ordner führt zu Sperren oder Überraschungen bei der Berechtigung. Behalten Sie Produktionsbäume unter einem dedizierten Unterbaum im Home-Office des Dienstbenutzers und dokumentieren Sie beschreibbare AgentSkill-Pfade.
Ports und Firewall-Standardeinstellungen:Dashboard- und Gateway-Listener, die mit anderen Daemons kollidieren, werden sofort beendet; Unternehmens-Proxys oder Host-Firewalls blockieren möglicherweise ausgehende LLM-Anrufe. Fügen Sie dem Preflight einen Port-Scan und einen einzeiligen ausgehenden Curl-Smoke-Test hinzu.
Mehrere Konfigurationsquellen: .env, Shell-Profile, launchd/pm2-Env-Blöcke und YAML-Overlays erzeugen zusammen „Ich habe die falsche Datei bearbeitet“-Fehler. Wählen Sie eine einzige Quelle der Wahrheit und Dokumentenpriorität.
Lücken in der Protokollierung und Beobachtbarkeit:Ohne Stdout-Ziele und Rotation füllt der erste lange Lauf die Festplatten oder scrollt den eigentlichen Fehler weg. Korrigieren Sie Pfade und Aufbewahrung bei der Installation – eine Größenordnung günstiger als die Nachrüstung von Monitoren.
Überprüfen Sie die Liste und wählen Sie dann im nächsten Abschnitt einen Installationspfad aus: Nur minimales Gateway oder Mehrkanal-Produktionstopologie.
Das Einschalten von Slack, Mail und Webhooks am ersten Tag lässt die Fehlermatrix explodieren. Sicherer:Starten Sie Gateway auf dem kleinsten Profil mit fehlerfreien Protokollen, und fügen Sie dann einen Kanaladapter pro Änderungsfenster hinzu, damit Rollbacks offensichtlich bleiben. Die Tabelle gleicht die Erwartungen an Ihre erste Bewertung ab.
| Dimension | Minimal (Gateway + Einzelkanal oder CLI) | Mehrkanal-Inkremental |
|---|---|---|
| Ziel | Prozessvalidierung, Konfigurationsanalyse, LLM-Ausgang, Grundkenntnisse | Validieren Sie Routing, Token-Rotation und gleichzeitige Sitzungsisolation |
| Konfigurationsoberfläche | Wenige Umgebungsvariablen, flaches YAML | Viele Webhooks/Tokens; Die Fehlerfläche wächst schnell |
| Triage-Anordnung | Zuerst Gateway-Protokolle und Doctor, dann Modell-API | Trennen Sie Kanalfehler von Agentenfehlern |
| Rollback-Kosten | Niedrig – kommentieren Sie einen Adapter und Diff | Hoch – Schnappschüsse pro Kanal aufbewahren |
| Am besten für | Erstbauer und kleine Teams | Teams mit Runbooks auf dem Weg zur Produktion |
Stabilisieren Sie ein inaktives Gateway vor Adaptern. Durch Umkehren der Reihenfolge werden drei Fehlerklassen in einem Protokollstrom gestapelt.
Diese Schritte isolierenFehler auf Prozessebene(Beim Booten beenden, schlechte Konfiguration, belegte Ports). Wenn der Prozess fehlerfrei ist, aber keine Nachrichten eintreffen, debuggen Sie die Adapter erst, nachdem das Gateway grün angezeigt wird. Community-CLIs werden häufig ausgeliefertopenclaw doctor(oder eine Fixvariante) – ersetzen Sie den genauen Unterbefehl aus Ihren Versionshinweisen.
Frieren Sie den Repro-Befehl ein:Notieren Sie im Ticket das npm-Skript vs. die globale CLI vs. pm2 plus cwd.
Führen Sie einen Selbsttest der Umgebung durch:Ausführenopenclaw doctor, archivieren Sie die vollständige Ausgabe und kreisen Sie Knotenpfade, Berechtigungsverweigerungen, fehlende Deps und Schemafehler ein.
Konfigurationen in Ebenen validieren:Analysieren Sie YAML/JSON und stellen Sie dann sicher, dass Umgebungsvariablen nicht durch Shell-Profile überschrieben werden.
Hörer prüfen:Stellen Sie sicher, dass Dashboard- und Gateway-Ports frei sind. Beachten Sie VPN-Macken beim Loopback.
Erfassen Sie die ersten 200 Protokollzeilen:Gehen Sie vom ersten FEHLER an nach oben – Grundursachen erscheinen oft früher als Warnungen.
Minimaler Rollback-Test:Deaktivieren Sie optionale Adapter und Drittanbieter-Skills, behalten Sie ein offizielles Beispiel und halbieren Sie dann die Wiederherstellungen.
cd /path/to/openclaw node -v npm -v openclaw doctor openclaw doctor --fix npm run start 2>&1 | tee /tmp/openclaw-boot.log lsof -nP -iTCP -sTCP:LISTEN | grep -E '3000|8787'
Tipp: doctor --fixverändert die lokale Konfiguration – Snapshot-Dateien oder durchläuft die Änderungskontrolle, bevor sie auf Produktionsknoten verwendet wird.
Verwenden Sie dies als Spickzettel für den Bereitschaftsdienst: Finden Sie das Symptom, führen Sie die erste Aktion aus und erweitern Sie erst dann die Suche. Wenn drei Durchgänge fehlschlagen, kehren Sie zu Abschnitt drei zurück, um vollständige Stämme zu erhalten und zu halbieren.
| Symptom | Wahrscheinliche Ursache | Erste Aktion |
|---|---|---|
| Sofortiger Ausgang, kein Stapel | Keine Knotenübereinstimmung oder falsche Binärdatei auf PATH | NVM/PM2-Knoten ausrichten; Wiederholen Sie den Arzt |
| YAML/JSON-Analysefehler | Einrückung, Kodierung, Zusammenführung von Müll | Syntax validieren; Minimale Konfiguration wiederherstellen |
| Port bereits verwendet | Zombie-Prozess oder widersprüchlicher Daemon | lsof, geben Sie den Port frei oder ändern Sie ihn |
| LLM-Timeouts/TLS-Fehler | Proxy, DNS, Unternehmens-MITM | Curl-Austrittstest; Vertrauenskette / HTTPS_PROXY |
| Die Kanalauthentifizierung schlägt während der Prozesslaufzeit fehl | Abgelaufenes Token oder Webhook-URL-Drift | Geheimnisse rotieren; Rückruf-Host überprüfen |
| AgentSkill EACCES | Dateisystemberechtigungen oder Sandbox | Eigentumsverhältnisse festlegen; Audit-Skill-Skripte |
Warnung:Vermeiden Sie Wiederholungensudo npm install -gOhne das Prozessmodell zu verstehen, können Globals „installiert“ melden, während die Laufzeit immer noch den falschen Modulbaum auflöst.
Installierte Brandbekämpfung und Langzeitzuverlässigkeit sind benachbarte Disziplinen: Die erste optimiert reproduzierbare Kaltstarts, die zweite optimiert die Wiederherstellung nach einem Absturz und die Überprüfbarkeit. Diese messbaren Eingabeaufforderungen helfen bei Überprüfungen, ohne die Originaldokumente zu ersetzen.
Wenn Laptops sich nicht treffen könnenunbeaufsichtigtUndNull-DialogAnforderungen, Cloud-Selbstprüfungen fügen eine Guardian-Neustartrichtlinie, Dashboard-Offenlegung und Protokollrotation hinzu – kopieren Sie die Produktionsanker aus demPersistent Cloud Playbook.
Sicherheitshinweis:Niemals vollständig einfügen.envDateien in den Chat; Verwenden Sie ablaufende Geheimkanäle und den Widerruf von Dokumenten.
Laptops, die mit Ruhezustand, Updates und gemeinsamen Sitzungen jonglieren, erzeugen Zufälligkeiten, die durch funktionierende Installationen nicht behoben werden können. Dedizierte, regional platzierte Cloud-Mac-Knoten machen das „tägliche Hochfahren“ einfacher als das „Hochfahren bei geöffnetem Deckel“. Für Teams, die OpenClaw in Bereitstellungsstandards integrieren,Die Cloud-Miete von VpsMesh Mac Mini ist in der Regel die bessere Lösung: Natives Apple Silicon, 24/7-Metall, flexible Mietfenster – verbringen Sie Zyklen mit Gateway-Logik statt mit Maschinenstatus.
NormalerweiseCWD-Driftoderenv überschreibt: pm2/systemd lädt einen anderen Pfad als Ihre interaktive Shell. Erfassen Sie argv und cwd aus Abschnitt drei, bevor Sie dem Arzt wieder vertrauen.
Heartbeat- und unbeaufsichtigte SLAs überstehen Laptops selten. Lesen Sie dieLeitfaden zur dauerhaften Bereitstellung, dann verwenden Sie dieBestellseiteUndPreisseitefür Regionen.
Beginnen Sie amHilfecenterfür SSH/VNC-Themen; Bewahren Sie die Doctor-Ausgabe und die Boot-Protokolle zur Eskalation auf.