Ứng dụng iOS (Node)

Trạng thái: bản xem trước nội bộ. Ứng dụng iOS chưa được phân phối công khai.

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, Screen snapshot, Camera capture, Location, Talk mode, Voice wake.
  • Nhận lệnh node.invoke và báo cáo các sự kiện trạng thái của node.

Yêu cầu

  • Gateway đang chạy trên 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 (ví dụ domain: openclaw.internal.), hoặc
    • Manual host/port (phương án dự phòng).

Bắt đầu nhanh (pair + kết nối)

  1. Khởi động Gateway:
openclaw gateway --port 18789

  1. Trong ứng dụng iOS, mở Settings và chọn một gateway đã được phát hiện (hoặc bật Manual Host và nhập host/port).

  2. Phê duyệt yêu cầu pairing trên máy chủ gateway:

openclaw nodes pending
openclaw nodes approve <requestId>
  1. Kiểm tra kết nối:
openclaw nodes status
openclaw gateway call node.list --params "{}"

Các cách phát hiện (Discovery paths)

Bonjour (LAN)

Gateway quảng bá _openclaw-gw._tcp trên local.. Ứng dụng iOS sẽ tự động liệt kê các gateway này.

Tailnet (cross-network)

Nếu mDNS bị chặn, các bạn dùng unicast DNS-SD zone (chọn một domain; ví dụ: openclaw.internal.) và Tailscale split DNS. Xem Bonjour để tham khảo ví dụ CoreDNS.

Manual host/port

Trong Settings, bật Manual Host và nhập gateway host + port (mặc định 18789).

Canvas + A2UI

iOS node render một WKWebView canvas. Dùng node.invoke để điều khiển:

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

Lưu ý:

  • Gateway canvas host phục vụ /__openclaw__/canvas/ và /__openclaw__/a2ui/.
  • iOS node tự động điều hướng tới A2UI khi kết nối nếu canvas host URL được quảng bá.
  • Quay về scaffold tích hợp sẵn bằng canvas.navigate với {"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 + talk mode

  • Voice wake và talk mode có sẵn trong Settings.
  • iOS có thể tạm dừng audio chạy nền; các tính năng voice chỉ hoạt động tốt nhất khi ứng dụng đang active.

Các lỗi thường gặp

  • NODE_BACKGROUND_UNAVAILABLE: đưa ứng dụng iOS lên foreground (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á canvas host URL; kiểm tra canvasHost trong cấu hình Gateway.
  • Pairing prompt không bao giờ xuất hiện: chạy openclaw nodes pending và phê duyệt thủ công.
  • Kết nối lại thất bại sau khi cài đặt lại: Keychain pairing token đã bị xóa; pairing lại node.

Tài liệu liên quan