Gateway-owned pairing einrichten

Kennst du das? Du versuchst, neue Nodes in dein System zu bringen, aber die Autorisierung ist ein einziges Ratespiel. Entweder ist der Prozess zu komplex oder du verlierst den Überblick, welche Geräte eigentlich Zugriff haben und warum Anfragen abgelehnt werden.

Eine zentrale Instanz, die klar entscheidet, wer rein darf und wer nicht, spart hier viel Zeit. Genau hier setzt das Gateway-owned pairing an: Das Gateway ist der “Source of Truth” und entscheidet, welche Nodes beitreten dürfen. UIs wie die macOS App dienen dabei nur als Frontend, um Anfragen zu bestätigen oder abzulehnen.

Voraussetzungen

• OpenClaw Gateway
• CLI-Zugriff oder die macOS App
• Nodes, die das Gateway WS Protokoll unterstützen

Schnellstart

In 5 Minuten ist dein Node gepairt. Folge diesem Pfad:

1. Pairing anfragen: Dein Node verbindet sich mit dem Gateway WS und sendet einen Request. Das Gateway erstellt eine pending request.
2. Status prüfen: Nutze die CLI, um offene Anfragen zu sehen: openclaw nodes pending.
3. Freigabe: Bestätige die Anfrage mit openclaw nodes approve <requestId>.
4. Token nutzen: Das Gateway gibt ein neues Token aus. Der Node verbindet sich automatisch mit diesem Token neu und ist damit “paired”.

Wichtig: Ausstehende Anfragen verfallen automatisch nach 5 Minuten.

CLI Workflow

Die CLI ist ideal für Headless-Systeme. Hier sind die wichtigsten Befehle:

openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes reject <requestId>
openclaw nodes status
openclaw nodes rename --node &lt;id|name|ip&gt; --name "Living Room iPad"

Mit nodes status siehst du alle gepairten und verbundenen Nodes sowie deren Capabilities.

API Surface

Wenn du eigene Tools baust, nutzt du diese Events und Methoden des Gateway-Protokolls:

Events:

• node.pair.requested: Wird ausgelöst, wenn eine neue Anfrage eingeht.
• node.pair.resolved: Wird ausgelöst, wenn eine Anfrage bestätigt, abgelehnt oder abgelaufen ist.

Methoden:

• node.pair.request: Erstellt eine Anfrage oder nutzt eine bestehende (idempotent).
• node.pair.list: Listet alle ausstehenden und gepairten Nodes auf.
• node.pair.approve: Bestätigt die Anfrage und generiert ein frisches Token.
• node.pair.reject: Lehnt die Anfrage ab.
• node.pair.verify: Prüft die Kombination aus { nodeId, token }.

Gut zu wissen: Ein Approval generiert immer ein neues Token. Über node.pair.request wird niemals ein Token zurückgegeben. Wenn du silent: true mitsendest, ist das ein Hinweis für Auto-Approval-Flows.

Auto-approval (macOS App)

Die macOS App kann einen silent approval versuchen. Das klappt, wenn:

• Die Anfrage als silent markiert ist.
• Die App eine SSH-Verbindung zum Gateway-Host unter demselben Benutzer verifizieren kann.

Schlägt das fehl, zeigt die App wie gewohnt den “Approve/Reject”-Dialog an.

Storage und Sicherheit

Das Gateway speichert den Pairing-Status lokal in deinem State-Verzeichnis (Standard ist ~/.openclaw):

• ~/.openclaw/nodes/paired.json
• ~/.openclaw/nodes/pending.json

Wenn du OPENCLAW_STATE_DIR änderst, zieht der nodes/ Ordner mit um. Behandle die paired.json vorsichtig, da die enthaltenen Token geheime Zugangsdaten sind. Um ein Token zu rotieren, musst du den Node neu bestätigen oder den Eintrag löschen.

Fehlerbehebung

Node kann nicht pairen

• Prüfe, ob das Gateway online ist.
• Stelle sicher, dass Pairing auf dem Gateway nicht deaktiviert wurde.

Token wird nicht akzeptiert

• Token sind flüchtig bei Neu-Pairing. Wenn ein Node neu gepairt wurde, ist das alte Token sofort ungültig.
• Prüfe, ob der Node-Eintrag in der paired.json noch existiert.

Transport-Probleme

• Der Transport selbst ist stateless und speichert keine Mitgliedschaften.
• Im Remote-Modus findet das Pairing immer gegen den Store des Remote-Gateways statt.

Hast du Fragen zur Einrichtung? Nutze den AI Setup Assistant.

Nächste Schritte

• Gateway Protocol Deep Dive
• CLI Reference
• Node SDK Integration
• Security Best Practices