Application iOS

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Ce qu’elle fait

• Se connecte à un Gateway via WebSocket (LAN ou tailnet).
• Expose les capacités du Node : Canvas, instantané d’écran, capture caméra, localisation, mode Talk, réveil vocal.
• Reçoit les commandes node.invoke et signale les événements d’état du Node.

​

Prérequis

• Gateway exécuté sur un autre appareil (macOS, Linux ou Windows via WSL2).
• Chemin réseau :
  • Même LAN via Bonjour, ou
  • Tailnet via DNS-SD unicast (domaine d’exemple : openclaw.internal.), ou
  • Hôte/port manuel (solution de repli).

​

Démarrage rapide (apparier + connecter)

1. Démarrez le Gateway :

openclaw gateway --port 18789

2. Dans l’app iOS, ouvrez Réglages et choisissez un gateway découvert (ou activez Hôte manuel et saisissez l’hôte/le port).
3. Approuvez la demande d’appariement sur l’hôte du gateway :

openclaw devices list
openclaw devices approve <requestId>

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

4. Vérifiez la connexion :

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

​

Push adossé au relais pour les builds officiels

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

• L’app iOS s’enregistre auprès du relais avec App Attest et un JWS de transaction d’app StoreKit.
• Le relais renvoie un handle de relais opaque ainsi qu’une autorisation d’envoi limitée à l’enregistrement.
• L’app iOS récupère l’identité du gateway apparié et l’inclut dans l’enregistrement du relais, afin que l’enregistrement adossé au relais soit délégué à ce gateway précis.
• L’app transmet cet enregistrement adossé au relais au gateway apparié avec push.apns.register.
• Le gateway utilise ce handle de relais stocké pour push.test, les réveils en arrière-plan et les impulsions de réveil.
• L’URL de base du relais du gateway doit correspondre à l’URL de relais intégrée dans le build iOS officiel/TestFlight.
• Si l’app se connecte ensuite à un autre gateway ou à un build avec une URL de base de relais différente, elle actualise l’enregistrement du relais au lieu de réutiliser l’ancienne liaison.

• Aucun token de relais à l’échelle du déploiement.
• Aucune clé APNs directe pour les envois officiels/TestFlight adossés au relais.

1. Installez le build iOS officiel/TestFlight.
2. Définissez gateway.push.apns.relay.baseUrl sur le gateway.
3. Appariez l’app au gateway et laissez-la terminer la connexion.
4. L’app publie automatiquement push.apns.register après avoir obtenu un token APNs, lorsque la session opérateur est connectée et que l’enregistrement du relais réussit.
5. Ensuite, push.test, les réveils de reconnexion et les impulsions de réveil peuvent utiliser l’enregistrement adossé au relais stocké.

​

Signaux de présence en arrière-plan

• OPENCLAW_APNS_RELAY_BASE_URL fonctionne toujours comme surcharge temporaire d’environnement pour le gateway.

​

Flux d’authentification et de confiance

• Seuls les builds iOS OpenClaw authentiques distribués via Apple peuvent utiliser le relais hébergé.
• Un gateway ne peut envoyer des pushs adossés au relais que pour les appareils iOS appariés avec ce gateway précis.

1. iOS app -> gateway
   • L’app s’apparie d’abord avec le gateway via le flux d’authentification Gateway normal.
   • Cela donne à l’app une session Node authentifiée ainsi qu’une session opérateur authentifiée.
   • La session opérateur est utilisée pour appeler gateway.identity.get.
2. iOS app -> relay
   • L’app appelle les points de terminaison d’enregistrement du relais via HTTPS.
   • L’enregistrement inclut une preuve App Attest ainsi qu’un JWS de transaction d’app StoreKit.
   • Le relais valide l’identifiant de bundle, la preuve App Attest et la preuve de distribution Apple, et exige le chemin de distribution officiel/production.
   • C’est ce qui empêche les builds Xcode/dev locaux d’utiliser le relais hébergé. Un build local peut être signé, mais il ne satisfait pas la preuve de distribution Apple officielle attendue par le relais.
3. gateway identity delegation
   • Avant l’enregistrement du relais, l’app récupère l’identité du gateway apparié depuis gateway.identity.get.
   • L’app inclut cette identité de gateway dans la charge utile d’enregistrement du relais.
   • Le relais renvoie un handle de relais et une autorisation d’envoi limitée à l’enregistrement, délégués à cette identité de gateway.
4. gateway -> relay
   • Le gateway stocke le handle de relais et l’autorisation d’envoi provenant de push.apns.register.
   • Lors de push.test, des réveils de reconnexion et des impulsions de réveil, le gateway signe la demande d’envoi avec sa propre identité d’appareil.
   • Le relais vérifie à la fois l’autorisation d’envoi stockée et la signature du gateway par rapport à l’identité de gateway déléguée lors de l’enregistrement.
   • Un autre gateway ne peut pas réutiliser cet enregistrement stocké, même s’il obtient le handle d’une quelconque manière.
5. relay -> APNs
   • Le relais possède les identifiants APNs de production et le token APNs brut pour le build officiel.
   • Le gateway ne stocke jamais le token APNs brut pour les builds officiels adossés au relais.
   • Le relais envoie le push final à APNs pour le compte du gateway apparié.

• Pour garder les identifiants APNs de production hors des gateways utilisateur.
• Pour éviter de stocker les tokens APNs bruts des builds officiels sur le gateway.
• Pour n’autoriser l’utilisation du relais hébergé qu’aux builds OpenClaw officiels/TestFlight.
• Pour empêcher un gateway d’envoyer des pushs de réveil à des appareils iOS appartenant à un autre gateway.

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"

​

Chemins de découverte

​

Bonjour (LAN)

​

Tailnet (inter-réseaux)

​

Hôte/port manuel

​

Canvas + A2UI

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

• L’hôte Canvas du Gateway sert /__openclaw__/canvas/ et /__openclaw__/a2ui/.
• Il est servi depuis le serveur HTTP du Gateway (même port que gateway.port, 18789 par défaut).
• Le Node iOS navigue automatiquement vers A2UI à la connexion lorsqu’une URL d’hôte Canvas est annoncée.
• Revenez à l’échafaudage intégré avec canvas.navigate et {"url":""}.

​

Relation avec Computer Use

​

Évaluation / instantané Canvas

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"}'

​

Réveil vocal + mode Talk

• Le réveil vocal et le mode Talk sont disponibles dans Réglages.
• Les Nodes iOS compatibles Talk annoncent la capacité talk et peuvent déclarer talk.ptt.start, talk.ptt.stop, talk.ptt.cancel et talk.ptt.once ; le Gateway autorise par défaut ces commandes push-to-talk pour les Nodes compatibles Talk et approuvés.
• iOS peut suspendre l’audio en arrière-plan ; considérez les fonctionnalités vocales comme fonctionnant au mieux lorsque l’app n’est pas active.

​

Erreurs courantes

• NODE_BACKGROUND_UNAVAILABLE : mettez l’app iOS au premier plan (les commandes canvas/camera/screen l’exigent).
• A2UI_HOST_NOT_CONFIGURED : le Gateway n’a pas annoncé l’URL de surface du Plugin Canvas ; vérifiez plugins.entries.canvas.config.host dans la configuration du Gateway.
• L’invite d’appariement n’apparaît jamais : exécutez openclaw devices list et approuvez manuellement.
• La reconnexion échoue après réinstallation : le token d’appariement Keychain a été effacé ; appariez à nouveau le Node.

​

Documentation associée

• Appariement
• Découverte
• Bonjour