OpenClaw einbetten

Ein einbettender Host sollte die installierte ausführbare Datei openclaw überwachen, das Gateway-WebSocket-Protokoll als Steuerungsebene verwenden und den Kindprozess als austauschbare Laufzeit behandeln. Dadurch bleiben Prozessverantwortung, Bereitschaft, Wiederherstellung nach Fehlern und Upgrades explizit, ohne von der privaten Zustandsstruktur von OpenClaw abhängig zu sein.

Informationen zur Client-Authentifizierung und zum Wiederverbindungsstatus finden Sie unter Erstellen eines Gateway-Clients.

Kindprozess mit einer Einbettungsvoreinstellung starten

Verwenden Sie eine echte node_modules-Installation und starten Sie die ausführbare Datei des Pakets. Eine sinnvolle Ausgangsbasis für einen Host, der Erkennung, Neustart und den Lebenszyklus der Kanäle verwaltet, ist:

import { spawn } from "node:child_process";import { dirname, resolve } from "node:path";import { fileURLToPath } from "node:url"; // Geben Sie einen absoluten Pfad zu einer echten Node-Laufzeit an, die von der Hostanwendung verwaltet wird.declare const hostNodeExecutable: string; const packageEntry = fileURLToPath(import.meta.resolve("openclaw"));const openclawEntry = resolve(dirname(packageEntry), "..", "openclaw.mjs");const gateway = spawn(hostNodeExecutable, [openclawEntry, "gateway", "--allow-unconfigured"], {  env: {    ...process.env,    OPENCLAW_DISABLE_BONJOUR: "1",    OPENCLAW_EXEC_SHELL_SNAPSHOT: "0",    OPENCLAW_NO_RESPAWN: "1",    OPENCLAW_SKIP_CHANNELS: "1",  },  stdio: ["ignore", "inherit", "inherit"],});

Lösen Sie OpenClaw wie gezeigt über das installierte Paket auf; gehen Sie nicht davon aus, dass eine projektlokale ausführbare Datei openclaw im PATH des Hostprozesses enthalten ist. Das Beispiel erbt die Ausgabe, damit der Kindprozess nicht durch volle stdout- oder stderr-Pipes blockiert werden kann. Wenn der Host diese Streams stattdessen erfasst, binden Sie unmittelbar nach dem Start Verbraucher an.

--allow-unconfigured umgeht nur die Startprüfung gateway.mode=local. Die Option schreibt keine Konfiguration und repariert keine ungültige Datei. Lassen Sie sie weg, wenn die einbettende App über das Onboarding, die Konfigurations-CLI oder Gateway-RPC eine normale lokale Konfiguration bereitstellt.

Warnung zum Electron-Shell-Snapshot

Bei der Erfassung des Shell-Snapshots wird process.execPath -e <script> aus einer Login-Shell ausgeführt. In einem normalen Node-Prozess ist process.execPath die ausführbare Node-Datei. Unter Electron ist es die Electron-Binärdatei, die den Aufruf als Anwendungsstart interpretieren und ein Popup mit der Meldung „Unable to find Electron app“ anzeigen kann. Legen Sie OPENCLAW_EXEC_SHELL_SNAPSHOT=0 in der Umgebung des Gateway-Kindprozesses fest, nicht nur im Renderer-Prozess. Aus demselben Grund muss hostNodeExecutable auf eine echte Node-Laufzeit und nicht auf Electrons process.execPath verweisen.

Ungültige Konfiguration anhand des Exit-Codes behandeln

Beim Start verwendet das Gateway den Exit-Code 78 (EX_CONFIG) für konfigurationsbedingte Startfehler, einschließlich einer ungültigen Konfiguration. Verzweigen Sie anhand des Exit-Codes, anstatt menschenlesbare stderr-Ausgaben auszuwerten:

1. Führen Sie openclaw doctor --fix --yes --non-interactive mit derselben Konfigurations- und Zustandsumgebung wie der Gateway-Kindprozess aus.
2. Versuchen Sie den Gateway-Start einmal erneut, nachdem Doctor erfolgreich beendet wurde.
3. Wenn der Kindprozess erneut mit 78 beendet wird, beenden Sie die Reparaturschleife und zeigen Sie dem Benutzer den Konfigurationsfehler an.

Bewahren Sie stderr für Diagnosezwecke auf, treffen Sie jedoch keine Entscheidungen zum Lebenszyklus anhand des Wortlauts.

