Änderungsnotizen · Entscheidungsmatrix · Acht-Schritte-Runbook · Ticketzeilen · VNC-Konsole
OpenClaw v2026.4.25Verschiebt den Plugin-Start auf aCold-Persistent-Registrierung: Beim Start liest der Agent kuratierte Metadaten, anstatt den gesamten Erweiterungsbaum zu durchsuchen, was das Installations- und Aktualisierungsverhalten vorhersehbarer macht, aber neue Fehlermodi einführt. Betreiber sehenleer aussehende Plugin-Fenster, lange erste Kaltstarts nach dem Upgrade und Abweichungen zwischen den globalen Build-IDs von npm und der Gateway-Benutzeroberfläche. Auch in den Versionshinweisen wird darauf hingewiesenHardening installieren und aktualisierenPlusGateway-Überprüfung gemischter Versionen– gemeint ist dasCLI, den Gateway-Prozess und den Paketpfad in Ihrer Launchd-Plistmuss die gleiche Versionsgeschichte erzählen. Dieser Artikel ist der orthogonale Begleiter zumv2026.4.25 Kanalpaarung und Gateway-SicherheitLeitfaden: Der Schwerpunkt liegt auf der Stabilität der Plugin-Ebene, während Sie QR und Mission Control aus dem kritischen Pfad heraushalten. Lesen Sie es zusammen mitabgestufte Freigabevorgänge, Dieoffizielle Komplettlösung für Docker Compose, Diev2026.4.5 bricht das Upgrade abRunbook und dashäufige FehlerAnleitung, damit Sie „Der IM-Kanal ist grün“ von „Die Erweiterungsregistrierung ist fehlerfrei“ unterscheiden können.
Die Ausdrücke „kalte Registrierung“, „Metadatenreparatur“ und „Überprüfung gemischter Versionen“ beschreiben messbares Verhalten.Erstens handelt es sich bei der Inbetriebnahme um eine kalte Lektüre.Wenn der Index auf der Festplatte zur Hälfte migriert ist, erhalten Sie keine saubere Fehlerzeile mit der Meldung „Registrierung beschädigt“. Sie werden einen leeren Plugin-Bildschirm oder eine mehrminütige Verzögerung sehen, während Node den Index neu erstellt, insbesondere auf einem Remote-Mac mit einer kleinen SSD und gemeinsam genutzten E/A.Zweitens stützen sich Installationspfade jetzt auf lokale InstallationsmetadatenDas muss teilweise NPM-Downloads überstehen. Ein Tarball, der mitten im Flug stoppt, kann eine Plugin-Zeile mit einer Versionsbezeichnung, aber keine ausführbare Binärdatei hinterlassen – genau die Art von Fehler, die das verursachtopenclaw plugins repairund zugehörige Neuindexierungsbefehle sollen adressieren.Drittens stellen gemischte Versionen ein Laufzeittopologieproblem dar.Die CLI in Ihrer Shell löst möglicherweise auf/opt/homebrew/...während launchd immer noch PunkteProgramArgumentsbei einem älterendist/index.jsunter einem vorherigen Präfix oder ein Docker-Container mountet ein anderes Konfigurationsstammverzeichnis als der Host, auf dem Sie gerade eine Reparatur ausgeführt haben. Bis diese Pfade zusammenlaufen, liest die Konsole an Port 18789 einen anderen Build als den, von dem Sie glauben, dass Sie ihn installiert haben.
Die folgenden fünf Elemente werden in Tickets angezeigt, wenn Teams die Beweiserhebung überspringen und zu „Alles neu installieren“ übergehen. Sie können sie als Abschnitt „Versteckte Kosten“ in einen Änderungsantrag kopieren.
Kaltstartspitzen:Der erste vollständige Index- oder Reparaturdurchlauf kann die CPU und die Knotenereignisschleife fixieren. Auf einer 32 GB großen Remote-Instanz mit einer verrauschten Nachbarfestplatte scheint die Sitzung hängen zu bleiben, obwohl der Prozess immer noch Shard-Dateien neu schreibt.
Halbinstallierte Plugins:Ein beim Abrufen eines Bundles ausgefallenes Netzwerk kann Manifestzeilen erstellen, die auf fehlende native Module verweisen, was in der Benutzeroberfläche als „Version bekannt, Aktivierungsschalter führt nichts aus“ angezeigt wird, bis die Reparatur den Baum abgleicht.
Mehrere Installationswurzeln:Homebrew/opt/homebrew, Vermächtnis/usr/local, und ein eingecheckternode_modulesDer Baum in einem Entwickler-Checkout kann alle einen OpenClaw-Build hosten. Der launchd-Job ist möglicherweise immer noch an den ältesten Pfad gebunden, was Warnungen zu gemischten Versionen in Protokollen auslöst, während Ihre interaktive Shell bereits auf 4.25 läuft.
Erlaubnis und Sandboxing:Ein Hilfsprogramm, das keine Dateien im Registrierungs-Cache-Verzeichnis erstellen kann, protokolliert häufig ein generisches „Plugin-Laden fehlgeschlagen“ anstelle eines klaren EPERM, sodass Sie immer noch denselben TCC und denselben Eigentümerpass benötigen, den Sie für jeden langlebigen Agenten unter macOS verwenden würden. Kombinieren Sie dies mit demRemote-Mac-TCC-Checklistewenn Ihre Symptome mit der automatisierten Berührung von UI-Oberflächen einhergehen.
Der Zustand des Kanals ist nicht gleichbedeutend mit dem Zustand des Plugins.Ein erfolgreicher IM-QR-Pfad beweist die Zustellung für einen Connector; das tut esnichtBeweisen Sie, dass die Registry und Gateway einverstanden sind. Unterzeichnen Sie diese Annahmelinien für separate Arbeitselemente, damit Sie kein „Produktionsbereit“-Ticket schließen, während Erweiterungen stillschweigend fehlschlagen.
Eine kalte Registrierung belohntwiederholbare Installationsflächen. Docker kann die Node-Engine und das Openclaw-Paket in einer Image-Ebene anheften, aber Bind-Mounts an den Host können gemischte Roots wieder einführen, wenn Sie auf dem Host reparieren und den Container ein veraltetes Volume lesen lassen. Bare-Metalnpm install -glässt sich schnell vorantreiben, erfordert aber Disziplin: Bei jeder Reparatur, jedem Doctor-Run und jeder Plist-Bearbeitung muss das verwendet werdenderselbe macOS-BenutzerDadurch wird schließlich die 18789-Benutzeroberfläche angezeigt, andernfalls weichen die Registrierung auf der Festplatte und der Cache pro Benutzer voneinander ab. Verwenden Sie die Tabelle als Anhang zu einem Änderungsdatensatz. Dies ist auch der schnellste Weg, um nachzuweisen, dass es sich bei einem Vorfall um eine Volumeninkongruenz und nicht um einen Modellausfall handelte.
| Dimension | Bare-Metal-NPM oder PNPM | Docker Compose | Häufige Fehlinterpretation |
|---|---|---|---|
| Versionsausrichtung | Hängt von launchd, PATH und Ihren Shell-Init-Dateien ab | Hängt vom Image-Tag und dem gemounteten Konfigurationsverzeichnis ab | Nur prüfenopenclaw --versionin einer SSH-Sitzung, passt nie zum Live-Gatewayargv |
| Reparaturszenario | Arbeitet an der vorhandenen Host-Registrierung | Der entsprechende Befehl muss im Container auf demselben Volume ausgeführt werden | Reparatur auf dem Host, während der Container noch auf einen eingefrorenen Pfad innerhalb des Bildes zeigt |
| Rollback-Geschwindigkeit | Stellen Sie einen bekannten Tarball wieder her und sperren Sie den Server schnell | Markieren Sie das Bild erneut unddocker compose up | Host und Image ohne Snapshot aktualisieren und dann zwei fehlerhafte Ebenen gleichzeitig debuggen |
| Beobachtbarkeit | macOS-Protokollstream plus lokaler Browser auf 127.0.0.1:18789 | Hinzufügendocker logsund Container-lokales Curl | SSHtailNur: DevTools niemals öffnen, um Bundle-Hashes zu vergleichen |
Regel:Der Prozess, der Gateway startet, definiert die Produktversion. Die CLI ist nur ein weiterer Client.
Die Reihenfolge ist absichtlich streng:Beweise vor der Mutation. Wenn Sie hohen Datenverkehr haben, kündigen Sie im Voraus ein Sperrfenster an und leihen Sie sich die Sprache ausEinfrieren und AusnahmeAbschnitt des Betriebshandbuchs. Erfassen Sie freien Speicherplatz auf der Festplatte. Kalte Registrierungsarbeiten reagieren empfindlich auf alles, was unter etwa zehn bis fünfzehn Prozent frei auf APFS liegt. Nachdem Sie Pakete geändert haben, führen Sie immer einen Thread durchopenclaw doctorzuerst, damit der Support etwas Durchsuchbares erhält, bevor Sie lang laufende Unterbefehle berühren. Wenn in der Versionsinformation ein Reparaturverb erwähnt wird, verwenden Sie das von Ihrer Organisation standardisierte Verb:reindex, repair, oder beides – und behalten Sie den vollständigen stderr bei, da ein teilweiser Erfolg immer noch gemischte Metadaten hinterlässt.
Starten Sie lediglich das Gateway neunachSie sind sicher, dass CLI, Plist und Container-Einstiegspunkt übereinstimmen. Durch den Neustart eines alten Prozesses mit einer neuen Registrierung erzeugen Teams verwirrende Sperrfehler, die wie eine Beschädigung aussehen. Die HTTP-Oberfläche sollte eine konsistente Build-Zeichenfolge bereitstellen: „compare“./versionoder das Banner in Protokollen, der Bereich „Info“ in der Benutzeroberfläche und die erste Zeile vonopenclaw --version. Wenn sich einer der drei Punkte unterscheidet, sind Sie noch nicht fertig.
Sichern:Exportieren Sie das OpenClaw-Konfigurationsstammverzeichnis, das Plugin-Datenverzeichnis und die Launchd-Plist. Aufzeichnenopenclaw --versionund das vollständige Gatewayargvauspsvor der Beule.
Freeze schreibt:während des Fensters, automatische Pauseskill updateJobs und Ad-hoc-Plugin-Installationen von anderen Betreuern, sodass sich zwei Migrationen nicht überschneiden.
Stoßen Sie das Paket an:Verschieben Sie den unterstützten Kanal auf v2026.4.25. Bestätigen Sie für globales NPMwhich openclawund der LaunchdProgramArgumentsauf dasselbe Präfix verweisen.
Führen Sie den Arzt aus:Fügen Sie alle Plugin-, Registrierungs- oder Gateway-Zeilen wörtlich in das Ticket ein, einschließlich Zeitwarnungen.
Plugins reparieren oder neu indizieren:Beobachten Sie die Uhrzeit und schreiben Sie auf die Festplatte. Bei einem Fehler behalten Sie den vollständigen stderr bei, keinen Screenshot der letzten drei Zeilen.
Gateway neu starten:Nur wenn Versionen ausgerichtet sind, sodass der alte Prozess keine veraltete Sperre für das neue Layout aufrechterhält.
Überprüfung gemischter Versionen:Vergleichen Sie CLI, HTTP-Versionsendpunkt und den Info- oder Fußzeilenbereich in der Benutzeroberfläche.
VNC-Akzeptanz:in einer grafischen Sitzung öffnenhttp://127.0.0.1:18789(oder Ihren dokumentierten Tunnel), validieren Sie die Erweiterungsliste, die Modellautorisierungskarten und die Fehlerschublade. Fügen Sie der Änderung einen Screenshot bei.
mixed-version triage in three checks: 1) CLI: openclaw --version 2) Process: ps — note dist/index.js path in argv 3) UI: footer or About, plus response headers in DevTools for the gateway route
Notiz:Dokumentieren Sie für Docker, wo Reparatur und Doctor ausgeführt werden (Host vsdocker compose exec) im Runbook und passen Sie es an das Volume-Layout im anLeitfaden verfassenEine gut gemeinte SSH-Sitzung führt also nicht zu einer Desynchronisierung eines Containers.
Vorsicht:Überspringen Sie nicht die Hauptversionen, schreiben Sie SecretRef nicht neu und konfigurieren Sie das Kanalrouting nicht an einem Wochenende ohne Backups. Wenn dies mit der Sicherheitsanordnung in der kollidiertv2026.4.5 bahnbrechende ÄnderungArtikel, gehen Sie den strengeren Weg.
SSH bleibt das richtige Werkzeug dafürdoctor, repairund strukturierte Protokolle.Kontrollieren Sie die Benutzeroberfläche, die Zustimmung zur Browsererweiterung und ob ein Umschalten tatsächlich bestehen bleibtSie benötigen immer noch die Desktop-Sitzung desselben Benutzers, der Eigentümer des launchd-Jobs ist. Das Raster unten ist für einen einzelnen Bereitschaftsdurchlauf über VNC dimensioniert. Wenn Sie bei einem nativen Modul oder einem kryptischen Ladefehler stecken bleiben, öffnen Sie dasZehn häufige FehlermusterOrdnen Sie im Leitfaden Ihr Schlüsselwort zu und kehren Sie dann zu Schritt fünf dieses Runbooks zurück, um zu sehen, ob ein zweiter Kaltstart den Fehler reproduziert.
| Überprüfen | Was zu tun | Kriterien bestehen |
|---|---|---|
| Versionsdreieck | Vergleichen Sie CLI, Prozess argv und die Info oder Fußzeile in der Benutzeroberfläche mit 18789 | Alle drei zeigen dasselbe Dur und Moll, das Sie versenden wollten |
| Plugin-Liste | Öffnen Sie nach dem Kaltstart einmal die Erweiterungsseite und warten Sie, bis sich die Liste beruhigt hat | Die Anzahl stimmt mit einer Baseline vor der Änderung überein, oder das Delta ist im Änderungsdatensatz dokumentiert |
| Modellberechtigung | Lösen Sie OAuth-Aktualisierungspfade aus, auf die Sie sich verlassen; Achten Sie auf Banner mit Ratenbegrenzung | Keine unbegrenzten 401- oder 429-Schleifen in der Zeitbox |
| Festplatte und E/A | Verwenden Sie den Aktivitätsmonitor, um den Lese-/Schreibvorgang während der Neuindizierung zu überwachen, sofern er noch ausgeführt wird | Spike zerfällt, freier Speicherplatz bleibt über der Sicherheitsmarge |
| Regressionsrauch | Senden Sie eine kleine Sonde auf Ihrem Kanal mit dem geringsten Risiko | Der Zustand des Kanals ist ein separater Posten vom Zustand des Plugins, wie in Abschnitt 01 |
IM-Onboarding, 18789-Sicherheitsmuster und SSH-Portweiterleitung neben derselben Steuerungsebene.
Lesen Sie →Frieren Sie Leitungen ein, wenn Sie sie unterbrechen müssen, und setzen Sie Bäume zurück, wenn die Freigabe schnell erfolgt.
Lesen Sie →Volumenverträge, Port 18789 und Überprüfung der Benutzeroberfläche in einem Container auf einem VNC-Host.
Lesen Sie →Führen Sie „doctor“ aus, reparieren oder indizieren Sie dann neu und stellen Sie sicher, dass Sie sich nicht in einem gemischten Versionszustand befinden. Eine blinde Gateway-Neuinstallation verschiebt nur den nächsten Kaltstart, und Sie verlieren den Diff, der eine veraltete Plist oder ein veraltetes Volume angezeigt hätte.
launchd weist immer noch auf ein älteres hindistEintrag, während Ihre interaktive Shell eine neuere globale Installation oder einen Docker-Hostpfad und einen Containerpfad verwendet, sehen Sie unter Bind Mounts unterschiedliche Bäume.
CLI und Protokolle, ja. Die Bedienoberfläche und einige macOS-Berechtigungen benötigen weiterhin die grafische Sitzung. Verwenden Sie die Tabelle Abschnitt 05 mit VNC im selben Benutzerkonto wie der Gateway-Prozess.
Die kalte Registrierung tauscht „den gesamten Baum bei jedem Start scannen“ gegen „Eigene Installationsmetadaten und Versionszeile“. Die operative Nachbereitung istvorhersehbare I/O-Spitzenwährend der Neuindizierung,Engere Kopplung zwischen launchd- und npm-Präfixen, UndDie Akzeptanz, die in einer Browsersitzung erfolgen muss, können Sie sehen. Wenn Sie nur SSH-Protokolle lesen, verschmelzen Sie „Kanal ist in Ordnung“ und „Erweiterungen sind in Ordnung“ in einem Ticket und verschwenden dann Tage damit, einem Geist nachzujagen, wenn nur die Hälfte des Stapels jemals validiert wurde.
Ein Mac unter Ihrem Schreibtisch braucht immer noch jemanden, der sich um den Ruhezustand, die Stromversorgung und die Apple Silicon-Thermik kümmert. Ageleaster Cloud-Mac mit SSH und geplantem VNCist oft der sauberere Weg, ein zweites Paar Augen auf 18789 zu werfen, ohne jemanden zu einem Schrankregal zu fliegen. Bei den wirtschaftlichen Gesichtspunkten geht es darum, wer spät in der Nacht Laufwerksersatzteile und Colo-Händler trägt, und nicht darum, ob OpenClaw „einfach“ ist.
Um einen projektbezogenen Apple Silicon-Knoten zu mieten, der diesen Checklisten entspricht, verwenden SieVNCMac: DieCloud-Mac-KaufSeite für Pläne und dieHomepagefür den Produktkontext. Behalten Sie diePaarungUndDockerArtikel im selben Laufordner, sodass das gesamte Team eine Karte von den Pixeln bis zur Prozessliste gemeinsam nutzen kann.