​

Aplikasi iOS (Node)

​

Yang dilakukannya

• Terhubung ke Gateway melalui WebSocket (LAN atau tailnet).
• Mengekspos capability node: Canvas, snapshot layar, tangkapan kamera, lokasi, mode bicara, voice wake.
• Menerima perintah 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 unicast DNS-SD (contoh domain: openclaw.internal.), atau
  • Host/port manual (fallback).

​

Mulai cepat (pair + connect)

1. Jalankan Gateway:

openclaw gateway --port 18789

2. Di aplikasi 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",
        },
      },
    },
  },
}

• Aplikasi iOS mendaftar ke relay menggunakan App Attest dan receipt aplikasi.
• Relay mengembalikan handle relay opak plus grant pengiriman yang dicakup ke registrasi.
• Aplikasi iOS mengambil identitas gateway yang di-pair dan menyertakannya dalam registrasi relay, sehingga registrasi berbasis relay didelegasikan ke gateway spesifik tersebut.
• Aplikasi meneruskan registrasi berbasis relay itu ke gateway yang di-pair dengan push.apns.register.
• Gateway menggunakan handle relay yang tersimpan itu untuk push.test, wake latar belakang, dan wake nudge.
• Base URL relay gateway harus cocok dengan URL relay yang ditanamkan ke dalam build iOS resmi/TestFlight.
• Jika aplikasi kemudian terhubung ke gateway lain atau build dengan base URL relay yang berbeda, aplikasi akan me-refresh registrasi relay alih-alih menggunakan ulang binding lama.

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

1. Instal build iOS resmi/TestFlight.
2. Setel gateway.push.apns.relay.baseUrl pada gateway.
3. Pair aplikasi ke gateway dan biarkan aplikasi menyelesaikan koneksinya.
4. Aplikasi menerbitkan push.apns.register secara otomatis setelah memiliki token APNs, sesi operator terhubung, dan registrasi relay berhasil.
5. Setelah itu, push.test, reconnect wake, dan wake nudge dapat menggunakan registrasi berbasis relay yang tersimpan.

• OPENCLAW_APNS_RELAY_BASE_URL masih 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 melakukan pairing dengan gateway spesifik tersebut.

1. iOS app -> gateway
   • Aplikasi pertama-tama melakukan pairing dengan gateway melalui alur auth Gateway normal.
   • Ini memberi aplikasi sesi node yang terautentikasi plus sesi operator yang terautentikasi.
   • Sesi operator digunakan untuk memanggil gateway.identity.get.
2. iOS app -> relay
   • Aplikasi memanggil endpoint registrasi relay melalui HTTPS.
   • Registrasi mencakup proof App Attest plus receipt aplikasi.
   • Relay memvalidasi bundle ID, proof App Attest, dan receipt Apple, serta mewajibkan jalur distribusi resmi/produksi.
   • Inilah yang memblokir build Xcode/dev lokal agar tidak dapat menggunakan relay yang di-host. Build lokal bisa saja ditandatangani, tetapi tidak memenuhi proof distribusi Apple resmi yang diharapkan relay.
3. gateway identity delegation
   • Sebelum registrasi relay, aplikasi mengambil identitas gateway yang di-pair dari gateway.identity.get.
   • Aplikasi menyertakan identitas gateway itu dalam payload registrasi relay.
   • Relay mengembalikan handle relay dan grant pengiriman yang dicakup ke registrasi yang didelegasikan ke identitas gateway tersebut.
4. gateway -> relay
   • Gateway menyimpan handle relay dan grant pengiriman dari push.apns.register.
   • Pada push.test, reconnect wake, dan wake nudge, gateway menandatangani permintaan kirim dengan identitas perangkatnya sendiri.
   • Relay memverifikasi baik grant pengiriman yang tersimpan maupun tanda tangan gateway terhadap identitas gateway yang didelegasikan dari registrasi.
   • Gateway lain tidak dapat menggunakan ulang registrasi yang tersimpan itu, meskipun somehow 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 di-pair.

• Untuk menjaga kredensial APNs produksi tetap 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 yang dimiliki 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)"

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"

​

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 otomatis bernavigasi ke A2UI saat connect 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 bicara

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

​

Error umum

• NODE_BACKGROUND_UNAVAILABLE: bawa aplikasi iOS ke foreground (perintah canvas/kamera/layar 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