Node-Kopplung

• Gerätekopplung (Rolle node) steuert den connect-Handshake. Siehe Automatische Gerätegenehmigung über vertrauenswürdige CIDRs unten und Kanalkopplung.
• Genehmigung von Node-Funktionen (node.pair.*) steuert, welche deklarierten Funktionen/Befehle ein verbundener Node bereitstellen darf. Das Gateway ist die maßgebliche Quelle; Benutzeroberflächen (macOS-App, Control UI) sind Frontends, die ausstehende Anfragen genehmigen oder ablehnen.

​

Funktionsweise der Funktionsgenehmigung

1. Ein Node stellt eine Verbindung zum Gateway-WS her (die Gerätekopplung steuert diesen Schritt).
2. Das Gateway vergleicht die deklarierte Funktions-/Befehlsoberfläche mit der genehmigten Oberfläche; neue oder erweiterte Oberflächen speichern eine ausstehende Anfrage im Gerätedatensatz und lösen node.pair.requested aus.
3. Sie genehmigen die Anfrage oder lehnen sie ab (CLI oder Benutzeroberfläche).
4. Bis zur Genehmigung bleiben Node-Befehle gefiltert; die Genehmigung gibt die deklarierte Oberfläche gemäß der normalen Befehlsrichtlinie frei.

​

CLI-Ablauf (für Headless-Systeme geeignet)

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

​

API-Oberfläche (Gateway-Protokoll)

• node.pair.requested – wird ausgelöst, wenn eine neue ausstehende Anfrage erstellt wird.
• node.pair.resolved – wird ausgelöst, wenn eine Anfrage genehmigt, abgelehnt oder abgelaufen ist.

• node.pair.list – listet ausstehende und gekoppelte Nodes auf (operator.pairing).
• node.pair.approve – genehmigt eine ausstehende Anfrage.
• node.pair.reject – lehnt eine ausstehende Anfrage ab.
• node.pair.remove – entfernt einen gekoppelten Node. Dadurch wird die Rolle node des Geräts im Speicher für gekoppelte Geräte widerrufen, die genehmigte Node-Oberfläche ebenfalls entfernt und die Sitzungen dieses Geräts mit Node-Rolle werden ungültig gemacht/getrennt. Ein Gerät mit mehreren Rollen (beispielsweise eines, das auch operator besitzt) behält seine Zeile und verliert nur die Rolle node; die Zeile eines reinen Node-Geräts wird gelöscht. Autorisierung: operator.pairing darf Node-Zeilen entfernen, die nicht zu Operatoren gehören; ein Aufrufer mit Geräte-Token, der auf einem Gerät mit mehreren Rollen seine eigene Node-Rolle widerruft, benötigt zusätzlich operator.admin.
• node.rename – benennt den für Operatoren sichtbaren Anzeigenamen eines gekoppelten Nodes um.

• Erneute Verbindungen mit unveränderter Oberfläche verwenden die ausstehende Anfrage wieder; wiederholte Anfragen aktualisieren die gespeicherten Node-Metadaten und den neuesten auf der Zulassungsliste stehenden Snapshot der deklarierten Befehle für die Sichtbarkeit durch Operatoren.
• Operator-Berechtigungsstufen und Prüfungen zum Genehmigungszeitpunkt sind unter Operator-Berechtigungen zusammengefasst.
• node.pair.approve verwendet die deklarierten Befehle der ausstehenden Anfrage, um zusätzliche Genehmigungsberechtigungen durchzusetzen:
  • Anfrage ohne Befehle: operator.pairing
  • Anfrage mit gewöhnlichen Befehlen: operator.pairing + operator.write
  • administrativ sensible Anfrage, die system.run, system.run.prepare, system.which, browser.proxy, fs.listDir oder system.execApprovals.get/set enthält: operator.pairing + operator.admin

​

Steuerung von Node-Befehlen (2026.3.31+)

• Nodes, die sich bisher allein auf die Gerätekopplung verlassen haben, um Befehle bereitzustellen, müssen nun zusätzlich die Node-Kopplung abschließen.
• Vor der Kopplungsgenehmigung in die Warteschlange gestellte Befehle werden verworfen und nicht zurückgestellt.

​

Vertrauensgrenzen für Node-Ereignisse (2026.3.31+)

​

SSH-verifizierte automatische Gerätegenehmigung (Standard)

