Android-App

Support-Momentaufnahme

• Rolle: Begleitknoten-App (Android hostet den Gateway nicht).
• Gateway erforderlich: ja (führen Sie ihn unter macOS, Linux oder Windows über WSL2 aus).
• Installation: Google Play für die App, Erste Schritte für den Gateway, dann Kopplung.
• Gateway: Runbook + Konfiguration.
  • Protokolle: Gateway-Protokoll (Knoten + Steuerungsebene).

Systemsteuerung

Die Systemsteuerung (launchd/systemd) befindet sich auf dem Gateway-Host. Siehe Gateway.

Verbindungs-Runbook

Android-Knoten-App ⇄ (mDNS/NSD + WebSocket) ⇄ Gateway

Android verbindet sich direkt mit dem Gateway-WebSocket und verwendet die Gerätekopplung (role: node).

Für Tailscale oder öffentliche Hosts benötigt Android einen sicheren Endpunkt:

• Bevorzugt: Tailscale Serve / Funnel mit https://<magicdns> / wss://<magicdns>
• Ebenfalls unterstützt: jede andere wss://-Gateway-URL mit einem echten TLS-Endpunkt
• Klartext-ws:// wird weiterhin für private LAN-Adressen / .local-Hosts sowie localhost, 127.0.0.1 und die Android-Emulator-Bridge (10.0.2.2) unterstützt

Voraussetzungen

• Sie können den Gateway auf dem „Master“-Computer ausführen.
• Android-Gerät/-Emulator kann den Gateway-WebSocket erreichen:
  • Gleiches LAN mit mDNS/NSD, oder
  • Gleiches Tailscale-Tailnet mit Wide-Area Bonjour / Unicast-DNS-SD (siehe unten), oder
  • Manueller Gateway-Host/-Port (Fallback)
• Tailnet-/öffentliche mobile Kopplung verwendet keine rohen Tailnet-IP-ws://-Endpunkte. Verwenden Sie stattdessen Tailscale Serve oder eine andere wss://-URL.
• Sie können die CLI (openclaw) auf dem Gateway-Computer ausführen (oder per SSH).

1) Gateway starten

openclaw gateway --port 18789 --verbose

Bestätigen Sie in den Logs, dass Sie etwas wie Folgendes sehen:

• listening on ws://0.0.0.0:18789

Für Remote-Android-Zugriff über Tailscale bevorzugen Sie Serve/Funnel statt einer rohen Tailnet-Bindung:

openclaw gateway --tailscale serve

Dadurch erhält Android einen sicheren wss://- / https://-Endpunkt. Eine einfache gateway.bind: "tailnet"-Einrichtung reicht für die erstmalige Remote-Android-Kopplung nicht aus, es sei denn, Sie terminieren TLS zusätzlich separat.

2) Discovery überprüfen (optional)

Vom Gateway-Computer aus:

dns-sd -B _openclaw-gw._tcp local.

Weitere Debugging-Hinweise: Bonjour.

Wenn Sie außerdem eine Wide-Area-Discovery-Domain konfiguriert haben, vergleichen Sie mit:

openclaw gateway discover --json

Das zeigt local. plus die konfigurierte Wide-Area-Domain in einem Durchlauf und verwendet den aufgelösten Dienstendpunkt statt reiner TXT-Hinweise.

Tailnet-Discovery (Wien ⇄ London) über Unicast-DNS-SD

Android-NSD-/mDNS-Discovery überschreitet keine Netzwerke. Wenn Ihr Android-Knoten und der Gateway in unterschiedlichen Netzwerken sind, aber über Tailscale verbunden sind, verwenden Sie stattdessen Wide-Area Bonjour / Unicast-DNS-SD.

Discovery allein reicht für Tailnet-/öffentliche Android-Kopplung nicht aus. Die erkannte Route benötigt weiterhin einen sicheren Endpunkt (wss:// oder Tailscale Serve):

1. Richten Sie eine DNS-SD-Zone (Beispiel openclaw.internal.) auf dem Gateway-Host ein und veröffentlichen Sie _openclaw-gw._tcp-Einträge.
2. Konfigurieren Sie Tailscale Split-DNS für Ihre gewählte Domain, die auf diesen DNS-Server zeigt.

Details und Beispiel-CoreDNS-Konfiguration: Bonjour.

3) Von Android verbinden

In der Android-App:

