​

iOS-App (Node)

​

Was sie macht

• Verbindet sich über WebSocket mit einem Gateway (LAN oder Tailnet).
• Stellt Node-Fähigkeiten bereit: Canvas, Bildschirm-Snapshot, Kameraaufnahme, Standort, Talk mode, Voice wake.
• Empfängt node.invoke-Befehle und meldet Node-Statusereignisse.

​

Anforderungen

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

​

Schnellstart (Pairing + Verbinden)

1. Starten Sie das Gateway:

openclaw gateway --port 18789

2. Öffnen Sie in der iOS-App die Einstellungen und wählen Sie ein erkanntes Gateway aus (oder aktivieren Sie Manual Host und geben Sie Host/Port ein).
3. Genehmigen Sie die Pairing-Anfrage auf dem Gateway-Host:

openclaw devices list
openclaw devices approve <requestId>

4. Verbindung prü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 mit App Attest und dem App-Receipt beim Relay.
• Das Relay gibt einen undurchsichtigen Relay-Handle zusammen mit einer registrierungsspezifischen Sendeberechtigung zurück.
• Die iOS-App ruft die Identität des gepaarten Gateways ab und schließt sie in die Relay-Registrierung ein, sodass die Relay-gestützte Registrierung an genau dieses Gateway delegiert wird.
• Die App leitet diese Relay-gestützte Registrierung mit push.apns.register an das gepaarte Gateway weiter.
• Das Gateway verwendet diesen gespeicherten Relay-Handle für push.test, Hintergrund-Weckvorgänge und Wake-Nudges.
• Die Relay-Basis-URL des Gateways muss mit der Relay-URL übereinstimmen, die in das offizielle/TestFlight-iOS-Build eingebettet ist.
• Wenn sich die App später mit einem anderen Gateway oder mit einem Build mit anderer Relay-Basis-URL verbindet, aktualisiert sie die Relay-Registrierung, anstatt die alte Bindung wiederzuverwenden.

• Kein Relay-Token für die gesamte Bereitstellung.
• Keinen direkten APNs-Schlüssel für Relay-gestützte Sendungen offizieller/TestFlight-Builds.

1. Installieren Sie das offizielle/TestFlight-iOS-Build.
2. Setzen Sie gateway.push.apns.relay.baseUrl auf dem Gateway.
3. Pairen Sie die App mit dem Gateway und lassen Sie sie die Verbindung vollständig herstellen.
4. Die App veröffentlicht push.apns.register automatisch, nachdem sie einen APNs-Token hat, die Operatorsitzung verbunden ist und die Relay-Registrierung erfolgreich war.
5. Danach können push.test, Reconnect-Weckvorgänge und Wake-Nudges die gespeicherte Relay-gestützte Registrierung verwenden.

• OPENCLAW_APNS_RELAY_BASE_URL funktioniert weiterhin als temporäre Umgebungsvariablen-Überschreibung für das Gateway.

​

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 genau diesem Gateway gepaart wurden.

1. iOS app -> gateway
   • Die App paart sich zuerst über den normalen Gateway-Authentifizierungsablauf mit dem Gateway.
   • Dadurch erhält die App eine authentifizierte Node-Sitzung sowie eine authentifizierte Operatorsitzung.
   • Die Operatorsitzung wird verwendet, um gateway.identity.get aufzurufen.
2. iOS app -> relay
   • Die App ruft die Relay-Registrierungsendpunkte über HTTPS auf.
   • Die Registrierung enthält App-Attest-Nachweis und den App-Receipt.
   • Das Relay validiert die Bundle-ID, den App-Attest-Nachweis und den Apple-Receipt und verlangt den offiziellen/produktiven Verteilungspfad.
   • Dadurch wird verhindert, dass lokale Xcode-/Dev-Builds das gehostete Relay verwenden. Ein lokales Build kann zwar signiert sein, erfüllt aber nicht den Nachweis der offiziellen Apple-Verteilung, den das Relay erwartet.
3. gateway identity delegation
   • Vor der Relay-Registrierung ruft die App die Identität des gepaarten Gateways über gateway.identity.get ab.
   • Die App schließt diese Gateway-Identität in die Relay-Registrierungsnutzlast ein.
   • Das Relay gibt einen Relay-Handle und eine registrierungsspezifische Sendeberechtigung zurück, die an diese Gateway-Identität delegiert sind.
4. gateway -> relay
   • Das Gateway speichert den Relay-Handle und die Sendeberechtigung aus push.apns.register.
   • Bei push.test, Reconnect-Weckvorgängen und Wake-Nudges signiert das Gateway die Sendeanfrage mit seiner eigenen Geräteidentität.
   • Das Relay verifiziert sowohl die gespeicherte Sendeberechtigung als auch die Gateway-Signatur gegenüber der delegierten Gateway-Identität aus der Registrierung.
   • Ein anderes Gateway kann diese gespeicherte Registrierung nicht wiederverwenden, selbst wenn es irgendwie an den Handle gelangt.
5. relay -> APNs
   • Das Relay besitzt die produktiven APNs-Anmeldedaten und den rohen APNs-Token für das offizielle Build.
   • Das Gateway speichert für offizielle Relay-gestützte Builds niemals den rohen APNs-Token.
   • Das Relay sendet den finalen Push im Namen des gepaarten Gateways an APNs.

• Damit produktive APNs-Anmeldedaten nicht in Benutzer-Gateways landen.
• Um zu vermeiden, dass rohe APNs-Tokens offizieller Builds im Gateway gespeichert werden.
• Damit das gehostete Relay nur von offiziellen/TestFlight-OpenClaw-Builds verwendet werden kann.
• Um zu verhindern, dass ein Gateway Weck-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"

​

Erkennungspfade

​

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 Canvas-Host des Gateways stellt /__openclaw__/canvas/ und /__openclaw__/a2ui/ bereit.
• Er wird vom HTTP-Server des Gateways bereitgestellt (derselbe Port wie gateway.port, Standard 18789).
• Der iOS-Node navigiert beim Verbinden automatisch zu A2UI, wenn eine Canvas-Host-URL angekündigt wird.
• Kehren Sie mit canvas.navigate und {"url":""} zum integrierten Gerüst zurück.

​

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 mode

• Voice wake und Talk mode sind in den Einstellungen verfügbar.
• iOS kann Audio im Hintergrund anhalten; behandeln Sie Voice-Funktionen 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_NOT_CONFIGURED: Das Gateway hat keine Canvas-Host-URL angekündigt; prüfen Sie canvasHost in Gateway configuration.
• Pairing-Aufforderung erscheint nie: Führen Sie openclaw devices list aus und genehmigen Sie manuell.
• Reconnect schlägt nach einer Neuinstallation fehl: Das Pairing-Token im Keychain wurde gelöscht; pairen Sie den Node erneut.

​

Verwandte Dokumente

• Pairing
• Erkennung
• Bonjour