Discovery & transports

OpenClaw có hai vấn đề riêng biệt nhưng trông có vẻ giống nhau:

  1. Điều khiển từ xa cho operator: ứng dụng menu bar trên macOS điều khiển gateway đang chạy ở nơi khác.
  2. Node pairing: các thiết bị iOS/Android (và các node tương lai) tìm gateway và pairing một cách bảo mật.

Mục tiêu thiết kế là giữ toàn bộ network discovery/advertising trong Node Gateway (openclaw gateway) và để các client (mac app, iOS) đóng vai trò consumer.

Thuật ngữ

  • Gateway: một tiến trình gateway chạy lâu dài, quản lý state (sessions, pairing, node registry) và chạy các channel. Hầu hết các setup dùng một gateway cho mỗi host; có thể setup nhiều gateway độc lập.
  • Gateway WS (control plane): WebSocket endpoint trên 127.0.0.1:18789 theo mặc định; có thể bind vào LAN/tailnet qua gateway.bind.
  • Direct WS transport: Gateway WS endpoint hướng ra LAN/tailnet (không qua SSH).
  • SSH transport (fallback): điều khiển từ xa bằng cách forward 127.0.0.1:18789 qua SSH.
  • Legacy TCP bridge (deprecated/removed): node transport cũ (xem Bridge protocol); không còn được quảng bá cho discovery nữa.

Chi tiết protocol:

Tại sao giữ cả “direct” và SSH

  • Direct WS cho trải nghiệm tốt nhất trên cùng mạng và trong tailnet:
    • tự động khám phá trên LAN qua Bonjour
    • pairing tokens + ACLs do gateway quản lý
    • không cần shell access; giao thức có thể giữ chặt chẽ và dễ kiểm tra
  • SSH vẫn là phương án dự phòng phổ quát:
    • hoạt động ở bất cứ đâu có SSH access (ngay cả giữa các mạng không liên quan)
    • vẫn hoạt động khi multicast/mDNS gặp vấn đề
    • không cần mở thêm port nào ngoài SSH

Discovery inputs (cách client tìm gateway)

1) Bonjour / mDNS (chỉ LAN)

Bonjour hoạt động theo kiểu best-effort và không vượt qua các mạng khác nhau. Nó chỉ dùng cho tiện lợi “cùng LAN”.

Hướng mục tiêu:

  • Gateway quảng bá WS endpoint của nó qua Bonjour.
  • Các client duyệt và hiển thị danh sách “chọn một gateway”, sau đó lưu endpoint đã chọn.

Troubleshooting và chi tiết beacon: Bonjour.

Chi tiết service beacon

  • Service types:
    • _openclaw-gw._tcp (gateway transport beacon)
  • TXT keys (không phải secret):
    • role=gateway
    • lanHost=<hostname>.local
    • sshPort=22 (hoặc port nào được quảng bá)
    • gatewayPort=18789 (Gateway WS + HTTP)
    • gatewayTls=1 (chỉ khi TLS được bật)
    • gatewayTlsSha256=<sha256> (chỉ khi TLS được bật và có fingerprint)
    • canvasPort=18793 (default canvas host port; phục vụ /__openclaw__/canvas/)
    • cliPath=<path> (tùy chọn; đường dẫn tuyệt đối đến openclaw entrypoint hoặc binary có thể chạy)
    • tailnetDns=<magicdns> (gợi ý tùy chọn; tự động phát hiện khi Tailscale khả dụng)

Tắt/ghi đè:

  • OPENCLAW_DISABLE_BONJOUR=1 tắt quảng bá.
  • gateway.bind trong ~/.openclaw/openclaw.json điều khiển chế độ bind của Gateway.
  • OPENCLAW_SSH_PORT ghi đè SSH port được quảng bá trong TXT (mặc định là 22).
  • OPENCLAW_TAILNET_DNS xuất bản gợi ý tailnetDns (MagicDNS).
  • OPENCLAW_CLI_PATH ghi đè CLI path được quảng bá.

2) Tailnet (cross-network)

Với các setup kiểu London/Vienna, Bonjour sẽ không giúp được. Target “direct” được khuyên dùng là:

  • Tên Tailscale MagicDNS (ưu tiên) hoặc một tailnet IP ổn định.

Nếu gateway phát hiện được nó đang chạy dưới Tailscale, nó sẽ xuất bản tailnetDns như một gợi ý tùy chọn cho các client (bao gồm cả wide-area beacons).

3) Manual / SSH target

Khi không có direct route (hoặc direct bị tắt), các client luôn có thể kết nối qua SSH bằng cách forward loopback gateway port.

Xem Remote access.

Transport selection (client policy)

Hành vi client được khuyên dùng:

  1. Nếu một paired direct endpoint đã được cấu hình và có thể truy cập, dùng nó.
  2. Nếu không, nếu Bonjour tìm thấy gateway trên LAN, hiển thị lựa chọn “Use this gateway” một chạm và lưu nó làm direct endpoint.
  3. Nếu không, nếu tailnet DNS/IP đã được cấu hình, thử direct.
  4. Nếu không, fall back sang SSH.

Pairing + auth (direct transport)

Gateway là nguồn chân lý cho việc chấp nhận node/client.

  • Các yêu cầu pairing được tạo/chấp thuận/từ chối trong gateway (xem Gateway pairing).
  • Gateway thực thi:
    • auth (token / keypair)
    • scopes/ACLs (gateway không phải là proxy thô đến mọi method)
    • rate limits

Trách nhiệm theo component

  • Gateway: quảng bá discovery beacons, quyết định pairing, và host WS endpoint.
  • macOS app: giúp các bạn chọn gateway, hiển thị pairing prompts, và chỉ dùng SSH như phương án dự phòng.
  • iOS/Android nodes: duyệt Bonjour để tiện lợi và kết nối đến Gateway WS đã pairing.