• Die App hält ihre Gateway-Verbindung über einen Vordergrunddienst (dauerhafte Benachrichtigung) aktiv.
• Öffnen Sie den Tab Connect.
• Verwenden Sie den Modus Setup Code oder Manual.
• Wenn Discovery blockiert ist, verwenden Sie manuellen Host/Port in Advanced controls. Für private LAN-Hosts funktioniert ws:// weiterhin. Für Tailscale-/öffentliche Hosts aktivieren Sie TLS und verwenden Sie einen wss://- / Tailscale-Serve-Endpunkt.

Nach der ersten erfolgreichen Kopplung verbindet sich Android beim Start automatisch erneut:

• Manueller Endpunkt (falls aktiviert), andernfalls
• Der zuletzt erkannte Gateway (Best-Effort).

Presence-Alive-Beacons

Nachdem die authentifizierte Knotensitzung verbunden ist und wenn die App in den Hintergrund wechselt, während der Vordergrunddienst weiterhin verbunden ist, ruft Android node.event mit event: "node.presence.alive" auf. Der Gateway speichert dies erst dann als lastSeenAtMs/lastSeenReason in den gekoppelten Knoten-/Gerätemetadaten, nachdem die authentifizierte Knotengeräteidentität bekannt ist.

Die App zählt den Beacon nur dann als erfolgreich gespeichert, wenn die Gateway-Antwort handled: true enthält. Ältere Gateways können node.event mit { "ok": true } bestätigen; diese Antwort ist kompatibel, zählt jedoch nicht als dauerhaftes Last-Seen-Update.

4) Kopplung genehmigen (CLI)

Auf dem Gateway-Computer:

openclaw devices listopenclaw devices approve <requestId>openclaw devices reject <requestId>

Kopplungsdetails: Kopplung.

Optional: Wenn der Android-Knoten immer aus einem streng kontrollierten Subnetz verbindet, können Sie sich für die erstmalige automatische Knotengenehmigung mit expliziten CIDRs oder genauen IPs entscheiden:

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

Dies ist standardmäßig deaktiviert. Es gilt nur für frische role: node-Kopplungen ohne angeforderte Scopes. Operator-/Browser-Kopplung sowie jede Rollen-, Scope-, Metadaten- oder Public-Key-Änderung erfordern weiterhin manuelle Genehmigung.

5) Überprüfen, ob der Knoten verbunden ist

• Über Knotenstatus:

  openclaw nodes status

• Über Gateway:

  openclaw gateway call node.list --params "{}"

6) Chat + Verlauf

Der Android-Chat-Tab unterstützt Sitzungsauswahl (Standard main, plus andere vorhandene Sitzungen):

• Verlauf: chat.history (anzeige-normalisiert; Inline-Direktiv-Tags werden aus sichtbarem Text entfernt, Plain-Text-XML-Nutzdaten von Tool-Aufrufen (einschließlich <tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls>, <function_calls>...</function_calls> und gekürzten Tool-Aufrufblöcken) sowie geleakte ASCII-/Vollbreiten-Modellsteuerungstoken werden entfernt, reine Silent-Token-Assistentenzeilen wie exakt NO_REPLY / no_reply werden ausgelassen, und übergroße Zeilen können durch Platzhalter ersetzt werden)
• Senden: chat.send
• Push-Updates (Best-Effort): chat.subscribe → event:"chat"

7) Canvas + Kamera

Gateway Canvas Host (für Webinhalte empfohlen)

Wenn der Knoten echtes HTML/CSS/JS anzeigen soll, das der Agent auf der Festplatte bearbeiten kann, richten Sie den Knoten auf den Gateway-Canvas-Host.

1. Erstellen Sie ~/.openclaw/workspace/canvas/index.html auf dem Gateway-Host.

2. Navigieren Sie den Knoten dorthin (LAN):

openclaw nodes invoke --node "&lt;Android Node&gt;" --command canvas.navigate --params '{"url":"http://<gateway-hostname>.local:18789/__openclaw__/canvas/"}'

Tailnet (optional): Wenn beide Geräte in Tailscale sind, verwenden Sie statt .local einen MagicDNS-Namen oder eine Tailnet-IP, z. B. http://<gateway-magicdns>:18789/__openclaw__/canvas/.

Dieser Server injiziert einen Live-Reload-Client in HTML und lädt bei Dateiänderungen neu. Der Gateway stellt auch /__openclaw__/a2ui/ bereit, aber die Android-App behandelt Remote-A2UI-Seiten als reines Rendering. Aktionsfähige A2UI-Befehle verwenden die gebündelte app-eigene A2UI-Seite, bevor Nachrichten angewendet werden.

