Truy cập từ xa

• Với người vận hành (bạn / ứng dụng macOS): WebSocket trực tiếp qua LAN/Tailnet là đơn giản nhất khi gateway có thể truy cập được; SSH tunneling là phương án dự phòng phổ quát.
• Với các nút (iOS/Android và thiết bị tương lai): kết nối tới Gateway WebSocket (LAN/tailnet hoặc SSH tunnel khi cần).

​

Ý tưởng cốt lõi

• Gateway WebSocket thường bind vào loopback trên cổng bạn cấu hình (mặc định là 18789).
• Để dùng từ xa, hãy phơi nó qua Tailscale Serve hoặc một bind LAN/Tailnet tin cậy, hoặc chuyển tiếp cổng loopback qua SSH.

​

Các thiết lập VPN và tailnet phổ biến

​

Gateway luôn bật trong tailnet của bạn

• UX tốt nhất: giữ gateway.bind: "loopback" và dùng Tailscale Serve cho Control UI.
• LAN/Tailnet tin cậy: bind gateway vào một giao diện riêng tư và kết nối trực tiếp với gateway.remote.transport: "direct".
• Dự phòng: giữ loopback cùng 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).

​

Máy tính để bàn tại nhà chạy Gateway

• Dùng chế độ từ xa của ứng dụng macOS (Settings → General → OpenClaw runs).
• Ứng dụng kết nối trực tiếp khi gateway có thể truy cập trên LAN/Tailnet, hoặc mở và quản lý SSH tunnel khi bạn chọn SSH.

​

Laptop chạy Gateway

• SSH tunnel tới laptop từ các máy khác, hoặc
• Dùng Tailscale Serve cho Control UI và giữ Gateway chỉ loopback.

​

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

• Tin nhắn Telegram đến Gateway.
• Gateway chạy agent và quyết định có gọi một công cụ nút hay không.
• Gateway gọi nút qua Gateway WebSocket (node.* RPC).
• Nút trả về kết quả; Gateway trả lời ngược lại ra Telegram.

• Các nút không chạy dịch vụ gateway. Chỉ nên chạy một gateway trên mỗi máy chủ, trừ khi bạn cố ý chạy các hồ sơ tách biệt (xem Nhiều gateway).
• “Chế độ nút” của ứng dụng macOS chỉ là một client nút 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ờ sẽ truy cập gateway từ xa qua ws://127.0.0.1:18789.
• openclaw gateway status, openclaw gateway health, openclaw gateway probe và openclaw gateway call cũng có thể nhắm tới 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",
    },
  },
}

{
  gateway: {
    mode: "remote",
    remote: {
      transport: "direct",
      url: "ws://192.168.0.202:18789",
      token: "your-token",
    },
  },
}

​

Thứ tự ưu tiên thông tin xác thực

• Thông tin xác thực tường minh (--token, --password, hoặc gatewayToken của công cụ) luôn thắng trên các đường dẫn call chấp nhận xác thực tường minh.
• An toàn khi ghi đè URL:
  • Các ghi đè URL của CLI (--url) không bao giờ tái sử dụng thông tin xác thực ngầm định từ config/env.
  • Các ghi đè URL từ env (OPENCLAW_GATEWAY_URL) chỉ có thể dùng thông tin xác thực env (OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD).
