`openclaw node`

Starte einen Headless-Node-Host, der sich mit dem Gateway-WebSocket verbindet und system.run / system.which auf diesem Rechner bereitstellt.

Warum einen Node-Host verwenden?

Verwende einen Node-Host, wenn du möchtest, dass Agenten Befehle auf anderen Rechnern in deinem Netzwerk ausführen, ohne dort die vollständige macOS-Companion-App zu installieren.

Typische Anwendungsfälle:

Befehle auf entfernten Linux/Windows-Rechnern ausführen (Build-Server, Lab-Rechner, NAS).
Exec auf dem Gateway sandboxed halten, aber genehmigte Ausführungen an andere Hosts delegieren.
Ein leichtgewichtiges, headless Ausführungsziel für Automatisierung oder CI-Nodes bereitstellen.

Die Ausführung wird weiterhin durch Exec-Genehmigungen und agentenbezogene Allowlists auf dem Node-Host geschützt, sodass du den Befehlszugriff gezielt und explizit halten kannst.

Browser-Proxy (konfigurationsfrei)

Node-Hosts advertisen automatisch einen Browser-Proxy, wenn browser.enabled auf dem Node nicht deaktiviert ist. So kann der Agent Browser-Automatisierung auf diesem Node nutzen, ohne zusätzliche Konfiguration.

Deaktiviere ihn auf dem Node bei Bedarf:

{
  nodeHost: {
    browserProxy: {
      enabled: false,
    },
  },
}

Ausführung (Vordergrund)

openclaw node run --host <gateway-host> --port 18789

Optionen:

--host <host>: Gateway-WebSocket-Host (Standard: 127.0.0.1)
--port <port>: Gateway-WebSocket-Port (Standard: 18789)
--tls: TLS für die Gateway-Verbindung verwenden
--tls-fingerprint <sha256>: Erwarteter TLS-Zertifikats-Fingerprint (sha256)
--node-id <id>: Node-ID überschreiben (löscht das Pairing-Token)
--display-name <name>: Anzeigename des Nodes überschreiben

Gateway-Authentifizierung für den Node-Host

openclaw node run und openclaw node install lösen die Gateway-Auth aus der Konfiguration/Umgebung auf (keine --token/--password-Flags bei Node-Befehlen):

OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD werden zuerst geprüft.
Dann lokaler Konfigurations-Fallback: gateway.auth.token / gateway.auth.password.
Im lokalen Modus erbt der Node-Host absichtlich nicht gateway.remote.token / gateway.remote.password.
Wenn gateway.auth.token / gateway.auth.password explizit über SecretRef konfiguriert und unaufgelöst ist, schlägt die Node-Auth-Auflösung geschlossen fehl (kein Remote-Fallback-Masking).
Im gateway.mode=remote-Modus sind die Remote-Client-Felder (gateway.remote.token / gateway.remote.password) ebenfalls nach Remote-Prioritätsregeln berechtigt.
Veraltete CLAWDBOT_GATEWAY_*-Umgebungsvariablen werden bei der Node-Host-Auth-Auflösung ignoriert.

Dienst (Hintergrund)

Installiere einen Headless-Node-Host als Benutzerdienst.

openclaw node install --host <gateway-host> --port 18789

Optionen:

--host <host>: Gateway-WebSocket-Host (Standard: 127.0.0.1)
--port <port>: Gateway-WebSocket-Port (Standard: 18789)
--tls: TLS für die Gateway-Verbindung verwenden
--tls-fingerprint <sha256>: Erwarteter TLS-Zertifikats-Fingerprint (sha256)
--node-id <id>: Node-ID überschreiben (löscht das Pairing-Token)
--display-name <name>: Anzeigename des Nodes überschreiben
--runtime <runtime>: Dienst-Laufzeit (node oder bun)
--force: Neuinstallation/Überschreiben, falls bereits installiert

Den Dienst verwalten:

openclaw node status
openclaw node stop
openclaw node restart
openclaw node uninstall

Verwende openclaw node run für einen Vordergrund-Node-Host (ohne Dienst).

Dienst-Befehle akzeptieren --json für maschinenlesbare Ausgabe.

Pairing

Die erste Verbindung erstellt eine ausstehende Geräte-Pairing-Anfrage (role: node) auf dem Gateway. Genehmige sie über:

openclaw devices list
openclaw devices approve <requestId>

Der Node-Host speichert seine Node-ID, Token, Anzeigename und Gateway-Verbindungsinformationen in ~/.openclaw/node.json.

Exec-Genehmigungen

system.run wird durch lokale Exec-Genehmigungen gesteuert:

~/.openclaw/exec-approvals.json
Exec-Genehmigungen
openclaw approvals --node <id|name|ip> (vom Gateway aus bearbeiten)