iOS アプリ

​

機能

• WebSocket 経由で Gateway に接続します（LAN または tailnet）。
• ノード機能を公開します: Canvas、Screen snapshot、Camera capture、Location、Talk mode、Voice wake。
• node.invoke コマンドを受信し、ノードステータスイベントを報告します。
• Agents サーフェス（Files）から、選択したエージェントのワークスペースを読み取り専用で閲覧します: ディレクトリのドリルダウン、シンタックスハイライト付きテキストプレビュー、画像プレビュー、共有シートへのエクスポート。書き込み操作はありません。プレビューは gateway によってサイズ制限されます。
• ペアリング済み gateway ごとに、最近のチャットセッションとトランスクリプトの小さな読み取り専用オフラインキャッシュを保持します: コールドオープンでは最後に認識されているトランスクリプトを即座に描画し、gateway が応答すると更新します。最近のチャットは切断中も閲覧可能で、リセット/忘れる操作により保護されたローカルキャッシュが消去されます。
• 切断中に送信されたテキストメッセージを、gateway ごとの永続的な送信箱にキューイングします（最大 50 件）: キュー内の吹き出しはトランスクリプトに表示され、再接続時に順番どおり冪等なリトライでフラッシュされ、正規の履歴で送信が確認されるまで永続化され、リトライ/削除アクションを表示する前にバックオフ付きで再試行し、48 時間オフラインの後は送信せず期限切れになります。リセット/忘れる操作では、キャッシュとともにキューもクリアされます。
• 必要に応じてアシスタントメッセージを読み上げます: Chat でメッセージを長押しし、Listen を選択します。アプリは、設定済みの TTS プロバイダーで対応 Gateway の tts.speak クリップを再生し、Gateway 音声が利用できない、または再生できない場合はデバイス上の音声にフォールバックします。セッション切り替えまたはバックグラウンド化で再生は停止します。

​

要件

• 別のデバイス（macOS、Linux、または WSL2 経由の Windows）で Gateway が実行されていること。
• ネットワーク経路:
  • Bonjour 経由の同一 LAN、または
  • ユニキャスト DNS-SD 経由の Tailnet（ドメイン例: openclaw.internal.）、または
  • 手動ホスト/ポート（フォールバック）。

​

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

1. スマートフォンから到達できるルートで、認証済み Gateway を起動します。Tailscale Serve が推奨されるリモート経路です:

openclaw gateway --port 18789 --tailscale serve

2. Control UI を開き、Nodes を選択して、 Devices カードの Pair mobile device をクリックします。
3. iOS アプリで、Settings -> Gateway を開き、QR コードをスキャンする（または セットアップコードを貼り付ける）ことで接続します。 セットアップコードに LAN と Tailscale Serve の両方のルートが含まれている場合、アプリは それらを順番にプローブし、最初に到達可能なエンドポイントを保存します。
4. 公式アプリは自動的に接続します。Devices に保留中の リクエストが表示される場合は、承認前にそのロールとスコープを確認します。

openclaw devices list
openclaw devices approve <requestId>

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

5. 接続を確認します:

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

​

公式ビルドの Relay-backed push

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

• iOS アプリは App Attest と StoreKit app transaction JWS を使用して relay に登録します。
• relay は不透明な relay handle と、登録スコープの send grant を返します。
• iOS アプリはペアリング済み gateway identity（gateway.identity.get）を取得し、relay 登録に含めるため、relay-backed registration はその特定の gateway に委任されます。
• アプリはその relay-backed registration を push.apns.register でペアリング済み gateway に転送します。
• gateway は保存された relay handle を push.test、バックグラウンドウェイク、wake nudges に使用します。
• アプリが後で別の gateway または異なる relay base URL のビルドに接続した場合、古いバインディングを再利用せず relay 登録を更新します。

1. 公式 iOS アプリをインストールします。
2. 任意: 意図的に分離されたカスタム relay ビルドを使用している場合にのみ、gateway に gateway.push.apns.relay.baseUrl を設定します。
3. アプリを gateway にペアリングし、接続完了まで待ちます。
4. アプリは APNs token を取得し、operator session が接続され、relay 登録が成功すると、push.apns.register を公開します。
5. その後、push.test、再接続ウェイク、wake nudges は保存済みの relay-backed registration を使用できます。

​

バックグラウンド alive ビーコン

• OPENCLAW_APNS_RELAY_BASE_URL は、gateway の一時的な env override として引き続き機能します（gateway.push.apns.relay.baseUrl が config-first の経路です）。
• App Store リリースビルドの push mode はホスト型 relay host をハードコードしており、relay-URL override を決して読み取りません。OPENCLAW_PUSH_RELAY_BASE_URL build-time env var は、local/sandbox iOS build modes にのみ影響します。

​

認証と信頼フロー

• Apple を通じて配布された正規の OpenClaw iOS ビルドだけが、ホスト型 relay を使用できます。
• gateway は、その特定の gateway とペアリングした iOS デバイスに対してのみ relay-backed push を送信できます。