• Der Benutzer des Gateway-Prozesses (oder sshVerify.user) kann sich per SSH nicht interaktiv mit dem Node-Host verbinden (Schlüssel/Agent; Tailscale SSH funktioniert ebenfalls), und dem Hostschlüssel wird bereits vertraut.
• openclaw wird auf dem entfernten PATH für nicht interaktives sh -lc aufgelöst.
• Die verbindende IP-Adresse ist eine direkte (nicht über einen Proxy geleitete, keine Loopback-Adresse) private, ULA-, Link-Local- oder CGNAT-Adresse oder entspricht sshVerify.cidrs, wenn dies festgelegt ist.
• Dieselbe Mindestvoraussetzung wie bei der Genehmigung über vertrauenswürdige CIDRs: nur eine neue Node-Kopplung ohne Berechtigungen; Upgrades, Browser, Control UI und WebChat erfordern immer eine Aufforderung.

{
  gateway: {
    nodes: {
      pairing: {
        // Vollständig deaktivieren:
        sshVerify: false,
        // ...oder Umfang/Parameter der Prüfung festlegen:
        // sshVerify: { user: "me", identity: "~/.ssh/probe", timeoutMs: 7000, cidrs: ["10.0.0.0/8"] },
      },
    },
  },
}

​

Automatische Genehmigung (macOS-App)

• die Anfrage als silent markiert ist (das Gateway markiert die erste Funktionsoberfläche als still, wenn die Gerätekopplung nicht interaktiv genehmigt wurde), und
• die App eine SSH-Verbindung zum Gateway-Host mit demselben Benutzer verifizieren kann.

​

Automatische Gerätegenehmigung über vertrauenswürdige CIDRs

{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}

• Deaktiviert, wenn gateway.nodes.pairing.autoApproveCidrs nicht festgelegt ist.
• Es gibt keinen pauschalen automatischen Genehmigungsmodus für LANs oder private Netzwerke; die SSH-verifizierte automatische Genehmigung (oben) erfordert einen kryptografischen Abgleich des Geräteschlüssels und niemals nur die Netzwerkzugehörigkeit.
• Nur eine neue Gerätekopplungsanfrage für role: node ohne angeforderte Berechtigungen ist berechtigt.
• Operator-, Browser-, Control-UI- und WebChat-Clients bleiben manuell.
• Upgrades von Rollen, Berechtigungen, Metadaten und öffentlichen Schlüsseln bleiben manuell.
• Loopback-Pfade auf demselben Host mit Headern eines vertrauenswürdigen Proxys sind nicht berechtigt, da dieser Pfad von lokalen Aufrufern gefälscht werden kann.

​

Bereinigung nach Ersetzung stiller Kopplungen

• Nur Datensätze, deren letzte Genehmigung lokal auf demselben Host (silent) erfolgte, kommen sowohl als Auslöser als auch als Ziel infrage. Durch vertrauenswürdige CIDRs und SSH verifizierte Kopplungen erstrecken sich über mehrere Hosts, bei denen die Anzeigemetadaten keine Maschinenidentität darstellen. Daher werden sie niemals automatisch entfernt — verwenden Sie dafür die Bereinigung in der Control UI oder openclaw nodes remove.
• Vom Eigentümer genehmigte sowie per QR-/Einrichtungscode (Bootstrap) vorgenommene Kopplungen werden niemals automatisch entfernt. Datensätze, die genehmigt wurden, bevor Herkunftsinformationen verfügbar waren, bleiben geschützt, selbst nach einer späteren stillen erneuten Genehmigung derselben Geräte-ID.
• Derzeit verbundene Geräte werden übersprungen, sodass gleichzeitige lokale Sitzungen mit separaten Statusverzeichnissen ihre Token behalten, solange sie aktiv sind. Datensätze, die innerhalb der letzten Minute genehmigt wurden, werden ebenfalls übersprungen, damit gleichzeitige Kopplungs-Handshakes einander nicht aufheben können, bevor ihre Verbindungen registriert sind.
• Betroffene Clients sind konstruktionsbedingt lokal und koppeln sich daher bei ihrer nächsten Verbindung still erneut.

​

Automatische Genehmigung bei Metadatenaktualisierungen

​

Hilfsfunktionen für die QR-Kopplung

​

Lokalität und weitergeleitete Header

​

Speicherung (lokal, privat)

• ~/.openclaw/state/openclaw.sqlite (gekoppelte Geräte mit Geräteauthentifizierung, genehmigte Node-Oberflächen, ausstehende Oberflächenanfragen, ausstehende Gerätekopplungsanfragen und Bootstrap-Token)

• Geräte-Token sind Geheimnisse; behandeln Sie die Statusdatenbank als vertraulich.
• Zum Rotieren eines Geräte-Tokens wird openclaw devices rotate / device.token.rotate verwendet.

​

Transportverhalten

• Der Transport ist zustandslos; er speichert keine Mitgliedschaften.
• Wenn das Gateway offline oder die Kopplung deaktiviert ist, können Nodes nicht gekoppelt werden.
• Im Remote-Modus erfolgt die Kopplung mit dem Speicher des entfernten Gateways.

​

Verwandte Themen

• Kanalkopplung
• Nodes-CLI
• Geräte-CLI