遠端存取（SSH、tunnel 與 tailnet）

此專案透過在專用主機（桌機/伺服器）上維持一個主 Gateway 並讓用戶端連入的方式，支援「透過 SSH 遠端操作」。

  • 操作者（你自己 / macOS app）：SSH tunnel 是萬用的後備方案。
  • 節點（iOS/Android 及未來裝置）：透過 Gateway WebSocket 連線（LAN/tailnet，必要時走 SSH tunnel）。

核心概念

  • Gateway WebSocket 綁定在你設定的連接埠上的 loopback（預設 18789）。
  • 遠端使用時，透過 SSH 轉送該 loopback 連接埠（或使用 tailnet/VPN 減少 tunnel 需求）。

常見的 VPN/tailnet 架構（代理所在位置）

把 Gateway 主機想成「代理所在的地方」。它擁有 session、認證 profile、通訊頻道和狀態。 你的筆電/桌機（及節點）連入這台主機。

1) tailnet 中的常駐 Gateway（VPS 或家用伺服器）

在一台持久運行的主機上跑 Gateway，透過 Tailscale 或 SSH 連入。

  • 最佳體驗： 保持 gateway.bind: "loopback" 並使用 Tailscale Serve 提供 Control UI。
  • 後備方案： 保持 loopback + 從任何需要存取的機器建立 SSH tunnel。
  • 範例： exe.dev（方便的 VM）或 Hetzner（正式環境 VPS）。

這適合筆電經常休眠、但需要代理隨時在線的情境。

2) 家用桌機跑 Gateway，筆電當遙控器

筆電不跑代理，只是遠端連入：

  • 使用 macOS app 的 Remote over SSH 模式（設定 → 一般 → 「OpenClaw runs」）。
  • App 會自動開啟和管理 tunnel，WebChat + 健康檢查直接可用。

操作手冊：macOS 遠端存取。

3) 筆電跑 Gateway，從其他機器遠端存取

Gateway 留在本機，但安全地對外提供存取：

  • 從其他機器建 SSH tunnel 到筆電，或
  • 用 Tailscale Serve 提供 Control UI，Gateway 保持 loopback-only。

指南：Tailscale 和 Web 總覽。

指令流程（各元件分工）

一個 gateway 服務擁有狀態 + 通訊頻道。節點是周邊裝置。

流程範例（Telegram → 節點）：

  • Telegram 訊息到達 Gateway。
  • Gateway 執行代理，決定是否需要呼叫節點工具。
  • Gateway 透過 Gateway WebSocket 呼叫節點（node.* RPC）。
  • 節點回傳結果；Gateway 將回覆送回 Telegram。

注意事項：

  • 節點不跑 gateway 服務。 除非你有意執行獨立 profile，否則每台主機只該跑一個 gateway（詳見 多 Gateway 部署）。
  • macOS app 的「node mode」只是透過 Gateway WebSocket 運作的節點用戶端。

SSH tunnel（CLI + 工具）

建立一條到遠端 Gateway WS 的本機 tunnel：

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

Tunnel 建立後：

  • openclaw health 和 openclaw status --deep 會透過 ws://127.0.0.1:18789 連到遠端 gateway。
  • openclaw gateway {status,health,send,agent,call} 也可透過 --url 指向轉送的 URL。

注意：如果你的 gateway.port（或 --port/OPENCLAW_GATEWAY_PORT）不是 18789，請替換。 注意：使用 --url 時，CLI 不會自動取用設定檔或環境變數中的憑證。 請明確提供 --token 或 --password，缺少明確憑證會報錯。

CLI 遠端預設值

你可以持久化遠端目標，讓 CLI 指令預設使用：

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

當 gateway 是 loopback-only 時，URL 保持 ws://127.0.0.1:18789，先開好 SSH tunnel 即可。

憑證優先順序

Gateway 憑證解析在 call/probe/status 路徑及 Discord exec-approval 監聽中共用同一套規則。Node-host 使用相同的基礎規則，但有一個本機模式例外（它會刻意忽略 gateway.remote.*）：

  • 明確憑證（--token、--password 或工具的 gatewayToken）在接受明確認證的呼叫路徑上永遠優先。
  • URL 覆寫安全性：
    • CLI URL 覆寫（--url）不會重用隱式的設定/環境憑證。
    • 環境變數 URL 覆寫（OPENCLAW_GATEWAY_URL）只會使用環境變數憑證（OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD）。
  • 本機模式預設值：
    • token：OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token -> gateway.remote.token（remote fallback 僅在本機 auth token 未設定時生效）
    • password：OPENCLAW_GATEWAY_PASSWORD -> gateway.auth.password -> gateway.remote.password（remote fallback 僅在本機 auth password 未設定時生效）
  • 遠端模式預設值：
    • token：gateway.remote.token -> OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token
    • password：OPENCLAW_GATEWAY_PASSWORD -> gateway.remote.password -> gateway.auth.password
  • Node-host 本機模式例外：gateway.remote.token / gateway.remote.password 被忽略。
  • 遠端 probe/status token 檢查預設嚴格模式：在目標為 remote 模式時，只使用 gateway.remote.token（不會 fallback 到本機 token）。
  • 舊版 CLAWDBOT_GATEWAY_* 環境變數僅在相容呼叫路徑中使用；probe/status/auth 解析只用 OPENCLAW_GATEWAY_*。

透過 SSH 使用 Chat UI

WebChat 不再使用獨立的 HTTP 連接埠。SwiftUI chat UI 直接連接 Gateway WebSocket。

  • 透過 SSH 轉送 18789（見上方說明），然後讓用戶端連接 ws://127.0.0.1:18789。
  • macOS 上建議使用 app 的「Remote over SSH」模式，它會自動管理 tunnel。

macOS app「Remote over SSH」

macOS 選單列 app 可以端對端完成相同的設定（遠端狀態檢查、WebChat 和 Voice Wake 轉送）。

操作手冊：macOS 遠端存取。

安全規則（遠端/VPN）

簡要版：除非確定有需要，否則讓 Gateway 保持 loopback-only。

  • Loopback + SSH/Tailscale Serve 是最安全的預設值（無公開暴露）。
  • 明文 ws:// 預設僅限 loopback。如果是受信任的私有網路，在用戶端程序上設定 OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 作為緊急措施。
  • 非 loopback 綁定（lan/tailnet/custom，或 loopback 不可用時的 auto）必須使用認證 token/password。
  • gateway.remote.token / .password 是用戶端憑證來源，它們本身不會設定伺服器端認證。
  • 本機呼叫路徑只有在 gateway.auth.* 未設定時才會 fallback 使用 gateway.remote.*。
  • 如果 gateway.auth.token / gateway.auth.password 透過 SecretRef 明確設定但未解析成功，解析會直接失敗（不會用 remote fallback 遮蓋）。
  • gateway.remote.tlsFingerprint 在使用 wss:// 時 pin 遠端 TLS 憑證。
  • Tailscale Serve 在 gateway.auth.allowTailscale: true 時可透過 identity header 認證 Control UI/WebSocket 流量；HTTP API 端點仍需要 token/password 認證。這種免 token 流程假設 gateway 主機是受信任的。如果你希望所有地方都用 token/password，請設定為 false。
  • 把瀏覽器控制視同操作者存取：限制在 tailnet 內 + 刻意配對節點。

深入了解：安全性。

arrow_back
上一頁
Bonjour
下一頁
Remote Gateway Readme
arrow_forward