• Mặc định chế độ cục bộ:
  • token: OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token -> gateway.remote.token (fallback 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 (fallback từ xa chỉ áp dụng khi đầu vào mật khẩu 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ộ của Node-host: gateway.remote.token / gateway.remote.password bị bỏ qua.
• Kiểm tra token probe/status từ xa mặc định là nghiêm ngặt: chúng chỉ dùng gateway.remote.token (không fallback sang token cục bộ) khi nhắm tới chế độ từ xa.
• Ghi đè env của Gateway chỉ dùng OPENCLAW_GATEWAY_*.

​

Truy cập từ xa Chat UI

• Chuyển tiếp 18789 qua SSH (xem ở trên), rồi kết nối client tới ws://127.0.0.1:18789.
• Với chế độ trực tiếp LAN/Tailnet, kết nối client tới URL riêng tư ws:// hoặc bảo mật wss:// đã cấu hình.
• Trên macOS, ưu tiên chế độ từ xa của ứng dụng, chế độ này tự động quản lý transport đã chọn.

​

Chế độ từ xa của ứng dụng macOS

​

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

• Loopback + SSH/Tailscale Serve là mặc định an toàn nhất (không phơi công khai).
• Plaintext ws:// được chấp nhận cho loopback, LAN, link-local, .local, .ts.net và các máy chủ Tailscale CGNAT. Máy chủ từ xa công khai phải dùng wss://.
• Bind không phải loopback (lan/tailnet/custom, hoặc auto khi loopback không khả dụng) phải dùng xác thực gateway: token, mật khẩu, hoặc reverse proxy nhận biết danh tính với gateway.auth.mode: "trusted-proxy".
• gateway.remote.token / .password là nguồn thông tin xác thực client. Tự chúng không cấu hình xác thực máy chủ.
• Các đường dẫn call cục bộ chỉ có thể dùng gateway.remote.* làm fallback khi gateway.auth.* chưa được đặt.
• Nếu gateway.auth.token / gateway.auth.password được cấu hình tường minh qua SecretRef và không phân giải được, việc phân giải sẽ fail-closed (không bị fallback từ xa che khuất).
• gateway.remote.tlsFingerprint ghim chứng chỉ TLS từ xa khi dùng wss://, bao gồm cả chế độ trực tiếp macOS. Nếu không có pin đã cấu hình hoặc đã lưu trước đó, macOS chỉ ghim chứng chỉ lần đầu sử dụng sau khi vượt qua kiểm tra tin cậy hệ thống bình thường; các gateway tự ký hoặc private-CA mà macOS chưa tin cậy cần fingerprint tường minh hoặc Remote over SSH.
• Tailscale Serve có thể xác thực lưu lượng Control UI/WebSocket qua các header danh tính khi gateway.auth.allowTailscale: true; các endpoint HTTP API không dùng xác thực header Tailscale đó và thay vào đó tuân theo chế độ xác thực HTTP thông thường của gateway. Luồng không token này giả định máy chủ gateway là tin cậy. Đặt thành false nếu bạn muốn xác thực bằng shared-secret ở mọi nơi.
• Xác thực Trusted-proxy mặc định kỳ vọng các thiết lập proxy nhận biết danh tính không phải loopback. Reverse proxy loopback cùng máy chủ yêu cầu gateway.auth.trustedProxy.allowLoopback = true tường minh.
• Đối xử với quyền điều khiển qua trình duyệt như quyền truy cập của người vận hành: chỉ tailnet + ghép cặp nút có chủ đích.

​

macOS: SSH tunnel bền vững qua LaunchAgent

​

Bước 1: thêm cấu hình SSH

Host remote-gateway
    HostName <REMOTE_IP>
    User <REMOTE_USER>
    LocalForward 18789 127.0.0.1:18789
    IdentityFile ~/.ssh/id_rsa

​

Bước 2: sao chép khóa SSH (một lần)

ssh-copy-id -i ~/.ssh/id_rsa <REMOTE_USER>@<REMOTE_IP>

​

Bước 3: cấu hình token gateway

openclaw config set gateway.remote.token "<your-token>"

​

Bước 4: tạo LaunchAgent

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>ai.openclaw.ssh-tunnel</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/bin/ssh</string>
        <string>-N</string>
        <string>remote-gateway</string>
    </array>
    <key>KeepAlive</key>
    <true/>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>

​

Bước 5: tải LaunchAgent

launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist

​

Khắc phục sự cố

ps aux | grep "ssh -N remote-gateway" | grep -v grep
lsof -i :18789

launchctl kickstart -k gui/$UID/ai.openclaw.ssh-tunnel

launchctl bootout gui/$UID/ai.openclaw.ssh-tunnel

​

Liên quan

• Tailscale
• Xác thực
• Thiết lập gateway từ xa