--- read_when: - iOS-/Android-Nodes mit einem Gateway koppeln - Node-Canvas/-Kamera für Agent-Kontext verwenden - Neue Node-Befehle oder CLI-Hilfsprogramme hinzufügen summary: 'Nodes: Kopplung, Fähigkeiten, Berechtigungen und CLI-Hilfsfunktionen für Canvas/Kamera/Bildschirm/Gerät/Benachrichtigungen/System' title: Nodes x-i18n: generated_at: "2026-05-06T06:55:11Z" model: gpt-5.5 provider: openai source_hash: 0ca35ddfb3efe374c0494e3883b0cb47b2e31511d4f7115a88f7c644b80d704f source_path: nodes/index.md workflow: 16 --- Ein **Node** ist ein Begleitgerät (macOS/iOS/Android/headless), das sich mit dem Gateway-**WebSocket** (derselbe Port wie für Operatoren) mit `role: "node"` verbindet und über `node.invoke` eine Befehlsoberfläche bereitstellt (z. B. `canvas.*`, `camera.*`, `device.*`, `notifications.*`, `system.*`). Protokolldetails: [Gateway-Protokoll](/de/gateway/protocol). Legacy-Transport: [Bridge-Protokoll](/de/gateway/bridge-protocol) (TCP JSONL; nur historisch für aktuelle Nodes). macOS kann auch im **Node-Modus** ausgeführt werden: Die Menüleisten-App verbindet sich mit dem WS-Server des Gateway und stellt ihre lokalen Canvas-/Kamera-Befehle als Node bereit (sodass `openclaw nodes …` gegen diesen Mac funktioniert). Im Remote-Gateway-Modus wird Browser-Automatisierung vom CLI-Node-Host (`openclaw node run` oder dem installierten Node-Dienst) ausgeführt, nicht vom nativen App-Node. Hinweise: - Nodes sind **Peripheriegeräte**, keine Gateways. Sie führen den Gateway-Dienst nicht aus. - Telegram-/WhatsApp-/usw.-Nachrichten landen auf dem **Gateway**, nicht auf Nodes. - Runbook zur Fehlerbehebung: [/nodes/troubleshooting](/de/nodes/troubleshooting) ## Kopplung + Status **WS-Nodes verwenden Gerätekopplung.** Nodes präsentieren während `connect` eine Geräteidentität; das Gateway erstellt eine Gerätekopplungsanfrage für `role: node`. Genehmigen Sie sie über die Geräte-CLI (oder UI). Schnelle CLI: ```bash openclaw devices list openclaw devices approve openclaw devices reject openclaw nodes status openclaw nodes describe --node ``` Wenn ein Node mit geänderten Authentifizierungsdetails (Rolle/Scopes/öffentlicher Schlüssel) erneut versucht, sich zu verbinden, wird die vorherige ausstehende Anfrage ersetzt und eine neue `requestId` erstellt. Führen Sie `openclaw devices list` erneut aus, bevor Sie genehmigen. Hinweise: - `nodes status` markiert einen Node als **gekoppelt**, wenn seine Gerätekopplungsrolle `node` enthält. - Der Gerätekopplungsdatensatz ist der dauerhafte Vertrag für genehmigte Rollen. Token- Rotation bleibt innerhalb dieses Vertrags; sie kann einen gekoppelten Node nicht in eine andere Rolle hochstufen, die durch die Kopplungsgenehmigung nie gewährt wurde. - `node.pair.*` (CLI: `openclaw nodes pending/approve/reject/remove/rename`) ist ein separater, Gateway-eigener Node-Kopplungsspeicher; er sperrt den WS-`connect`-Handshake **nicht**. - `openclaw nodes remove --node ` löscht veraltete Einträge aus diesem separaten, Gateway-eigenen Node-Kopplungsspeicher. - Der Genehmigungsumfang folgt den deklarierten Befehlen der ausstehenden Anfrage: - Anfrage ohne Befehle: `operator.pairing` - Nicht-Exec-Node-Befehle: `operator.pairing` + `operator.write` - `system.run` / `system.run.prepare` / `system.which`: `operator.pairing` + `operator.admin` ## Remote-Node-Host (system.run) Verwenden Sie einen **Node-Host**, wenn Ihr Gateway auf einem Rechner läuft und Sie Befehle auf einem anderen ausführen möchten. Das Modell spricht weiterhin mit dem **Gateway**; das Gateway leitet `exec`-Aufrufe an den **Node-Host** weiter, wenn `host=node` ausgewählt ist. ### Was wo ausgeführt wird - **Gateway-Host**: empfängt Nachrichten, führt das Modell aus, leitet Tool-Aufrufe weiter. - **Node-Host**: führt `system.run`/`system.which` auf dem Node-Rechner aus. - **Genehmigungen**: werden auf dem Node-Host über `~/.openclaw/exec-approvals.json` durchgesetzt. Hinweis zu Genehmigungen: - Genehmigungsbasierte Node-Ausführungen binden den exakten Anfragekontext. - Für direkte Shell-/Runtime-Dateiausführungen bindet OpenClaw außerdem nach bestem Bemühen einen konkreten lokalen Dateioperanden und verweigert die Ausführung, wenn sich diese Datei vor der Ausführung ändert. - Wenn OpenClaw für einen Interpreter-/Runtime-Befehl nicht genau eine konkrete lokale Datei identifizieren kann, wird die genehmigungsbasierte Ausführung verweigert, statt vollständige Runtime-Abdeckung vorzutäuschen. Verwenden Sie Sandboxing, separate Hosts oder eine explizite vertrauenswürdige Allowlist/einen vollständigen Workflow für breitere Interpreter-Semantik. ### Node-Host starten (Vordergrund) Auf dem Node-Rechner: ```bash openclaw node run --host --port 18789 --display-name "Build Node" ``` ### Remote-Gateway über SSH-Tunnel (Loopback-Bindung) Wenn das Gateway an loopback bindet (`gateway.bind=loopback`, Standard im lokalen Modus), können Remote-Node-Hosts keine direkte Verbindung herstellen. Erstellen Sie einen SSH-Tunnel und richten Sie den Node-Host auf das lokale Ende des Tunnels. Beispiel (Node-Host -> Gateway-Host): ```bash # Terminal A (keep running): forward local 18790 -> gateway 127.0.0.1:18789 ssh -N -L 18790:127.0.0.1:18789 user@gateway-host # Terminal B: export the gateway token and connect through the tunnel export OPENCLAW_GATEWAY_TOKEN="" openclaw node run --host 127.0.0.1 --port 18790 --display-name "Build Node" ``` Hinweise: - `openclaw node run` unterstützt Token- oder Passwort-Authentifizierung. - Env-Vars werden bevorzugt: `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`. - Config-Fallback ist `gateway.auth.token` / `gateway.auth.password`. - Im lokalen Modus ignoriert der Node-Host absichtlich `gateway.remote.token` / `gateway.remote.password`. - Im Remote-Modus sind `gateway.remote.token` / `gateway.remote.password` gemäß den Remote-Vorrangregeln zulässig. - Wenn aktive lokale `gateway.auth.*` SecretRefs konfiguriert, aber nicht auflösbar sind, schlägt die Node-Host-Authentifizierung geschlossen fehl. - Die Authentifizierungsauflösung des Node-Hosts berücksichtigt nur `OPENCLAW_GATEWAY_*`-Env-Vars. ### Node-Host starten (Dienst) ```bash openclaw node install --host --port 18789 --display-name "Build Node" openclaw node start openclaw node restart ``` ### Koppeln + benennen Auf dem Gateway-Host: ```bash openclaw devices list openclaw devices approve openclaw nodes status ``` Wenn der Node mit geänderten Authentifizierungsdetails erneut versucht, sich zu verbinden, führen Sie `openclaw devices list` erneut aus und genehmigen Sie die aktuelle `requestId`. Benennungsoptionen: - `--display-name` bei `openclaw node run` / `openclaw node install` (bleibt auf dem Node in `~/.openclaw/node.json` erhalten). - `openclaw nodes rename --node --name "Build Node"` (Gateway-Override). ### Befehle allowlisten Exec-Genehmigungen gelten **pro Node-Host**. Fügen Sie Allowlist-Einträge vom Gateway aus hinzu: ```bash openclaw approvals allowlist add --node "/usr/bin/uname" openclaw approvals allowlist add --node "/usr/bin/sw_vers" ``` Genehmigungen befinden sich auf dem Node-Host unter `~/.openclaw/exec-approvals.json`. ### Exec auf den Node richten Konfigurieren Sie Standardwerte (Gateway-Config): ```bash openclaw config set tools.exec.host node openclaw config set tools.exec.security allowlist openclaw config set tools.exec.node "" ``` Oder pro Sitzung: ``` /exec host=node security=allowlist node= ``` Nach der Konfiguration läuft jeder `exec`-Aufruf mit `host=node` auf dem Node-Host (vorbehaltlich der Node-Allowlist/Genehmigungen). `host=auto` wählt den Node nicht implizit selbst aus, aber eine explizite `host=node`-Anfrage pro Aufruf ist aus `auto` heraus erlaubt. Wenn Node-Exec der Standard für die Sitzung sein soll, setzen Sie explizit `tools.exec.host=node` oder `/exec host=node ...`. Verwandt: - [Node-Host-CLI](/de/cli/node) - [Exec-Tool](/de/tools/exec) - [Exec-Genehmigungen](/de/tools/exec-approvals) ## Befehle aufrufen Low-Level (rohes RPC): ```bash openclaw nodes invoke --node --command canvas.eval --params '{"javaScript":"location.href"}' ``` Für die gängigen Workflows „dem Agenten einen MEDIA-Anhang geben“ gibt es höherstufige Hilfsfunktionen. ## Befehlsrichtlinie Node-Befehle müssen zwei Gates passieren, bevor sie aufgerufen werden können: 1. Der Node muss den Befehl in seiner WebSocket-`connect.commands`-Liste deklarieren. 2. Die Plattformrichtlinie des Gateway muss den deklarierten Befehl erlauben. Windows- und macOS-Begleit-Nodes erlauben standardmäßig sichere deklarierte Befehle wie `canvas.*`, `camera.list`, `location.get` und `screen.snapshot`. Vertrauenswürdige Nodes, die die `talk`-Capability bewerben oder `talk.*`-Befehle deklarieren, erlauben standardmäßig auch deklarierte Push-to-Talk-Befehle (`talk.ptt.start`, `talk.ptt.stop`, `talk.ptt.cancel`, `talk.ptt.once`), unabhängig vom Plattformlabel. Gefährliche oder datenschutzintensive Befehle wie `camera.snap`, `camera.clip` und `screen.record` erfordern weiterhin ein explizites Opt-in mit `gateway.nodes.allowCommands`. `gateway.nodes.denyCommands` hat immer Vorrang vor Standardwerten und zusätzlichen Allowlist-Einträgen. Plugin-eigene Node-Befehle können eine Gateway-Node-Invoke-Richtlinie hinzufügen. Diese Richtlinie läuft nach der Allowlist-Prüfung und vor der Weiterleitung an den Node, sodass rohes `node.invoke`, CLI-Helfer und dedizierte Agent-Tools dieselbe Plugin- Berechtigungsgrenze teilen. Gefährliche Plugin-Node-Befehle erfordern weiterhin ein explizites Opt-in per `gateway.nodes.allowCommands`. Nachdem ein Node seine deklarierte Befehlsliste geändert hat, lehnen Sie die alte Gerätekopplung ab und genehmigen Sie die neue Anfrage, damit das Gateway den aktualisierten Befehls-Snapshot speichert. ## Screenshots (Canvas-Snapshots) Wenn der Node das Canvas (WebView) anzeigt, gibt `canvas.snapshot` `{ format, base64 }` zurück. CLI-Helfer (schreibt in eine temporäre Datei und gibt `MEDIA:` aus): ```bash openclaw nodes canvas snapshot --node --format png openclaw nodes canvas snapshot --node --format jpg --max-width 1200 --quality 0.9 ``` ### Canvas-Steuerungen ```bash openclaw nodes canvas present --node --target https://example.com openclaw nodes canvas hide --node openclaw nodes canvas navigate https://example.com --node openclaw nodes canvas eval --node --js "document.title" ``` Hinweise: - `canvas present` akzeptiert URLs oder lokale Dateipfade (`--target`) sowie optional `--x/--y/--width/--height` zur Positionierung. - `canvas eval` akzeptiert Inline-JS (`--js`) oder ein Positionsargument. ### A2UI (Canvas) ```bash openclaw nodes canvas a2ui push --node --text "Hello" openclaw nodes canvas a2ui push --node --jsonl ./payload.jsonl openclaw nodes canvas a2ui reset --node ``` Hinweise: - Nur A2UI v0.8 JSONL wird unterstützt (v0.9/createSurface wird abgelehnt). ## Fotos + Videos (Node-Kamera) Fotos (`jpg`): ```bash openclaw nodes camera list --node openclaw nodes camera snap --node # default: both facings (2 MEDIA lines) openclaw nodes camera snap --node --facing front ``` Videoclips (`mp4`): ```bash openclaw nodes camera clip --node --duration 10s openclaw nodes camera clip --node --duration 3000 --no-audio ``` Hinweise: - Der Node muss für `canvas.*` und `camera.*` **im Vordergrund** sein (Hintergrundaufrufe geben `NODE_BACKGROUND_UNAVAILABLE` zurück). - Die Clipdauer wird begrenzt (derzeit `<= 60s`), um übergroße base64-Payloads zu vermeiden. - Android fragt nach Möglichkeit nach `CAMERA`-/`RECORD_AUDIO`-Berechtigungen; verweigerte Berechtigungen schlagen mit `*_PERMISSION_REQUIRED` fehl. ## Bildschirmaufnahmen (Nodes) Unterstützte Nodes stellen `screen.record` (mp4) bereit. Beispiel: ```bash openclaw nodes screen record --node --duration 10s --fps 10 openclaw nodes screen record --node --duration 10s --fps 10 --no-audio ``` Hinweise: - Die Verfügbarkeit von `screen.record` hängt von der Node-Plattform ab. - Bildschirmaufnahmen werden auf `<= 60s` begrenzt. - `--no-audio` deaktiviert die Mikrofonaufnahme auf unterstützten Plattformen. - Verwenden Sie `--screen `, um bei mehreren verfügbaren Bildschirmen ein Display auszuwählen. ## Standort (Nodes) Nodes stellen `location.get` bereit, wenn Standort in den Einstellungen aktiviert ist. CLI-Helfer: ```bash openclaw nodes location get --node openclaw nodes location get --node --accuracy precise --max-age 15000 --location-timeout 10000 ``` Hinweise: - Standort ist **standardmäßig deaktiviert**. - „Immer“ erfordert eine Systemberechtigung; Abruf im Hintergrund erfolgt nach bestem Bemühen. - Die Antwort enthält lat/lon, Genauigkeit (Meter) und Zeitstempel. ## SMS (Android-Nodes) Android-Nodes können `sms.send` bereitstellen, wenn der Benutzer die **SMS**-Berechtigung erteilt und das Gerät Telefonie unterstützt. Low-Level-Aufruf: ```bash openclaw nodes invoke --node --command sms.send --params '{"to":"+15555550123","message":"Hello from OpenClaw"}' ``` Hinweise: - Die Berechtigungsabfrage muss auf dem Android-Gerät akzeptiert werden, bevor die Capability beworben wird. - Wi-Fi-only-Geräte ohne Telefonie bewerben `sms.send` nicht. ## Android-Geräte- + personenbezogene Datenbefehle Android-Nodes können zusätzliche Befehlsfamilien bewerben, wenn die entsprechenden Capabilities aktiviert sind. Verfügbare Familien: - `device.status`, `device.info`, `device.permissions`, `device.health` - `notifications.list`, `notifications.actions` - `photos.latest` - `contacts.search`, `contacts.add` - `calendar.events`, `calendar.add` - `callLog.search` - `sms.search` - `motion.activity`, `motion.pedometer` Beispielaufrufe: ```bash openclaw nodes invoke --node --command device.status --params '{}' openclaw nodes invoke --node --command notifications.list --params '{}' openclaw nodes invoke --node --command photos.latest --params '{"limit":1}' ``` Hinweise: - Motion-Befehle werden anhand der verfügbaren Sensoren über Capabilities gesteuert. ## Systembefehle (Node-Host / Mac-Node) Der macOS-Node stellt `system.run`, `system.notify` und `system.execApprovals.get/set` bereit. Der Headless-Node-Host stellt `system.run`, `system.which` und `system.execApprovals.get/set` bereit. Beispiele: ```bash openclaw nodes notify --node --title "Ping" --body "Gateway ready" openclaw nodes invoke --node --command system.which --params '{"name":"git"}' ``` Hinweise: - `system.run` gibt stdout/stderr/Exit-Code in der Payload zurück. - Shell-Ausführung läuft jetzt über das `exec`-Tool mit `host=node`; `nodes` bleibt die direkte RPC-Oberfläche für explizite Node-Befehle. - `nodes invoke` stellt `system.run` oder `system.run.prepare` nicht bereit; diese bleiben ausschließlich auf dem Exec-Pfad. - Der Exec-Pfad bereitet vor der Genehmigung einen kanonischen `systemRunPlan` vor. Sobald eine Genehmigung erteilt wurde, leitet das Gateway diesen gespeicherten Plan weiter, nicht später vom Aufrufer bearbeitete command/cwd/session-Felder. - `system.notify` berücksichtigt den Status der Benachrichtigungsberechtigung in der macOS-App. - Nicht erkannte Node-Metadaten für `platform` / `deviceFamily` verwenden eine konservative Standard-Allowlist, die `system.run` und `system.which` ausschließt. Wenn Sie diese Befehle absichtlich für eine unbekannte Plattform benötigen, fügen Sie sie explizit über `gateway.nodes.allowCommands` hinzu. - `system.run` unterstützt `--cwd`, `--env KEY=VAL`, `--command-timeout` und `--needs-screen-recording`. - Für Shell-Wrapper (`bash|sh|zsh ... -c/-lc`) werden anfragebezogene `--env`-Werte auf eine explizite Allowlist reduziert (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`). - Bei Immer-erlauben-Entscheidungen im Allowlist-Modus werden für bekannte Dispatch-Wrapper (`env`, `nice`, `nohup`, `stdbuf`, `timeout`) die inneren ausführbaren Pfade statt der Wrapper-Pfade gespeichert. Wenn das Entpacken nicht sicher ist, wird automatisch kein Allowlist-Eintrag gespeichert. - Auf Windows-Node-Hosts im Allowlist-Modus erfordern Shell-Wrapper-Ausführungen über `cmd.exe /c` eine Genehmigung (ein Allowlist-Eintrag allein erlaubt die Wrapper-Form nicht automatisch). - `system.notify` unterstützt `--priority ` und `--delivery `. - Node-Hosts ignorieren `PATH`-Überschreibungen und entfernen gefährliche Start-/Shell-Schlüssel (`DYLD_*`, `LD_*`, `NODE_OPTIONS`, `PYTHON*`, `PERL*`, `RUBYOPT`, `SHELLOPTS`, `PS4`). Wenn Sie zusätzliche PATH-Einträge benötigen, konfigurieren Sie stattdessen die Service-Umgebung des Node-Hosts (oder installieren Sie Tools an Standardorten), anstatt `PATH` über `--env` zu übergeben. - Im macOS-Node-Modus wird `system.run` durch Exec-Genehmigungen in der macOS-App geschützt (Einstellungen → Exec-Genehmigungen). Ask/Allowlist/Full verhalten sich genauso wie beim Headless-Node-Host; abgelehnte Prompts geben `SYSTEM_RUN_DENIED` zurück. - Auf dem Headless-Node-Host wird `system.run` durch Exec-Genehmigungen geschützt (`~/.openclaw/exec-approvals.json`). ## Exec-Node-Bindung Wenn mehrere Nodes verfügbar sind, können Sie Exec an einen bestimmten Node binden. Dadurch wird der Standard-Node für `exec host=node` festgelegt (und kann pro Agent überschrieben werden). Globaler Standard: ```bash openclaw config set tools.exec.node "node-id-or-name" ``` Überschreibung pro Agent: ```bash openclaw config get agents.list openclaw config set agents.list[0].tools.exec.node "node-id-or-name" ``` Aufheben, um jeden Node zu erlauben: ```bash openclaw config unset tools.exec.node openclaw config unset agents.list[0].tools.exec.node ``` ## Berechtigungskarte Nodes können eine `permissions`-Map in `node.list` / `node.describe` enthalten, indiziert nach Berechtigungsnamen (z. B. `screenRecording`, `accessibility`) mit booleschen Werten (`true` = erteilt). ## Headless-Node-Host (plattformübergreifend) OpenClaw kann einen **Headless-Node-Host** (ohne Benutzeroberfläche) ausführen, der eine Verbindung zum Gateway- WebSocket herstellt und `system.run` / `system.which` bereitstellt. Das ist unter Linux/Windows oder zum Ausführen eines minimalen Node neben einem Server nützlich. Starten Sie ihn: ```bash openclaw node run --host --port 18789 ``` Hinweise: - Pairing ist weiterhin erforderlich (das Gateway zeigt einen Prompt zum Geräte-Pairing an). - Der Node-Host speichert seine Node-ID, sein Token, seinen Anzeigenamen und Gateway-Verbindungsinformationen in `~/.openclaw/node.json`. - Exec-Genehmigungen werden lokal über `~/.openclaw/exec-approvals.json` erzwungen (siehe [Exec-Genehmigungen](/de/tools/exec-approvals)). - Unter macOS führt der Headless-Node-Host `system.run` standardmäßig lokal aus. Setzen Sie `OPENCLAW_NODE_EXEC_HOST=app`, um `system.run` über den Exec-Host der Companion-App zu leiten; fügen Sie `OPENCLAW_NODE_EXEC_FALLBACK=0` hinzu, um den App-Host zu verlangen und geschlossen fehlzuschlagen, wenn er nicht verfügbar ist. - Fügen Sie `--tls` / `--tls-fingerprint` hinzu, wenn der Gateway-WS TLS verwendet. ## Mac-Node-Modus - Die macOS-Menüleisten-App verbindet sich als Node mit dem Gateway-WS-Server (sodass `openclaw nodes …` mit diesem Mac funktioniert). - Im Remote-Modus öffnet die App einen SSH-Tunnel für den Gateway-Port und verbindet sich mit `localhost`.