遠端 OpenClaw（macOS ⇄ 遠端主機）

此流程讓 macOS 應用程式作為在另一台主機（桌機／伺服器）上運行的 OpenClaw Gateway 的完整遠端控制器。這是應用程式的 Remote over SSH（遠端執行）功能。所有功能——健康檢查、語音喚醒轉發和 Web Chat——都重用 Settings → General 中相同的遠端 SSH 設定。

模式

  • Local (this Mac)：所有功能在筆電上執行。不涉及 SSH。
  • Remote over SSH（預設）：OpenClaw 指令在遠端主機上執行。macOS 應用程式以 -o BatchMode 加上你選擇的身分／金鑰和本機連接埠轉發開啟 SSH 連線。
  • Remote direct (ws/wss)：不使用 SSH 通道。macOS 應用程式直接連線至 Gateway URL（例如透過 Tailscale Serve 或公用 HTTPS 反向代理）。

遠端傳輸方式

遠端模式支援兩種傳輸方式：

  • SSH tunnel（預設）：使用 ssh -N -L ... 將 Gateway 連接埠轉發至 localhost。由於通道使用 loopback，Gateway 看到的節點 IP 為 127.0.0.1。
  • Direct (ws/wss)：直接連線至 Gateway URL。Gateway 看到的是真實客戶端 IP。

遠端主機前置需求

  1. 安裝 Node + pnpm 並建構／安裝 OpenClaw CLI（pnpm install && pnpm build && pnpm link --global）。
  2. 確保 openclaw 在非互動式 shell 的 PATH 中（必要時 symlink 至 /usr/local/bin 或 /opt/homebrew/bin）。
  3. 開啟 SSH 並使用金鑰驗證。建議使用 Tailscale IP 以確保離開區域網路後的穩定連線。

macOS 應用程式設定

  1. 開啟 Settings → General。
  2. 在 OpenClaw runs 下方選擇 Remote over SSH 並設定：
    • Transport：SSH tunnel 或 Direct (ws/wss)。
    • SSH target：user@host（選用 :port）。
      • 若 Gateway 位於同一區域網路且廣播 Bonjour，從已發現的清單中選取以自動填入此欄位。
    • Gateway URL（僅 Direct）：wss://gateway.example.ts.net（或 ws://... 用於本機／區域網路）。
    • Identity file（進階）：金鑰路徑。
    • Project root（進階）：用於指令的遠端 checkout 路徑。
    • CLI path（進階）：可選的 openclaw 進入點／執行檔路徑（廣播時自動填入）。
  3. 點選 Test remote。成功表示遠端 openclaw status --json 執行正確。失敗通常代表 PATH/CLI 問題；exit 127 表示遠端找不到 CLI。
  4. 健康檢查和 Web Chat 會自動透過此 SSH 通道運行。

Web Chat

  • SSH tunnel：Web Chat 透過轉發的 WebSocket 控制連接埠連線至 Gateway（預設 18789）。
  • Direct (ws/wss)：Web Chat 直接連線至設定的 Gateway URL。
  • 已不再有獨立的 WebChat HTTP 伺服器。

權限

  • 遠端主機需要與本機相同的 TCC 核准（自動化、輔助使用、螢幕錄製、麥克風、語音辨識、通知）。在該機器上執行引導設定一次即可授予。
  • 節點透過 node.list / node.describe 廣播其權限狀態，讓代理程式知道可用的功能。

安全性說明

  • 建議在遠端主機上使用 loopback 綁定，並透過 SSH 或 Tailscale 連線。
  • SSH 通道使用嚴格主機金鑰檢查；先信任主機金鑰使其存在於 ~/.ssh/known_hosts 中。
  • 若將 Gateway 綁定至非 loopback 介面，請要求 token/密碼驗證。
  • 請參閱 安全性 和 Tailscale。

WhatsApp 登入流程（遠端）

  • 在遠端主機上執行 openclaw channels login --verbose。使用手機上的 WhatsApp 掃描 QR 碼。
  • 驗證過期時在該主機上重新執行登入。健康檢查會顯示連結問題。

疑難排解

  • exit 127 / not found：openclaw 不在非登入 shell 的 PATH 中。加入 /etc/paths、你的 shell rc，或 symlink 至 /usr/local/bin//opt/homebrew/bin。
  • Health probe failed：檢查 SSH 連線、PATH，以及 Baileys 是否已登入（openclaw status --json）。
  • Web Chat 卡住：確認遠端主機上 Gateway 正在運行，且轉發的連接埠與 Gateway WS 連接埠相符；UI 需要健康的 WS 連線。
  • Node IP 顯示 127.0.0.1：SSH tunnel 的預期行為。若希望 Gateway 看到真實客戶端 IP，將 Transport 切換至 Direct (ws/wss)。
  • Voice Wake：觸發詞組在遠端模式下會自動轉發；不需要獨立的轉發器。

通知音效

透過 openclaw 和 node.invoke 的腳本為每個通知選擇音效，例如：

openclaw nodes notify --node <id> --title "Ping" --body "Remote gateway ready" --sound Glass

應用程式中已不再有全域的「預設音效」切換；呼叫者為每個請求選擇音效（或不使用音效）。

arrow_back
上一頁
Permissions
下一頁
Signing
arrow_forward