Ứng dụng 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.

​

Chức năng

• Kết nối tới Gateway qua WebSocket (LAN hoặc tailnet).
• Cung cấp các khả năng của Node: Canvas, ảnh chụp màn hình, chụp Camera, Vị trí, chế độ Talk, đánh thức bằng giọng nói.
• Nhận lệnh node.invoke và báo cáo các sự kiện trạng thái Node.

​

Yêu cầu

• Gateway đang chạy trên một thiết bị khác (macOS, Linux hoặc Windows qua WSL2).
• Đường mạng:
  • Cùng LAN qua Bonjour, hoặc
  • Tailnet qua unicast DNS-SD (miền ví dụ: openclaw.internal.), hoặc
  • Máy chủ/cổng thủ công (dự phòng).

​

Bắt đầu nhanh (ghép nối + kết nối)

1. Khởi động Gateway:

openclaw gateway --port 18789

2. Trong ứng dụng iOS, mở Cài đặt và chọn một Gateway đã được phát hiện (hoặc bật Máy chủ thủ công và nhập máy chủ/cổng).
3. Phê duyệt yêu cầu ghép nối trên máy chủ Gateway:

openclaw devices list
openclaw devices approve <requestId>

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

4. Xác minh kết nối:

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

​

Push dựa trên relay cho bản dựng chính thức

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

• Ứng dụng iOS đăng ký với relay bằng App Attest và JWS giao dịch ứng dụng StoreKit.
• Relay trả về một định danh relay mờ cùng quyền gửi giới hạn theo đăng ký.
• Ứng dụng iOS lấy danh tính Gateway đã ghép nối và đưa nó vào đăng ký relay, vì vậy đăng ký dựa trên relay được ủy quyền cho Gateway cụ thể đó.
• Ứng dụng chuyển tiếp đăng ký dựa trên relay đó tới Gateway đã ghép nối bằng push.apns.register.
• Gateway dùng định danh relay đã lưu đó cho push.test, đánh thức nền và nhắc đánh thức.
• URL cơ sở relay của Gateway phải khớp với URL relay được nhúng trong bản dựng iOS chính thức/TestFlight.
• Nếu sau đó ứng dụng kết nối tới Gateway khác hoặc một bản dựng có URL cơ sở relay khác, nó sẽ làm mới đăng ký relay thay vì tái sử dụng liên kết cũ.

• Không cần token relay dùng chung cho toàn bộ triển khai.
• Không cần khóa APNs trực tiếp cho các lượt gửi dựa trên relay của bản chính thức/TestFlight.

1. Cài đặt bản dựng iOS chính thức/TestFlight.
2. Đặt gateway.push.apns.relay.baseUrl trên Gateway.
3. Ghép nối ứng dụng với Gateway và để ứng dụng hoàn tất kết nối.
4. Ứng dụng tự động công bố push.apns.register sau khi có token APNs, phiên operator đã kết nối và đăng ký relay thành công.
5. Sau đó, push.test, đánh thức kết nối lại và nhắc đánh thức có thể dùng đăng ký dựa trên relay đã lưu.

​

Tín hiệu alive trong nền

• OPENCLAW_APNS_RELAY_BASE_URL vẫn hoạt động như một biến môi trường ghi đè tạm thời cho Gateway.

​

Luồng xác thực và tin cậy

• Chỉ các bản dựng iOS OpenClaw chính hãng được phân phối qua Apple mới có thể dùng relay lưu trữ.
• Một Gateway chỉ có thể gửi push dựa trên relay cho các thiết bị iOS đã ghép nối với chính Gateway đó.

1. iOS app -> gateway
   • Ứng dụng trước tiên ghép nối với Gateway qua luồng xác thực Gateway thông thường.
   • Việc đó cấp cho ứng dụng một phiên Node đã xác thực cùng một phiên operator đã xác thực.
   • Phiên operator được dùng để gọi gateway.identity.get.