Nach einem erfolgreichen Start hat eine ungültige Änderung der aktiven Konfiguration weniger schwerwiegende Folgen. Der Konfigurations-Watcher protokolliert, dass das Neuladen übersprungen wurde, und verwendet weiterhin die zuletzt akzeptierte In-Memory-Konfiguration. Reparieren Sie die Datei und lassen Sie den Watcher anschließend den nächsten gültigen Snapshot übernehmen.

Auf Protokollbereitschaft warten

Verwenden Sie WebSocket-Signale statt einer Teilzeichenfolge im Protokoll:

1. Öffnen Sie den Gateway-WebSocket.
2. Warten Sie auf das Ereignis connect.challenge. Es belegt, dass der Listener den WebSocket akzeptiert hat und der Challenge-Handshake beginnen kann.
3. Senden Sie connect mit der an die Challenge gebundenen Gerätesignatur.
4. Behandeln Sie hello-ok als Anwendungsbereitschaft für authentifizierte RPC-Aufrufe.

Die Challenge erfolgt absichtlich vor der vollständigen Initialisierung. Wenn beim Start Nebenprozesse noch ausstehen, gibt connect einen wiederholbaren Fehler UNAVAILABLE mit details.reason: "startup-sidecars" und einem begrenzten retryAfterMs zurück und schließt anschließend mit dem Code 1013 und dem Grund gateway starting. Verwenden Sie resolveGatewayStartupRetryAfterMs aus @openclaw/gateway-protocol/startup-unavailable oder die integrierte Richtlinie des Referenzclients und stellen Sie anschließend die Verbindung erneut her.

Neustart und Herunterfahren interpretieren

Vor einem geordneten Schließen sendet das Gateway ein Ereignis shutdown mit reason und restartExpectedMs. Ein nicht nullwertiges restartExpectedMs bedeutet, dass ein prozessinterner oder überwachter Neustart erwartet wird; null bedeutet ein endgültiges Herunterfahren.

Der anschließende WebSocket-Schließcode lautet in beiden Fällen 1012. Der gewöhnliche Schließgrund des Clients lautet ebenfalls in beiden Fällen service restart, sodass weder der Schließcode noch der Grund zwischen Neustart und Herunterfahren unterscheiden. Bewahren Sie die vorherige shutdown-Nutzlast auf, wenn sie eintrifft, und kombinieren Sie sie mit der eigenen Beendigungsabsicht des Hosts und dem Exit-Status des Kindprozesses. Wenn die Verbindung ohne dieses Ereignis abbricht, verwenden Sie die normale begrenzte Richtlinie für Wiederverbindungen und die Überwachung des Kindprozesses.

RPC statt Zustandsdateien verwenden

Behalten Sie das Gateway als alleinigen Eigentümer des OpenClaw-Zustands bei. Für gängige Einbettungsoperationen stehen bereits RPC-Methoden zur Verfügung:

config.get schwärzt sensible Werte und SecretRef-Bezeichner, bevor der Snapshot zurückgegeben wird. Schreibmethoden geben ebenfalls eine geschwärzte Konfiguration zurück. Ein Client muss den Schwärzungsplatzhalter als undurchsichtig behandeln und den dokumentierten Vertrag zum Schreiben der Konfiguration verwenden; er darf niemals erwarten, dass das Gateway Geheimnisse im Klartext zurückgibt.

Lesen oder verändern Sie keine Dateien, SQLite-Tabellen, Transkriptdateien oder Cache-Verzeichnisse unter ~/.openclaw, um App-Funktionen zu implementieren. Diese Strukturen sind private Implementierungsdetails der Laufzeit und können ohne Protokollkompatibilität verschoben oder geändert werden.

Installieren, nicht vereinfachen

Das Stammpaket openclaw ist kein Ziel für das Vendoring als einzelne Datei. Gebündelte Laufzeitdateien unter dist/extensions behalten unqualifizierte Selbstimporte wie openclaw/plugin-sdk/* bei, während das npm-Paket absichtlich erweiterungsspezifische node_modules-Verzeichnisbäume ausschließt.

Installieren Sie OpenClaw über npm, pnpm oder eine andere normale Node-Paketinstallation, damit Node die Paketexporte und den Abhängigkeitsbaum des Stammpakets auflösen kann. Starten Sie die installierte ausführbare Datei openclaw. Kopieren Sie nicht nur dist, vereinfachen Sie das Paket nicht zu einem App- Bundle und übernehmen Sie keine ausgewählten Erweiterungsdateien in das Projekt.

Verwandte Themen

• Erstellen eines Gateway-Clients
• Gateway-Protokoll
• Gateway-CLI
• Gateway-Integrationen für externe Apps