遠端控制

此流程可讓 macOS App 作為完整的遠端控制工具，用於控制在另一台主機（桌上型電腦／伺服器）上執行的 OpenClaw 閘道。App 可直接連線至受信任的 LAN／Tailnet 閘道 URL；若遠端閘道僅限回送介面，則可管理 SSH 通道。健康狀態檢查、語音喚醒轉送和 Web Chat 會重複使用 Settings -> General 中的相同遠端設定。

​

模式

• 本機（這台 Mac）：所有項目都在筆記型電腦上執行；不涉及 SSH。
• 透過 SSH 遠端連線（預設）：OpenClaw 命令會在遠端主機上執行。App 會使用 -o BatchMode、你選擇的身分／金鑰和本機連接埠轉送來開啟 SSH 連線。
• 遠端直接連線（ws/wss）：不使用 SSH 通道；App 會直接連線至閘道 URL（LAN、Tailscale、Tailscale Serve 或公開的 HTTPS 反向 Proxy）。

​

遠端傳輸方式

• SSH 通道（預設）：使用 ssh -N -L ... 將閘道連接埠轉送至 localhost。由於通道使用回送介面，閘道會將節點的 IP 視為 127.0.0.1。
• 直接連線（ws/wss）：直接連線至閘道 URL。閘道會看到真實的用戶端 IP。

App 會針對自身的 SSH 程序停用 SSH 連線多工和驗證後背景化，以便監控並重新啟動該確切程序，即使所選別名已啟用 ControlMaster 或 ForkAfterAuthentication 亦然。

由於閘道認證資訊會透過此通道傳輸，因此 SSH 主機金鑰驗證預設為嚴格模式。若要改用受管理 SSH 別名本身的信任行為，請透過 openclaw-mac configure-remote 設定 --ssh-host-key-policy openssh，或直接將 gateway.remote.sshHostKeyPolicy 設為 "openssh"。選擇加入前，請檢查該別名，以及任何相符的 Host * 或系統設定。在 App 中或透過 configure-remote 變更 SSH 目標後，除非你明確針對新目標再次選擇加入，否則原則會重設為 strict。

在 SSH 通道模式下，探索到的 LAN／Tailnet 主機名稱會儲存為 gateway.remote.sshTarget。App 會將 gateway.remote.url 保留在本機通道端點（例如 ws://127.0.0.1:18789），讓命令列介面、Web Chat 和本機節點主機服務全都使用相同的回送傳輸方式。當探索同時傳回原始 Tailnet IP 和穩定的主機名稱時，App 會優先使用 Tailscale MagicDNS 或 LAN 名稱，讓連線在位址變更後更能持續運作。如果本機通道連接埠與遠端閘道連接埠不同，請將 gateway.remote.remotePort 設為遠端主機上的連接埠。

遠端模式中的瀏覽器自動化由命令列介面的節點主機擁有，而非原生 macOS App 節點。App 會在可行時啟動已安裝的節點主機服務；若要從該 Mac 啟用瀏覽器控制，請使用 openclaw node install ... 和 openclaw node start 安裝／啟動服務（或在前景執行 openclaw node run ...），然後指定該支援瀏覽器功能的節點。

​

遠端主機的必要條件

1. 安裝 Node + pnpm，並建置／安裝 OpenClaw 命令列介面（pnpm install && pnpm build && pnpm link --global）。
2. 確保非互動式 Shell 的 PATH 中包含 openclaw（如有需要，建立指向 /usr/local/bin 或 /opt/homebrew/bin 的符號連結）。
3. 使用 SSH 傳輸時：設定金鑰式 SSH 驗證。若要在 LAN 外維持穩定連線，建議使用 Tailscale IP。

​

macOS App 設定

若要略過歡迎流程並透過 SSH 預先設定 App：

openclaw-mac configure-remote \
  --ssh-target user@gateway-host \
  --local-port 18789 \
  --remote-port 18789 \
  --token "$OPENCLAW_GATEWAY_TOKEN"

或者，如果受信任的 LAN 或 Tailnet 已可連線至閘道，可完全略過 SSH：

openclaw-mac configure-remote \
  --direct-url ws://192.168.0.202:18789 \
  --token "$OPENCLAW_GATEWAY_TOKEN"

openclaw-mac connect、wizard 和 configure-remote 會依下列順序解析使用中的設定：OPENCLAW_CONFIG_PATH，接著是 $OPENCLAW_STATE_DIR/openclaw.json，最後是 ~/.openclaw/openclaw.json。兩種設定形式都會寫入該使用中檔案、將新手引導標記為已完成，並讓 App 在下次啟動時管理所選傳輸方式。--local-port／--remote-port 的預設值為 18789。其他旗標：--password、--identity <path>、--ssh-host-key-policy <strict|openssh>、--project-root <path>、--cli-path <path>、--json。執行 openclaw-mac configure-remote --help 以查看完整參考資訊。