2. iOS app -> relay
   • Ứng dụng gọi các endpoint đăng ký relay qua HTTPS.
   • Đăng ký bao gồm bằng chứng App Attest cùng một JWS giao dịch ứng dụng StoreKit.
   • Relay xác thực ID gói, bằng chứng App Attest và bằng chứng phân phối Apple, đồng thời yêu cầu đường dẫn phân phối chính thức/sản xuất.
   • Đây là cơ chế chặn các bản dựng Xcode/dev cục bộ dùng relay lưu trữ. Một bản dựng cục bộ có thể được ký, nhưng nó không đáp ứng bằng chứng phân phối Apple chính thức mà relay mong đợi.
3. gateway identity delegation
   • Trước khi đăng ký relay, ứng dụng lấy danh tính Gateway đã ghép nối từ gateway.identity.get.
   • Ứng dụng đưa danh tính Gateway đó vào payload đăng ký relay.
   • Relay trả về một định danh relay và một quyền gửi giới hạn theo đăng ký được ủy quyền cho danh tính Gateway đó.
4. gateway -> relay
   • Gateway lưu định danh relay và quyền gửi từ push.apns.register.
   • Khi push.test, đánh thức kết nối lại và nhắc đánh thức, Gateway ký yêu cầu gửi bằng danh tính thiết bị của chính nó.
   • Relay xác minh cả quyền gửi đã lưu và chữ ký Gateway đối chiếu với danh tính Gateway được ủy quyền từ đăng ký.
   • Gateway khác không thể tái sử dụng đăng ký đã lưu đó, ngay cả khi bằng cách nào đó lấy được định danh.
5. relay -> APNs
   • Relay sở hữu thông tin xác thực APNs sản xuất và token APNs thô cho bản dựng chính thức.
   • Gateway không bao giờ lưu token APNs thô cho các bản dựng chính thức dựa trên relay.
   • Relay gửi push cuối cùng tới APNs thay mặt Gateway đã ghép nối.

• Để giữ thông tin xác thực APNs sản xuất khỏi các Gateway của người dùng.
• Để tránh lưu token APNs thô của bản dựng chính thức trên Gateway.
• Để chỉ cho phép dùng relay lưu trữ với các bản dựng OpenClaw chính thức/TestFlight.
• Để ngăn một Gateway gửi push đánh thức tới thiết bị iOS thuộc một Gateway khác.

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"

​

Đường dẫn phát hiện

​

Bonjour (LAN)

​

Tailnet (xuyên mạng)

​

Máy chủ/cổng thủ công

​

Canvas + A2UI

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

• Máy chủ canvas của Gateway phục vụ /__openclaw__/canvas/ và /__openclaw__/a2ui/.
• Nó được phục vụ từ máy chủ HTTP của Gateway (cùng cổng với gateway.port, mặc định 18789).
• Node iOS tự động điều hướng tới A2UI khi kết nối nếu URL máy chủ canvas được quảng bá.
• Quay lại scaffold tích hợp bằng canvas.navigate và {"url":""}.

​

Quan hệ với Computer Use

​

Eval / ảnh chụp 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"}'

​

Đánh thức bằng giọng nói + chế độ Talk

• Đánh thức bằng giọng nói và chế độ Talk có trong Cài đặt.
• iOS có thể tạm dừng âm thanh nền; hãy xem các tính năng giọng nói là nỗ lực tốt nhất khi ứng dụng không hoạt động.

​

Lỗi thường gặp

• NODE_BACKGROUND_UNAVAILABLE: đưa ứng dụng iOS ra tiền cảnh (các lệnh canvas/camera/screen yêu cầu điều này).
• A2UI_HOST_NOT_CONFIGURED: Gateway không quảng bá URL máy chủ canvas; kiểm tra canvasHost trong cấu hình Gateway.
• Lời nhắc ghép nối không bao giờ xuất hiện: chạy openclaw devices list và phê duyệt thủ công.
• Kết nối lại thất bại sau khi cài đặt lại: token ghép nối Keychain đã bị xóa; hãy ghép nối lại Node.

​

Tài liệu liên quan

• Ghép nối
• Phát hiện
• Bonjour