​

Truy cập từ xa (SSH, tunnels và tailnets)

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

​

Ý tưởng cốt lõi

• Gateway WebSocket kết nối với loopback trên cổng đã cấu hình của bạn (mặc định là 18789).
• Để sử dụng từ xa, bạn chuyển tiếp cổng loopback đó qua SSH (hoặc sử dụng tailnet/VPN và giảm thiểu việc tunneling).

​

Cài đặt VPN/tailnet phổ biến (nơi agent hoạt động)

​

1) Gateway luôn hoạt động trong tailnet của bạn (VPS hoặc máy chủ tại nhà)

• Trải nghiệm người dùng tốt nhất: giữ gateway.bind: "loopback" và sử dụng Tailscale Serve cho giao diện điều khiển.
• 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 sản xuất).

​

2) Máy tính để bàn tại nhà chạy Gateway, laptop là điều khiển từ xa

• Sử dụng chế độ Remote over SSH của ứng dụng macOS (Cài đặt → Chung → “OpenClaw chạy”).
• Ứng dụng mở và quản lý tunnel, do đó WebChat + kiểm tra sức khỏe hoạt động “ngay lập tức”.

​

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

• SSH tunnel đến laptop từ các máy khác, hoặc
• Tailscale Serve giao diện điều khiển và giữ Gateway chỉ loopback.

​

Luồng lệnh (chạy ở đâu)

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

• Các node không chạy dịch vụ gateway. Chỉ một gateway nên chạy trên mỗi máy chủ trừ khi bạn cố ý chạy các hồ sơ cách ly (xem Nhiều gateway).
• Chế độ “node mode” của ứng dụng macOS chỉ là một client node qua Gateway WebSocket.

​

SSH tunnel (CLI + công cụ)

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

• openclaw health và openclaw status --deep giờ đây có thể truy cập gateway từ xa qua ws://127.0.0.1:18789.
• openclaw gateway {status,health,send,agent,call} cũng có thể nhắm đến URL đã chuyển tiếp qua --url khi cần.

​

Mặc định từ xa của CLI

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

​

Quy tắc thông tin xác thực

• Thông tin xác thực rõ ràng (--token, --password, hoặc công cụ gatewayToken) luôn thắng trên các đường dẫn call chấp nhận xác thực rõ ràng.
• An toàn ghi đè URL:
  • Ghi đè URL CLI (--url) không bao giờ sử dụng lại thông tin xác thực cấu hình/môi trường ngầm định.
  • Ghi đè URL môi trường (OPENCLAW_GATEWAY_URL) chỉ có thể sử dụng thông tin xác thực môi trường (OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD).
• Mặc định chế độ cục bộ:
  • token: OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token -> gateway.remote.token (phương án dự phòng từ xa chỉ áp dụng khi đầu vào token xác thực cục bộ chưa được đặt)
  • password: OPENCLAW_GATEWAY_PASSWORD -> gateway.auth.password -> gateway.remote.password (phương án dự phòng từ xa chỉ áp dụng khi đầu vào password xác thực cục bộ chưa được đặt)
• Mặc định chế độ từ xa:
  • token: gateway.remote.token -> OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token
  • password: OPENCLAW_GATEWAY_PASSWORD -> gateway.remote.password -> gateway.auth.password
• Ngoại lệ chế độ cục bộ node-host: gateway.remote.token / gateway.remote.password bị bỏ qua.
• Kiểm tra token probe/status từ xa nghiêm ngặt theo mặc định: chúng chỉ sử dụng gateway.remote.token (không có phương án dự phòng token cục bộ) khi nhắm đến chế độ từ xa.
• Biến môi trường CLAWDBOT_GATEWAY_* cũ chỉ được sử dụng bởi các đường dẫn call tương thích; giải quyết probe/status/auth chỉ sử dụng OPENCLAW_GATEWAY_*.

​

Giao diện chat qua SSH

• Chuyển tiếp 18789 qua SSH (xem ở trên), sau đó kết nối các client đến ws://127.0.0.1:18789.
• Trên macOS, ưu tiên chế độ “Remote over SSH” của ứng dụng, chế độ này quản lý tunnel tự động.

​

Ứng dụng macOS “Remote over SSH”

​

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

• Loopback + SSH/Tailscale Serve là mặc định an toàn nhất (không phơi bày công khai).
• ws:// dạng văn bản chỉ là loopback theo mặc định. Đối với các mạng riêng tư đáng tin cậy, đặt OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 trên tiến trình client như một biện pháp khẩn cấp.
• Non-loopback binds (lan/tailnet/custom, hoặc auto khi loopback không khả dụng) phải sử dụng token/password xác thực.
• gateway.remote.token / .password là nguồn thông tin xác thực client. Chúng không tự cấu hình xác thực máy chủ.
• Các đường dẫn call cục bộ có thể sử dụng gateway.remote.* như phương án dự phòng chỉ khi gateway.auth.* chưa được đặt.
• Nếu gateway.auth.token / gateway.auth.password được cấu hình rõ ràng qua SecretRef và không được giải quyết, giải quyết sẽ thất bại (không có phương án dự phòng từ xa).
• gateway.remote.tlsFingerprint ghim chứng chỉ TLS từ xa khi sử dụng wss://.
• Tailscale Serve có thể xác thực lưu lượng Control UI/WebSocket qua các tiêu đề nhận dạng khi gateway.auth.allowTailscale: true; các điểm cuối API HTTP vẫn yêu cầu xác thực token/password. Luồng không cần token này giả định máy chủ gateway là đáng tin cậy. Đặt nó thành false nếu bạn muốn token/password ở mọi nơi.
• Xem điều khiển trình duyệt như truy cập của người vận hành: chỉ tailnet + ghép nối node có chủ ý.