​

App iOS (Node)

​

Fungsinya

• Terhubung ke Gateway melalui WebSocket (LAN atau tailnet).
• Mengekspos kapabilitas node: Canvas, snapshot layar, pengambilan kamera, Lokasi, mode Talk, Voice wake.
• Menerima command node.invoke dan melaporkan event status node.

​

Persyaratan

• Gateway berjalan di perangkat lain (macOS, Linux, atau Windows melalui WSL2).
• Jalur jaringan:
  • LAN yang sama melalui Bonjour, atau
  • Tailnet melalui DNS-SD unicast (contoh domain: openclaw.internal.), atau
  • Host/port manual (fallback).

​

Quick start (pair + connect)

1. Jalankan Gateway:

openclaw gateway --port 18789

2. Di app iOS, buka Settings dan pilih gateway yang ditemukan (atau aktifkan Manual Host dan masukkan host/port).
3. Setujui permintaan pairing di host gateway:

openclaw devices list
openclaw devices approve <requestId>

4. Verifikasi koneksi:

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

​

Push berbasis relay untuk build resmi

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

• App iOS mendaftar ke relay menggunakan App Attest dan receipt app.
• Relay mengembalikan relay handle opaque plus send grant yang dicakup pendaftaran.
• App iOS mengambil identitas gateway yang telah dipasangkan dan menyertakannya dalam pendaftaran relay, sehingga pendaftaran berbasis relay didelegasikan ke gateway tertentu tersebut.
• App meneruskan pendaftaran berbasis relay itu ke gateway yang dipasangkan dengan push.apns.register.
• Gateway menggunakan relay handle yang tersimpan itu untuk push.test, wake latar belakang, dan wake nudge.
• URL dasar relay gateway harus cocok dengan URL relay yang sudah ditanamkan ke dalam build iOS resmi/TestFlight.
• Jika app kemudian terhubung ke gateway yang berbeda atau build dengan URL dasar relay yang berbeda, app akan me-refresh pendaftaran relay alih-alih menggunakan kembali binding lama.

• Tidak ada token relay untuk seluruh deployment.
• Tidak ada key APNs langsung untuk pengiriman resmi/TestFlight berbasis relay.

1. Instal build iOS resmi/TestFlight.
2. Setel gateway.push.apns.relay.baseUrl pada gateway.
3. Pair app ke gateway dan biarkan koneksi selesai.
4. App memublikasikan push.apns.register secara otomatis setelah memiliki token APNs, sesi operator terhubung, dan pendaftaran relay berhasil.
5. Setelah itu, push.test, reconnect wake, dan wake nudge dapat menggunakan pendaftaran berbasis relay yang tersimpan.

• OPENCLAW_APNS_RELAY_BASE_URL tetap berfungsi sebagai override env sementara untuk gateway.

​

Alur autentikasi dan kepercayaan

• Hanya build iOS OpenClaw asli yang didistribusikan melalui Apple yang dapat menggunakan relay yang di-host.
• Gateway hanya dapat mengirim push berbasis relay untuk perangkat iOS yang dipasangkan dengan gateway tertentu tersebut.

1. app iOS -> gateway
   • App terlebih dahulu melakukan pairing dengan gateway melalui alur auth Gateway normal.
   • Ini memberi app sesi node yang terautentikasi plus sesi operator yang terautentikasi.
   • Sesi operator digunakan untuk memanggil gateway.identity.get.
2. app iOS -> relay
   • App memanggil endpoint pendaftaran relay melalui HTTPS.
   • Pendaftaran mencakup bukti App Attest plus receipt app.
   • Relay memvalidasi bundle ID, bukti App Attest, dan receipt Apple, serta mewajibkan jalur distribusi resmi/produksi.
   • Inilah yang mencegah build Xcode/dev lokal menggunakan relay yang di-host. Build lokal mungkin ditandatangani, tetapi tidak memenuhi bukti distribusi Apple resmi yang diharapkan relay.
3. delegasi identitas gateway
   • Sebelum pendaftaran relay, app mengambil identitas gateway yang dipasangkan dari gateway.identity.get.
   • App menyertakan identitas gateway tersebut dalam payload pendaftaran relay.
   • Relay mengembalikan relay handle dan send grant yang dicakup pendaftaran yang didelegasikan ke identitas gateway tersebut.
4. gateway -> relay
   • Gateway menyimpan relay handle dan send grant dari push.apns.register.
   • Pada push.test, reconnect wake, dan wake nudge, gateway menandatangani permintaan kirim dengan identitas perangkatnya sendiri.
   • Relay memverifikasi baik send grant yang tersimpan maupun tanda tangan gateway terhadap identitas gateway yang didelegasikan dari pendaftaran.
   • Gateway lain tidak dapat menggunakan kembali pendaftaran yang tersimpan itu, bahkan jika entah bagaimana memperoleh handle tersebut.
5. relay -> APNs
   • Relay memiliki kredensial APNs produksi dan token APNs mentah untuk build resmi.
   • Gateway tidak pernah menyimpan token APNs mentah untuk build resmi berbasis relay.
   • Relay mengirim push akhir ke APNs atas nama gateway yang dipasangkan.

• Untuk menjaga kredensial APNs produksi tetap berada di luar gateway pengguna.
• Untuk menghindari penyimpanan token APNs build resmi mentah di gateway.
• Untuk mengizinkan penggunaan relay yang di-host hanya untuk build OpenClaw resmi/TestFlight.
• Untuk mencegah satu gateway mengirim wake push ke perangkat iOS milik gateway lain.

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

​

Jalur discovery

​

Bonjour (LAN)

​

Tailnet (lintas jaringan)

​

Host/port manual

​

Canvas + A2UI

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

• Host canvas Gateway menyajikan /__openclaw__/canvas/ dan /__openclaw__/a2ui/.
• Disajikan dari server HTTP Gateway (port yang sama dengan gateway.port, default 18789).
• Node iOS secara otomatis menavigasi ke A2UI saat terhubung ketika URL host canvas diumumkan.
• Kembali ke scaffold bawaan dengan canvas.navigate dan {"url":""}.

​

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 + mode Talk

• Voice wake dan mode Talk tersedia di Settings.
• iOS dapat menangguhkan audio latar belakang; perlakukan fitur suara sebagai best-effort saat app tidak aktif.

​

Error umum

• NODE_BACKGROUND_UNAVAILABLE: bawa app iOS ke foreground (command canvas/camera/screen memerlukannya).
• A2UI_HOST_NOT_CONFIGURED: Gateway tidak mengumumkan URL host canvas; periksa canvasHost di Konfigurasi Gateway.
• Prompt pairing tidak pernah muncul: jalankan openclaw devices list dan setujui secara manual.
• Reconnect gagal setelah instal ulang: token pairing Keychain telah dihapus; pair ulang node.

​

Dokumen terkait

• Pairing
• Discovery
• Bonjour