1. iOS app -> gateway: アプリは通常の Gateway auth flow を通じて gateway とペアリングし、認証済みノードセッションと認証済みオペレーターセッションを取得します。オペレーターセッションは gateway.identity.get を呼び出します。
2. iOS app -> relay: アプリは App Attest proof と StoreKit app transaction JWS を使用し、HTTPS 経由で relay registration endpoints を呼び出します。relay は bundle ID、App Attest proof、Apple distribution proof を検証し、official/production distribution path を要求します。これにより、local Xcode/dev builds は official Apple distribution proof を満たせないため、hosted relay を使用できません。
3. gateway identity delegation: relay 登録の前に、アプリは gateway.identity.get からペアリング済み gateway identity を取得し、relay registration payload に含めます。relay は、その gateway identity に委任された relay handle と registration-scoped send grant を返します。
4. gateway -> relay: gateway は push.apns.register から relay handle と send grant を保存します。push.test、再接続ウェイク、wake nudges では、gateway が自身の device identity で送信リクエストに署名します。relay は、保存された send grant と gateway signature の両方を、登録時に委任された gateway identity に照らして検証します。別の gateway は、たとえ何らかの方法で handle を取得したとしても、その保存済み登録を再利用できません。
5. relay -> APNs: relay は production APNs credentials と公式ビルド用の raw APNs token を所有します。gateway は relay-backed 公式ビルドの raw APNs token を保存しません。relay はペアリング済み gateway に代わって最終的な push を APNs に送信します。

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（クロスネットワーク）

​

手動ホスト/ポート

​

複数の gateway

• 設定 -> Gateway には、アクティブなGatewayがマークされた ペアリング済みGateway リストが表示されます。項目をタップすると切り替わります。アプリは現在のセッションを終了し、選択したGatewayへ再接続します。複数のGatewayがペアリングされている場合、接続行の横にクイック切り替えメニューが表示されます。
• 認証情報、TLS 信頼判断、Gatewayごとの設定、キャッシュされたチャット履歴はGatewayごとに保存されます。切り替えてもGateway間で状態が混ざることはなく、プッシュ登録はアクティブなGatewayに従います。
• ペアリング済みGatewayをスワイプするか、コンテキストメニューを使用して 忘れる を選択すると、その認証情報、デバイストークン、TLS ピン、キャッシュされたチャットが削除されます。
• 検出されたGatewayへ切り替えるには、そのGatewayがネットワーク上で見えている必要があります。手動Gatewayは保存済みのホストとポートで再接続します。

​

Canvas + A2UI

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

• Gateway canvas ホストは、Gateway HTTP サーバー（gateway.port と同じポート、デフォルトは 18789）から /__openclaw__/canvas/ と /__openclaw__/a2ui/ を提供します。
• iOS ノードは、接続時のデフォルトビューとして組み込みスキャフォールドを保持します。canvas.a2ui.push と canvas.a2ui.reset は、バンドルされたアプリ所有の A2UI ページを使用します。
• リモートGateway A2UI ページは iOS ではレンダリング専用です。ネイティブ A2UI ボタンアクションは、バンドルされたアプリ所有ページからのものだけが受け付けられます。
• 組み込みスキャフォールドに戻るには、canvas.navigate と {"url":""} を使用します。

​

Computer Use との関係

​

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

​

音声ウェイク + talk モード

• 音声ウェイクと talk モードは設定で利用できます。
• OpenAI realtime Talk は、talk.realtime.transport が webrtc の場合、クライアント所有の WebRTC を使用します。明示的な gateway-relay 設定は引き続きGateway所有です。Talk モードを参照してください。
• Talk 対応 iOS ノードは talk capability を公開し、talk.ptt.start、talk.ptt.stop、talk.ptt.cancel、talk.ptt.once を宣言できます。Gateway は、信頼された Talk 対応ノードに対して、これらのプッシュツートークコマンドをデフォルトで許可します。
• iOS はバックグラウンド音声を一時停止する場合があります。アプリがアクティブでない場合、音声機能はベストエフォートとして扱ってください。

​

よくあるエラー

• NODE_BACKGROUND_UNAVAILABLE: iOS アプリをフォアグラウンドにしてください（canvas/camera/screen コマンドにはこれが必要です）。
• A2UI_HOST_UNAVAILABLE: バンドルされた A2UI ページにアプリの WebView から到達できませんでした。アプリを Screen タブでフォアグラウンドにしたまま再試行してください。
• ペアリングプロンプトが表示されない: openclaw devices list を実行し、手動で承認してください。
• Watch に iPhone の状態が表示されない: watch.status で iPhone が watchPaired: true および watchAppInstalled: true を報告していることを確認してください。ペアリングが false の場合は、Apple の Watch アプリで Watch をペアリングしてください。インストールが false の場合は、My Watch -> Available Apps からコンパニオンをインストールしてください。どちらかを変更した後、Watch で OpenClaw を一度開いてください。即時到達性には引き続き両方のアプリが実行中である必要がありますが、 キューに入った更新は後でバックグラウンドで届く場合があります。
• 再インストール後に再接続に失敗する: Keychain のペアリングトークンがクリアされています。ノードを再ペアリングしてください。

​

関連ドキュメント

• ペアリング
• 検出
• Bonjour