iOS-App

​

Was sie macht

• Verbindet sich per WebSocket mit einem Gateway (LAN oder Tailnet).
• Stellt Node-Funktionen bereit: Canvas, Bildschirm-Snapshot, Kameraaufnahme, Standort, Talk-Modus, Voice Wake.
• Empfängt node.invoke-Befehle und meldet Node-Statusereignisse.

​

Anforderungen

• Gateway, das auf einem anderen Gerät läuft (macOS, Linux oder Windows über WSL2).
• Netzwerkpfad:
  • Gleiches LAN über Bonjour, oder
  • Tailnet über Unicast-DNS-SD (Beispieldomäne: openclaw.internal.), oder
  • Manueller Host/Port (Fallback).

​

Schnellstart (koppeln + verbinden)

1. Starten Sie ein authentifiziertes Gateway mit einer Route, die Ihr Telefon erreichen kann. Tailscale Serve ist der empfohlene Remote-Pfad:

openclaw gateway --port 18789 --tailscale serve

2. Öffnen Sie die Control UI, wählen Sie Nodes aus und klicken Sie in der Devices-Karte auf Pair mobile device.
3. Öffnen Sie in der iOS-App Settings → Gateway, scannen Sie den QR-Code (oder fügen Sie den Setup-Code ein) und stellen Sie die Verbindung her.
4. Die offizielle App verbindet sich automatisch. Wenn Devices eine ausstehende Anfrage anzeigt, prüfen Sie deren Rolle und Scopes, bevor Sie sie genehmigen.

openclaw devices list
openclaw devices approve <requestId>

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

5. Verbindung überprüfen:

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

​

Relay-gestützter Push für offizielle Builds

{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
        },
      },
    },
  },
}

• Die iOS-App registriert sich beim Relay mit App Attest und einem StoreKit-App-Transaktions-JWS.
• Das Relay gibt ein opakes Relay-Handle sowie eine registrierungsbezogene Sendeberechtigung zurück.
• Die iOS-App ruft die Identität des gekoppelten Gateways ab und nimmt sie in die Relay-Registrierung auf, sodass die relay-gestützte Registrierung an dieses spezifische Gateway delegiert wird.
• Die App leitet diese relay-gestützte Registrierung mit push.apns.register an das gekoppelte Gateway weiter.
• Das Gateway verwendet dieses gespeicherte Relay-Handle für push.test, Hintergrund-Wakes und Wake-Anstöße.
• Benutzerdefinierte Gateway-Relay-URLs müssen mit der in den iOS-Build eingebetteten Relay-URL übereinstimmen.
• Wenn sich die App später mit einem anderen Gateway oder einem Build mit einer anderen Relay-Basis-URL verbindet, aktualisiert sie die Relay-Registrierung, statt die alte Bindung wiederzuverwenden.

• Kein deploymentweites Relay-Token.
• Kein direkter APNs-Schlüssel für relay-gestützte Sendungen offizieller App-Store-Builds.

1. Installieren Sie die offizielle iOS-App.
2. Optional: Setzen Sie gateway.push.apns.relay.baseUrl auf dem Gateway nur dann, wenn Sie einen bewusst getrennten benutzerdefinierten Relay-Build verwenden.
3. Koppeln Sie die App mit dem Gateway und lassen Sie sie die Verbindung abschließen.
4. Die App veröffentlicht push.apns.register automatisch, nachdem sie ein APNs-Token hat, die Operator-Sitzung verbunden ist und die Relay-Registrierung erfolgreich war.
5. Danach können push.test, Reconnect-Wakes und Wake-Anstöße die gespeicherte relay-gestützte Registrierung verwenden.

​

Background-alive-Beacons

• OPENCLAW_APNS_RELAY_BASE_URL funktioniert weiterhin als temporäre Env-Überschreibung für das Gateway.
• Der öffentliche App-Store-Release-Zweig lehnt OPENCLAW_PUSH_RELAY_BASE_URL für iOS-Builds ab.

​

Authentifizierungs- und Vertrauensablauf

• Nur echte OpenClaw-iOS-Builds, die über Apple verteilt werden, können das gehostete Relay verwenden.
• Ein Gateway kann relay-gestützte Pushes nur für iOS-Geräte senden, die mit diesem spezifischen Gateway gekoppelt wurden.

1. iOS app -> gateway
   • Die App koppelt sich zuerst über den normalen Gateway-Authentifizierungsablauf mit dem Gateway.
   • Dadurch erhält die App eine authentifizierte Node-Sitzung sowie eine authentifizierte Operator-Sitzung.
   • Die Operator-Sitzung wird verwendet, um gateway.identity.get aufzurufen.
2. iOS app -> relay
   • Die App ruft die Relay-Registrierungsendpunkte über HTTPS auf.
   • Die Registrierung enthält einen App-Attest-Nachweis sowie ein StoreKit-App-Transaktions-JWS.
   • Das Relay validiert Bundle-ID, App-Attest-Nachweis und Apple-Verteilungsnachweis und verlangt den offiziellen/produktiven Verteilungspfad.
   • Dadurch werden lokale Xcode-/Dev-Builds daran gehindert, das gehostete Relay zu verwenden. Ein lokaler Build kann signiert sein, erfüllt aber nicht den offiziellen Apple-Verteilungsnachweis, den das Relay erwartet.
3. gateway identity delegation
   • Vor der Relay-Registrierung ruft die App die Identität des gekoppelten Gateways von gateway.identity.get ab.
   • Die App nimmt diese Gateway-Identität in die Relay-Registrierungsnutzlast auf.
   • Das Relay gibt ein Relay-Handle und eine registrierungsbezogene Sendeberechtigung zurück, die an diese Gateway-Identität delegiert sind.
