​

iOSアプリ（ノード）

​

できること

• WebSocket経由でGatewayに接続する（LANまたはtailnet）。
• ノード機能を提供する: Canvas、画面スナップショット、カメラキャプチャ、位置情報、Talk mode、Voice wake。
• node.invoke コマンドを受信し、ノード状態イベントを報告する。

​

要件

• 別のデバイス上で動作しているGateway（macOS、Linux、またはWSL2経由のWindows）。
• ネットワーク経路:
  • 同じLAN上でBonjourを使用、または
  • ユニキャストDNS-SD経由のtailnet（ドメイン例: openclaw.internal.）、または
  • 手動のホスト/ポート指定（フォールバック）。

​

クイックスタート（ペアリング + 接続）

1. Gatewayを起動します:

openclaw gateway --port 18789

2. iOSアプリでSettingsを開き、検出されたgatewayを選択します（またはManual Hostを有効にしてhost/portを入力します）。
3. Gatewayホスト上でペアリングリクエストを承認します:

openclaw devices list
openclaw devices approve <requestId>

4. 接続を確認します:

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

​

公式ビルド向けのrelayベースpush

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

• iOSアプリはApp Attestとアプリレシートを使用してrelayに登録します。
• relayは、不透明なrelay handleと、登録スコープのsend grantを返します。
• iOSアプリはペアリング済みgateway identityを取得し、それをrelay登録に含めることで、そのrelayベース登録をその特定のgatewayに委譲します。
• アプリは、そのrelayベース登録を push.apns.register でペアリング済みGatewayへ転送します。
• Gatewayは、push.test、バックグラウンドwake、wake nudgeに対して、その保存されたrelay handleを使用します。
• Gateway relay base URLは、公式/TestFlight iOSビルドに組み込まれたrelay URLと一致している必要があります。
• 後でアプリが別のGatewayや、異なるrelay base URLを持つビルドに接続した場合、古い紐付けを再利用するのではなく、relay登録を更新します。

• デプロイ全体で共通のrelayトークンは不要。
• 公式/TestFlightのrelayベース送信に直接のAPNsキーは不要。

1. 公式/TestFlight iOSビルドをインストールします。
2. gatewayで gateway.push.apns.relay.baseUrl を設定します。
3. アプリをgatewayにペアリングし、接続完了まで待ちます。
4. APNsトークンがあり、operatorセッションが接続済みで、relay登録が成功した後、アプリは自動的に push.apns.register を公開します。
5. その後、push.test、再接続wake、wake nudgeで、保存されたrelayベース登録を使用できます。

• OPENCLAW_APNS_RELAY_BASE_URL は、gatewayの一時的なenvオーバーライドとして引き続き使用できます。

​

認証と信頼のフロー

• Apple経由で配布された真正なOpenClaw iOSビルドだけがホスト型relayを使用できる。
• Gatewayは、その特定の gatewayとペアリングしたiOSデバイスに対してのみrelayベースpushを送信できる。

1. iOS app -> gateway
   • アプリはまず通常のGateway認証フローを通じてgatewayとペアリングします。
   • これにより、アプリは認証済みノードセッションと認証済みoperatorセッションを取得します。
   • operatorセッションは gateway.identity.get の呼び出しに使用されます。
2. iOS app -> relay
   • アプリはHTTPS経由でrelay登録エンドポイントを呼び出します。
   • 登録にはApp Attestの証明とアプリレシートが含まれます。
   • relayはbundle ID、App Attest証明、Appleレシートを検証し、 公式/本番の配布経路を要求します。
   • これにより、ローカルのXcode/devビルドはホスト型relayを使用できません。ローカルビルドは 署名されている場合がありますが、relayが要求する公式なApple配布証明を満たしません。
3. gateway identity delegation
   • relay登録前に、アプリは gateway.identity.get からペアリング済みgateway identityを取得します。
   • アプリはそのgateway identityをrelay登録ペイロードに含めます。
   • relayは、そのgateway identityに委譲されたrelay handleと登録スコープのsend grantを返します。
4. gateway -> relay
   • Gatewayは、push.apns.register からrelay handleとsend grantを保存します。
   • push.test、再接続wake、wake nudgeでは、Gatewayは 自身のdevice identityで送信リクエストに署名します。
   • relayは、保存済みsend grantとGateway署名の両方を、登録時に委譲された gateway identityに対して検証します。
   • たとえ別のGatewayがそのhandleを何らかの形で取得したとしても、その保存済み登録を再利用することはできません。
5. relay -> APNs
   • relayは、本番APNs認証情報と、公式ビルド用の生のAPNsトークンを保持します。
   • Gatewayは、relayベースの公式ビルドに対して生のAPNsトークンを保存しません。
   • relayは、ペアリング済みGatewayを代理して最終的なpushをAPNsへ送信します。

• 本番APNs認証情報をユーザーのgatewayから切り離すため。
• 公式ビルドの生のAPNsトークンをgatewayに保存しないようにするため。
• 公式/TestFlightのOpenClawビルドに対してのみホスト型relay利用を許可するため。
• あるgatewayが、別のgatewayに属するiOSデバイスへwake pushを送れないようにするため。

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"

​

検出経路

​

Bonjour（LAN）

​

tailnet（ネットワークをまたぐ場合）

​

手動host/port

​

Canvas + A2UI

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

• Gateway canvas hostは /__openclaw__/canvas/ と /__openclaw__/a2ui/ を提供します。
• これはGateway HTTPサーバーから配信されます（gateway.port と同じポート。デフォルト 18789）。
• iOSノードは、canvas host URLが通知されると接続時に自動でA2UIへ移動します。
• canvas.navigate と {"url":""} で組み込みscaffoldに戻れます。

​

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とTalk modeはSettingsで利用できます。
• iOSではバックグラウンド音声が中断される場合があるため、アプリがアクティブでないときの音声機能はベストエフォートとして扱ってください。

​

よくあるエラー

• NODE_BACKGROUND_UNAVAILABLE: iOSアプリをフォアグラウンドにしてください（canvas/camera/screenコマンドには必要です）。
• A2UI_HOST_NOT_CONFIGURED: Gatewayがcanvas host URLを通知していません。 Gateway configuration の canvasHost を確認してください。
• ペアリングプロンプトが表示されない: openclaw devices list を実行して手動で承認してください。
• 再インストール後に再接続できない: Keychainのペアリングトークンが消去されています。ノードを再ペアリングしてください。

​

関連ドキュメント

• Pairing
• Discovery
• Bonjour