若要改從 UI 設定：

1. 開啟 Settings -> General。
2. 在 OpenClaw runs 下選擇 Remote，並設定：
   • Transport：SSH tunnel 或 Direct (ws/wss)。
   • SSH target：user@host（可選的 :port）。如果閘道位於同一個 LAN 並透過 Bonjour 公告，請從探索到的清單中選取，以自動填入此欄位。
   • Gateway URL（僅限 Direct）：wss://gateway.example.ts.net（本機／LAN 則使用 ws://...）。
   • Identity file（進階）：你的金鑰路徑。
   • Project root（進階）：用於執行命令的遠端簽出路徑。
   • CLI path（進階）：可執行之 openclaw 進入點／二進位檔的選用路徑（公告時會自動填入）。
3. 按下 Test remote。成功表示遠端 openclaw status --json 已正確執行。失敗通常表示 PATH／命令列介面有問題；結束碼 127 表示在遠端找不到命令列介面。
4. 健康狀態檢查和 Web Chat 現在會自動透過所選傳輸方式執行。

​

Web Chat

• SSH 通道：透過轉送的 WebSocket 控制連接埠（預設為 18789）連線至閘道。
• 直接連線（ws/wss）：直接連線至已設定的閘道 URL。
• 沒有獨立的 Web Chat HTTP 伺服器。

​

權限

• 遠端主機需要與本機相同的 TCC 核准（Automation、Accessibility、Screen Recording、Microphone、Speech Recognition、Notifications）。在該機器上執行一次新手引導以授予這些權限。
• 節點會透過 node.list／node.describe 公告其權限狀態，讓代理程式知道有哪些功能可用。

​

安全性注意事項

• 遠端主機應優先繫結至回送介面，並透過 SSH、Tailscale Serve 或受信任的 Tailnet／LAN 直接 URL 連線。
• SSH 通道預設要求使用已受信任的主機金鑰。請先信任主機金鑰（將其加入已設定的 known-hosts 檔案），或針對你接受其 OpenSSH 信任原則的受管理別名，明確設定 gateway.remote.sshHostKeyPolicy: "openssh"。
• 如果將閘道繫結至非回送介面，必須要求有效的閘道驗證：權杖、密碼，或搭配 gateway.auth.mode: "trusted-proxy" 的身分感知反向 Proxy。
• 直接 wss:// 連線會對操作員／控制流量和 Mac 隨附節點套用同一套憑證原則。設定 gateway.remote.tlsFingerprint 以明確固定憑證。若未設定，App 只會在通過一般 macOS 信任驗證後，記錄首次使用時的固定憑證。
• 請參閱安全性和 Tailscale。

​

WhatsApp 登入流程（遠端）

• 在遠端主機上執行 openclaw channels login --channel whatsapp --verbose。使用手機上的 WhatsApp 掃描 QR Code。
• 如果驗證過期，請在該主機上重新執行登入。健康狀態檢查會顯示連結問題。

​

疑難排解

症狀	原因／修正方式
exit 127／找不到	非登入 shell 的 PATH 中沒有 openclaw。請將它加入 /etc/paths、你的 shell rc，或建立符號連結至 /usr/local/bin//opt/homebrew/bin。
健康狀態探測失敗	檢查 SSH 是否可連線、PATH，以及 Baileys (WhatsApp) 是否已登入（openclaw status --json）。
網頁聊天卡住	確認閘道正在遠端主機上執行，且轉送的連接埠與閘道 WS 連接埠相符；使用者介面需要正常的 WS 連線。
節點 IP 顯示 127.0.0.1	使用 SSH 通道時屬於預期行為。若要讓閘道看到真實的用戶端 IP，請將 Transport 切換為 Direct (ws/wss)。
儀表板可用，但 Mac 功能離線	操作端／控制連線正常，但隨附的節點連線尚未連線，或缺少其命令介面。開啟選單列的裝置區段，並檢查 Mac 是否為 paired · disconnected。直接 wss:// 操作端和節點連線會使用相同的已設定或已儲存憑證政策。對於受信任的 wss://*.ts.net Tailscale Serve 端點，憑證輪替後，過期的已儲存葉憑證釘選會被取代，並自動重試。已設定的釘選絕不會自動輪替；請在檢閱新憑證後更新 gateway.remote.tlsFingerprint，或切換為 Remote over SSH。
語音喚醒	在遠端模式下，觸發詞會自動轉送；不需要個別的轉送程式。

​

通知音效

使用 openclaw nodes notify 從指令碼中為每則通知選擇音效，例如：

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

應用程式中沒有全域預設音效切換選項；呼叫端會為每個請求選擇音效（或不使用音效）。

​

相關內容

• macOS 應用程式
• 遠端存取