RPC-Adapter in OpenClaw: Externe CLIs stabil anbinden

Es ist oft frustrierend, externe Tools in eine bestehende Architektur einzubinden. Du hast ein CLI-Tool, das lokal super funktioniert, aber sobald es automatisiert mit anderen Komponenten sprechen soll, fangen die Probleme mit dem Prozess-Management an. Wenn Prozesse unerwartet sterben oder die Kommunikation zwischen den Komponenten instabil ist, wird die Wartung zum Albtraum.

OpenClaw löst das über RPC-Adapter. Anstatt komplexe Wrapper zu bauen, kommuniziert das System über JSON-RPC direkt mit den Tools. Das macht die Integration vorhersehbar und sorgt dafür, dass du dich nicht um das manuelle Parsen von unstrukturierten Terminal-Ausgaben kümmern musst.

Voraussetzungen

• signal-cli (für Pattern A)
• imsg (für Pattern B / Legacy)

Schnellstart

OpenClaw nutzt aktuell zwei Patterns, um externe CLIs anzubinden. Hier ist der Überblick, wie du diese einsetzt.

Pattern A: HTTP Daemon (signal-cli)

In diesem Szenario läuft signal-cli als Hintergrunddienst (Daemon) und kommuniziert über JSON-RPC via HTTP.

• Kommunikation: Events fließen über einen SSE-Stream (/api/v1/events), während der Status über die Health Probe /api/v1/check abgefragt wird.
• Lifecycle: Wenn du die Konfiguration channels.signal.autoStart=true nutzt, übernimmt OpenClaw das Starten und Stoppen des Daemons automatisch.

Pattern B: stdio Child-Prozess (Legacy: imsg)

Hinweis: Verwende für neue iMessage-Setups bitte BlueBubbles.

Hier startet OpenClaw imsg rpc direkt als Kindprozess. Die Kommunikation erfolgt zeilenweise über stdin und stdout (ein JSON-Objekt pro Zeile). Es ist kein TCP-Port oder Daemon erforderlich. Folgende Kernmethoden werden genutzt:

• watch.subscribe & watch.unsubscribe für Benachrichtigungen (Method: message).
• send zum Versenden von Nachrichten.
• chats.list für Diagnosen und das Abrufen von Chat-Listen.

Best Practices für Adapter

Damit deine Integration stabil bleibt, solltest du diese vier Richtlinien beachten:

• Das Gateway steuert den Prozess; Start und Stopp sind fest an den Lifecycle des Providers gebunden.
• Halte RPC-Clients resilient, indem du konsequente Timeouts implementierst.
• Sorge dafür, dass Prozesse bei einem unerwarteten Exit automatisch neu gestartet werden.
• Bevorzuge immer stabile IDs wie chat_id gegenüber Anzeigenamen (Display Strings).

Fehlerbehebung

• Verbindungsabbrüche: RPC-Clients müssen resilient sein. Stelle sicher, dass Timeouts definiert sind und der Prozess bei einem Exit automatisch neu startet.
• Adressierungsprobleme: Falls Nachrichten nicht ankommen, nutze chats.list für Diagnosen und verwende bevorzugt die chat_id für die Adressierung.

AI Setup Assistant

Nächste Schritte

• Signal Dokumentation
• BlueBubbles Integration