Remote OpenClaw (macOS ⇄ remote host)

Luồng này cho phép ứng dụng macOS hoạt động như một bộ điều khiển từ xa hoàn chỉnh cho Gateway OpenClaw đang chạy trên một host khác (desktop/server). Đây là tính năng Remote over SSH (chạy từ xa) của ứng dụng. Tất cả các tính năng—health check, Voice Wake forwarding, và Web Chat—đều dùng chung cấu hình SSH từ xa từ Settings → General.

Các chế độ

  • Local (this Mac): Mọi thứ chạy trên laptop. Không dùng SSH.
  • Remote over SSH (mặc định): Các lệnh OpenClaw được thực thi trên remote host. Ứng dụng Mac mở kết nối SSH với -o BatchMode cùng identity/key mà các bạn chọn và một local port-forward.
  • Remote direct (ws/wss): Không dùng SSH tunnel. Ứng dụng Mac kết nối trực tiếp đến Gateway URL (ví dụ qua Tailscale Serve hoặc một HTTPS reverse proxy công khai).

Remote transports

Chế độ remote hỗ trợ hai loại transport:

  • SSH tunnel (mặc định): Dùng ssh -N -L ... để forward cổng Gateway về localhost. Gateway sẽ thấy IP của node là 127.0.0.1 vì tunnel là loopback.
  • Direct (ws/wss): Kết nối thẳng đến Gateway URL. Gateway thấy IP thật của client.

Yêu cầu trên remote host

  1. Cài đặt Node + pnpm và build/install OpenClaw CLI (pnpm install && pnpm build && pnpm link --global).
  2. Đảm bảo openclaw có trong PATH cho non-interactive shell (symlink vào /usr/local/bin hoặc /opt/homebrew/bin nếu cần).
  3. Mở SSH với key auth. Mình khuyên dùng IP Tailscale để kết nối ổn định khi không ở cùng mạng LAN.

Thiết lập ứng dụng macOS

  1. Mở Settings → General.
  2. Ở mục OpenClaw runs, chọn Remote over SSH và cấu hình:
    • Transport: SSH tunnel hoặc Direct (ws/wss).
    • SSH target: user@host (có thể thêm :port).
      • Nếu Gateway ở cùng LAN và quảng bá Bonjour, các bạn chọn từ danh sách phát hiện được để tự động điền trường này.
    • Gateway URL (chỉ cho Direct): wss://gateway.example.ts.net (hoặc ws://... cho local/LAN).
    • Identity file (nâng cao): đường dẫn đến key của các bạn.
    • Project root (nâng cao): đường dẫn checkout từ xa dùng cho các lệnh.
    • CLI path (nâng cao): đường dẫn tùy chọn đến entrypoint/binary openclaw có thể chạy được (tự động điền khi được quảng bá).
  3. Ấn Test remote. Thành công nghĩa là lệnh openclaw status --json từ xa chạy đúng. Lỗi thường do vấn đề PATH/CLI; exit 127 nghĩa là không tìm thấy CLI trên remote.
  4. Health check và Web Chat giờ sẽ tự động chạy qua SSH tunnel này.

Web Chat

  • SSH tunnel: Web Chat kết nối đến Gateway qua cổng WebSocket control được forward (mặc định 18789).
  • Direct (ws/wss): Web Chat kết nối thẳng đến Gateway URL đã cấu hình.
  • Không còn WebChat HTTP server riêng nữa.

Quyền truy cập

  • Remote host cần các quyền TCC giống như local (Automation, Accessibility, Screen Recording, Microphone, Speech Recognition, Notifications). Chạy onboarding trên máy đó để cấp quyền một lần.
  • Các node quảng bá trạng thái quyền của chúng qua node.list / node.describe để agent biết những gì có sẵn.

Lưu ý bảo mật

  • Ưu tiên bind loopback trên remote host và kết nối qua SSH hoặc Tailscale.
  • Nếu các bạn bind Gateway vào interface không phải loopback, hãy yêu cầu token/password auth.
  • Xem thêm Security và Tailscale.

Luồng đăng nhập WhatsApp (remote)

  • Chạy openclaw channels login --verbose trên remote host. Quét mã QR bằng WhatsApp trên điện thoại.
  • Chạy lại login trên host đó nếu auth hết hạn. Health check sẽ phát hiện các vấn đề kết nối.

Troubleshooting

  • exit 127 / not found: openclaw không có trong PATH cho non-login shell. Thêm nó vào /etc/paths, shell rc của các bạn, hoặc symlink vào /usr/local/bin//opt/homebrew/bin.
  • Health probe failed: kiểm tra khả năng kết nối SSH, PATH, và Baileys đã đăng nhập chưa (openclaw status --json).
  • Web Chat stuck: xác nhận Gateway đang chạy trên remote host và cổng được forward khớp với cổng WS của Gateway; UI yêu cầu kết nối WS khỏe mạnh.
  • Node IP hiển thị 127.0.0.1: đây là điều bình thường với SSH tunnel. Chuyển Transport sang Direct (ws/wss) nếu các bạn muốn Gateway thấy IP thật của client.
  • Voice Wake: các cụm từ kích hoạt được forward tự động ở chế độ remote; không cần forwarder riêng.

Âm thanh thông báo

Chọn âm thanh cho từng thông báo từ script với openclaw và node.invoke, ví dụ:

openclaw nodes notify --node <id> --title "Ping" --body "Remote gateway ready" --sound Glass

Không còn toggle “âm thanh mặc định” toàn cục trong ứng dụng nữa; người gọi chọn âm thanh (hoặc không có) cho mỗi request.