Ứng dụng Android (Node)

Tổng quan hỗ trợ

  • Vai trò: ứng dụng node đi kèm (Android không chạy Gateway).
  • Yêu cầu Gateway: có (chạy trên macOS, Linux, hoặc Windows qua WSL2).
  • Cài đặt: Bắt đầu + Pairing.
  • Gateway: Runbook + Cấu hình.

Điều khiển hệ thống

Điều khiển hệ thống (launchd/systemd) nằm trên máy chủ Gateway. Xem Gateway.

Hướng dẫn kết nối

Ứng dụng Android node ⇄ (mDNS/NSD + WebSocket) ⇄ Gateway

Android kết nối trực tiếp tới Gateway WebSocket (mặc định ws://<host>:18789) và sử dụng Pairing do Gateway quản lý.

Yêu cầu trước khi bắt đầu

  • Các bạn có thể chạy Gateway trên máy “master”.
  • Thiết bị/emulator Android có thể kết nối tới Gateway WebSocket:
    • Cùng mạng LAN với mDNS/NSD, hoặc
    • Cùng Tailscale tailnet dùng Wide-Area Bonjour / unicast DNS-SD (xem bên dưới), hoặc
    • Nhập thủ công gateway host/port (phương án dự phòng)
  • Các bạn có thể chạy CLI (openclaw) trên máy gateway (hoặc qua SSH).

1) Khởi động Gateway

openclaw gateway --port 18789 --verbose

Kiểm tra trong log xem có dòng kiểu như:

  • listening on ws://0.0.0.0:18789

Với cấu hình chỉ dùng tailnet (khuyên dùng cho Vienna ⇄ London), bind gateway vào IP tailnet:

  • Đặt gateway.bind: "tailnet" trong ~/.openclaw/openclaw.json trên máy chủ gateway.
  • Khởi động lại Gateway / ứng dụng menubar macOS.

2) Xác minh discovery (tùy chọn)

Từ máy gateway:

dns-sd -B _openclaw-gw._tcp local.

Thêm ghi chú debug: Bonjour.

Discovery qua tailnet (Vienna ⇄ London) dùng unicast DNS-SD

Android NSD/mDNS discovery không hoạt động xuyên mạng. Nếu Android node và gateway ở hai mạng khác nhau nhưng kết nối qua Tailscale, hãy dùng Wide-Area Bonjour / unicast DNS-SD:

  1. Thiết lập DNS-SD zone (ví dụ openclaw.internal.) trên máy chủ gateway và publish các bản ghi _openclaw-gw._tcp.
  2. Cấu hình Tailscale split DNS cho domain các bạn chọn, trỏ về DNS server đó.

Chi tiết và ví dụ cấu hình CoreDNS: Bonjour.

3) Kết nối từ Android

Trong ứng dụng Android:

  • Ứng dụng giữ kết nối gateway hoạt động qua foreground service (thông báo liên tục).
  • Mở Settings.
  • Trong Discovered Gateways, chọn gateway của các bạn và ấn Connect.
  • Nếu mDNS bị chặn, dùng Advanced → Manual Gateway (host + port) và Connect (Manual).

Sau lần pairing thành công đầu tiên, Android tự động kết nối lại khi khởi động:

  • Manual endpoint (nếu đã bật), nếu không thì
  • Gateway được phát hiện gần nhất (best-effort).

4) Phê duyệt pairing (CLI)

Trên máy gateway:

openclaw nodes pending
openclaw nodes approve <requestId>

Chi tiết Pairing: Gateway pairing.

5) Xác minh node đã kết nối

  • Qua nodes status: 
    openclaw nodes status
  • Qua Gateway: 
    openclaw gateway call node.list --params "{}"

6) Chat + lịch sử

Chat sheet của Android node dùng primary session key (main) của gateway, nên lịch sử và phản hồi được chia sẻ với WebChat và các client khác:

  • Lịch sử: chat.history
  • Gửi: chat.send
  • Cập nhật push (best-effort): chat.subscribe → event:"chat"

7) Canvas + camera

Gateway Canvas Host (khuyên dùng cho nội dung web)

Nếu các bạn muốn node hiển thị HTML/CSS/JS thực mà agent có thể chỉnh sửa trên ổ đĩa, hãy trỏ node tới Gateway canvas host.

Lưu ý: các node dùng canvas host độc lập trên canvasHost.port (mặc định 18793).

  1. Tạo ~/.openclaw/workspace/canvas/index.html trên máy chủ gateway.

  2. Điều hướng node tới đó (LAN):

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

Tailnet (tùy chọn): nếu cả hai thiết bị đều dùng Tailscale, dùng tên MagicDNS hoặc IP tailnet thay vì .local, ví dụ http://<gateway-magicdns>:18793/__openclaw__/canvas/.

Server này inject một live-reload client vào HTML và reload khi file thay đổi. A2UI host nằm tại http://<gateway-host>:18793/__openclaw__/a2ui/.

Các lệnh Canvas (chỉ foreground):

  • canvas.eval, canvas.snapshot, canvas.navigate (dùng {"url":""} hoặc {"url":"/"} để quay về scaffold mặc định). canvas.snapshot trả về { format, base64 } (mặc định format="jpeg").
  • A2UI: canvas.a2ui.push, canvas.a2ui.reset (alias cũ canvas.a2ui.pushJSONL)

Các lệnh Camera (chỉ foreground; cần quyền):

  • camera.snap (jpg)
  • camera.clip (mp4)

Xem Camera node để biết tham số và CLI helpers.