4. gateway -> relay
   • Das Gateway speichert das Relay-Handle und die Sendeberechtigung aus push.apns.register.
   • Bei push.test, Reconnect-Wakes und Wake-Anstößen signiert das Gateway die Sendeanfrage mit seiner eigenen Geräteidentität.
   • Das Relay prüft sowohl die gespeicherte Sendeberechtigung als auch die Gateway-Signatur gegen die delegierte Gateway-Identität aus der Registrierung.
   • Ein anderes Gateway kann diese gespeicherte Registrierung nicht wiederverwenden, selbst wenn es irgendwie an das Handle gelangt.
5. relay -> APNs
   • Das Relay besitzt die produktiven APNs-Zugangsdaten und das rohe APNs-Token für den offiziellen Build.
   • Das Gateway speichert bei relay-gestützten offiziellen Builds niemals das rohe APNs-Token.
   • Das Relay sendet den finalen Push im Namen des gekoppelten Gateways an APNs.

• Um produktive APNs-Zugangsdaten aus Benutzer-Gateways herauszuhalten.
• Um zu vermeiden, rohe APNs-Token offizieller Builds auf dem Gateway zu speichern.
• Um die Nutzung des gehosteten Relay nur für offizielle OpenClaw-iOS-Builds zu erlauben.
• Um zu verhindern, dass ein Gateway Wake-Pushes an iOS-Geräte sendet, die einem anderen Gateway gehören.

export OPENCLAW_APNS_TEAM_ID="TEAMID"
export OPENCLAW_APNS_KEY_ID="KEYID"
export OPENCLAW_APNS_PRIVATE_KEY_P8="$(cat /path/to/AuthKey_KEYID.p8)"

mkdir -p ~/.openclaw/credentials/apns
chmod 700 ~/.openclaw/credentials/apns
mv /path/to/AuthKey_KEYID.p8 ~/.openclaw/credentials/apns/AuthKey_KEYID.p8
chmod 600 ~/.openclaw/credentials/apns/AuthKey_KEYID.p8
export OPENCLAW_APNS_PRIVATE_KEY_PATH="$HOME/.openclaw/credentials/apns/AuthKey_KEYID.p8"

​

Discovery-Pfade

​

Bonjour (LAN)

​

Tailnet (netzwerkübergreifend)

​

Manueller Host/Port

​

Canvas + A2UI

openclaw nodes invoke --node "iOS Node" --command canvas.navigate --params '{"url":"http://<gateway-host>:18789/__openclaw__/canvas/"}'

• Der Gateway-Canvas-Host stellt /__openclaw__/canvas/ und /__openclaw__/a2ui/ bereit.
• Er wird vom Gateway-HTTP-Server bereitgestellt (derselbe Port wie gateway.port, Standard 18789).
• Die iOS-Node behält das integrierte Scaffold als verbundene Standardansicht. canvas.a2ui.push und canvas.a2ui.reset verwenden die gebündelte, app-eigene A2UI-Seite.
• Remote-Gateway-A2UI-Seiten sind unter iOS nur zur Anzeige; native A2UI-Schaltflächenaktionen werden nur von gebündelten, app-eigenen Seiten akzeptiert.
• Kehren Sie mit canvas.navigate und {"url":""} zum integrierten Scaffold zurück.

​

Beziehung zu Computer Use

​

Canvas eval / Snapshot

openclaw nodes invoke --node "iOS Node" --command canvas.eval --params '{"javaScript":"(() => { const {ctx} = window.__openclaw; ctx.clearRect(0,0,innerWidth,innerHeight); ctx.lineWidth=6; ctx.strokeStyle=\"#ff2d55\"; ctx.beginPath(); ctx.moveTo(40,40); ctx.lineTo(innerWidth-40, innerHeight-40); ctx.stroke(); return \"ok\"; })()"}'

openclaw nodes invoke --node "iOS Node" --command canvas.snapshot --params '{"maxWidth":900,"format":"jpeg"}'

​

Voice Wake + Talk-Modus

• Sprachaktivierung und Sprechmodus sind in den Einstellungen verfügbar.
• OpenAI-Echtzeit-Sprechen verwendet client-eigenes WebRTC, wenn talk.realtime.transport auf webrtc gesetzt ist; eine explizite gateway-relay-Konfiguration bleibt Gateway-eigen. Siehe Sprechmodus.
• Sprechfähige iOS-Knoten geben die talk-Fähigkeit bekannt und können talk.ptt.start, talk.ptt.stop, talk.ptt.cancel und talk.ptt.once deklarieren; der Gateway erlaubt diese Push-to-Talk-Befehle standardmäßig für vertrauenswürdige sprechfähige Knoten.
• iOS kann Hintergrundaudio aussetzen; behandeln Sie Sprachfunktionen als Best-Effort, wenn die App nicht aktiv ist.

​

Häufige Fehler

• NODE_BACKGROUND_UNAVAILABLE: Bringen Sie die iOS-App in den Vordergrund (Canvas-/Kamera-/Bildschirmbefehle erfordern dies).
• A2UI_HOST_UNAVAILABLE: Die gebündelte A2UI-Seite war in der App-WebView nicht erreichbar; lassen Sie die App im Vordergrund auf dem Bildschirm-Tab und versuchen Sie es erneut.
• Kopplungsaufforderung erscheint nie: Führen Sie openclaw devices list aus und genehmigen Sie manuell.
• Erneute Verbindung schlägt nach Neuinstallation fehl: Das Keychain-Kopplungstoken wurde gelöscht; koppeln Sie den Knoten erneut.

​

Verwandte Dokumentation

• Kopplung
• Erkennung
• Bonjour