Canvas-Befehle (nur im Vordergrund):

• canvas.eval, canvas.snapshot, canvas.navigate (verwenden Sie {"url":""} oder {"url":"/"}, um zum Standardgerüst zurückzukehren). canvas.snapshot gibt { format, base64 } zurück (Standard format="jpeg").
• A2UI: canvas.a2ui.push, canvas.a2ui.reset (canvas.a2ui.pushJSONL Legacy-Alias). Diese Befehle verwenden die gebündelte app-eigene A2UI-Seite für aktionsfähiges Rendering.

Kamerabefehle (nur im Vordergrund; berechtigungsgebunden):

• camera.snap (jpg)
• camera.clip (mp4)

Siehe Kamera-Knoten für Parameter und CLI-Hilfsfunktionen.

8) Sprache + erweiterte Android-Befehlsoberfläche

• Voice-Tab: Android hat zwei explizite Aufnahmemodi. Mic ist eine manuelle Voice-Tab-Sitzung, die jede Pause als Chat-Turn sendet und stoppt, wenn die App den Vordergrund verlässt oder der Benutzer den Voice-Tab verlässt. Talk ist der kontinuierliche Talk Mode und hört weiter zu, bis er ausgeschaltet wird oder der Knoten die Verbindung trennt.
• Talk Mode stuft den vorhandenen Vordergrunddienst vor Beginn der Aufnahme von connectedDevice auf connectedDevice|microphone hoch und stuft ihn wieder herab, wenn Talk Mode stoppt. Der Knotendienst deklariert FOREGROUND_SERVICE_CONNECTED_DEVICE mit CHANGE_NETWORK_STATE; Android 14+ erfordert außerdem die Deklaration FOREGROUND_SERVICE_MICROPHONE, die Laufzeitberechtigung RECORD_AUDIO und den Mikrofon-Diensttyp zur Laufzeit.
• Standardmäßig verwendet Android Talk native Spracherkennung, Gateway-Chat und talk.speak über den konfigurierten Gateway-Talk-Provider. Lokales System-TTS wird nur verwendet, wenn talk.speak nicht verfügbar ist.
• Android Talk verwendet den Echtzeit-Gateway-Relay nur, wenn talk.realtime.mode realtime ist und talk.realtime.transport gateway-relay ist.
• Voice Wake bleibt in der Android-UX/-Laufzeit deaktiviert.
• Zusätzliche Android-Befehlsfamilien (Verfügbarkeit hängt von Gerät, Berechtigungen und Benutzereinstellungen ab):
  • device.status, device.info, device.permissions, device.health
  • device.apps nur, wenn Settings > Phone Capabilities > Installed Apps aktiviert ist; es listet standardmäßig launcher-sichtbare Apps auf.
  • notifications.list, notifications.actions (siehe Benachrichtigungsweiterleitung unten)
  • photos.latest
  • contacts.search, contacts.add
  • calendar.events, calendar.add
  • callLog.search
  • sms.search
  • motion.activity, motion.pedometer

Assistenten-Einstiegspunkte

Android unterstützt das Starten von OpenClaw über den Systemassistenten-Trigger (Google Assistant). Wenn konfiguriert, öffnet das Halten der Home-Taste oder das Sagen von „Hey Google, frag OpenClaw...“ die App und übergibt den Prompt an den Chat-Composer.

Dies verwendet Android-App Actions-Metadaten, die im App-Manifest deklariert sind. Auf Gateway-Seite ist keine zusätzliche Konfiguration erforderlich -- der Assistenten-Intent wird vollständig von der Android-App verarbeitet und als normale Chat-Nachricht weitergeleitet.

Benachrichtigungsweiterleitung

Android kann Gerätebenachrichtigungen als Ereignisse an den Gateway weiterleiten. Mehrere Steuerelemente erlauben es Ihnen, festzulegen, welche Benachrichtigungen weitergeleitet werden und wann.

Die Benachrichtigungsauswahl verwendet außerdem sichereres Verhalten für weitergeleitete Benachrichtigungsereignisse und verhindert so die versehentliche Weiterleitung sensibler Systembenachrichtigungen.

Beispielkonfiguration:

{  notifications: {    allowPackages: ["com.slack", "com.whatsapp"],    denyPackages: ["com.android.systemui"],    quietHours: {      start: "22:00",      end: "07:00",    },    rateLimit: 5,  },}

Verwandte Themen

• iOS-App
• Nodes
• Fehlerbehebung für Android-Node