Truy cập từ xa (SSH, tunnel, và tailnet)

Repo này hỗ trợ “remote over SSH” bằng cách giữ một Gateway duy nhất (master) chạy trên một host chuyên dụng (desktop/server) và kết nối các client tới nó.

  • Với operator (các bạn / ứng dụng macOS): SSH tunneling là phương án dự phòng phổ quát.
  • Với node (iOS/Android và các thiết bị tương lai): kết nối tới Gateway WebSocket (qua LAN/tailnet hoặc SSH tunnel nếu cần).

Ý tưởng cốt lõi

  • Gateway WebSocket bind vào loopback trên port đã cấu hình (mặc định là 18789).
  • Để dùng từ xa, các bạn forward port loopback đó qua SSH (hoặc dùng tailnet/VPN và ít tunnel hơn).

Các thiết lập VPN/tailnet phổ biến (nơi agent chạy)

Hãy nghĩ về Gateway host như là “nơi agent sống”. Nó quản lý session, auth profile, channel, và state. Laptop/desktop (và các node) của các bạn kết nối tới host đó.

1) Gateway luôn chạy trong tailnet của bạn (VPS hoặc home server)

Chạy Gateway trên một host persistent và truy cập qua Tailscale hoặc SSH.

  • UX tốt nhất: giữ gateway.bind: "loopback" và dùng Tailscale Serve cho Control UI.
  • Phương án dự phòng: giữ loopback + SSH tunnel từ bất kỳ máy nào cần truy cập.
  • Ví dụ: exe.dev (VM dễ dùng) hoặc Hetzner (VPS production).

Cách này lý tưởng khi laptop của các bạn hay sleep nhưng muốn agent luôn chạy.

2) Desktop ở nhà chạy Gateway, laptop điều khiển từ xa

Laptop không chạy agent. Nó kết nối từ xa:

  • Dùng chế độ Remote over SSH của ứng dụng macOS (Settings → General → “OpenClaw runs”).
  • Ứng dụng sẽ mở và quản lý tunnel, nên WebChat + health check “chạy ngay”.

Hướng dẫn: macOS remote access.

3) Laptop chạy Gateway, truy cập từ xa từ các máy khác

Giữ Gateway ở local nhưng expose an toàn:

  • SSH tunnel tới laptop từ các máy khác, hoặc
  • Tailscale Serve Control UI và giữ Gateway ở chế độ loopback-only.

Hướng dẫn: Tailscale và Web overview.

Luồng lệnh (cái gì chạy ở đâu)

Một gateway service quản lý state + channel. Node là thiết bị ngoại vi.

Ví dụ luồng (Telegram → node):

  • Tin nhắn Telegram đến Gateway.
  • Gateway chạy agent và quyết định có gọi node tool không.
  • Gateway gọi node qua Gateway WebSocket (node.* RPC).
  • Node trả về kết quả; Gateway reply lại cho Telegram.

Lưu ý:

  • Node không chạy gateway service. Chỉ nên chạy một gateway trên mỗi host trừ khi các bạn cố ý chạy các profile riêng biệt (xem Multiple gateway).
  • macOS app “node mode” chỉ là một node client qua Gateway WebSocket.

SSH tunnel (CLI + tools)

Tạo một tunnel local tới Gateway WS từ xa:

ssh -N -L 18789:127.0.0.1:18789 user@host

Khi tunnel đã chạy:

  • openclaw health và openclaw status --deep giờ sẽ kết nối tới gateway từ xa qua ws://127.0.0.1:18789.
  • openclaw gateway {status,health,send,agent,call} cũng có thể target URL đã forward qua --url khi cần.

Lưu ý: thay 18789 bằng gateway.port đã cấu hình của các bạn (hoặc --port/OPENCLAW_GATEWAY_PORT).

CLI remote mặc định

Các bạn có thể lưu remote target để các lệnh CLI dùng nó mặc định:

{
  gateway: {
    mode: "remote",
    remote: {
      url: "ws://127.0.0.1:18789",
      token: "your-token",
    },
  },
}

Khi gateway ở chế độ loopback-only, giữ URL là ws://127.0.0.1:18789 và mở SSH tunnel trước.

Chat UI qua SSH

WebChat không còn dùng HTTP port riêng nữa. SwiftUI chat UI kết nối trực tiếp tới Gateway WebSocket.

  • Forward 18789 qua SSH (xem phía trên), sau đó kết nối client tới ws://127.0.0.1:18789.
  • Trên macOS, mình khuyên dùng chế độ “Remote over SSH” của app, nó sẽ tự quản lý tunnel.

macOS app “Remote over SSH”

Ứng dụng menu bar macOS có thể điều khiển toàn bộ thiết lập này từ đầu đến cuối (remote status check, WebChat, và Voice Wake forwarding).

Hướng dẫn: macOS remote access.

Quy tắc bảo mật (remote/VPN)

Phiên bản ngắn gọn: giữ Gateway ở chế độ loopback-only trừ khi các bạn chắc chắn cần bind.

  • Loopback + SSH/Tailscale Serve là cách an toàn nhất (không public ra ngoài).
  • Non-loopback bind (lan/tailnet/custom, hoặc auto khi loopback không khả dụng) phải dùng auth token/password.
  • gateway.remote.token chỉ dùng cho remote CLI call — nó không bật local auth.
  • gateway.remote.tlsFingerprint pin remote TLS cert khi dùng wss://.
  • Tailscale Serve có thể xác thực qua identity header khi gateway.auth.allowTailscale: true. Đặt thành false nếu các bạn muốn dùng token/password thay thế.
  • Coi browser control như operator access: chỉ dùng trong tailnet + node pairing có chủ đích.

Tìm hiểu sâu: Security.