遠端存取（SSH、通道與 tailnet）

此儲存庫支援「透過 SSH 遠端存取」，方法是在專用主機（桌面/伺服器）上保持單一閘道（主閘道）執行，並將客戶端連接到它。

• 對於操作者（你 / macOS 應用程式）：SSH 通道是通用的後備方案。
• 對於節點（iOS/Android 與未來裝置）：連接到閘道 WebSocket（LAN/tailnet 或視需要使用 SSH 通道）。

核心概念

• 閘道 WebSocket 綁定到你配置的埠上的 loopback（預設為 18789）。
• 對於遠端使用，你透過 SSH 轉發該 loopback 埠（或使用 tailnet/VPN 並減少通道使用）。

常見的 VPN/tailnet 設定（代理所在位置）

將閘道主機視為「代理所在位置」。它擁有會話、驗證設定檔、頻道和狀態。 你的筆記型電腦/桌面（和節點）連接到該主機。

1) 在你的 tailnet 中永遠線上的閘道（VPS 或家用伺服器）

在持久主機上執行閘道，並透過 Tailscale 或 SSH 到達它。

• **最佳 UX：**保持 gateway.bind: "loopback" 並使用 Tailscale Serve 作為控制介面。
• **後備方案：**保持 loopback + 從任何需要存取的機器使用 SSH 通道。
• 範例：exe.dev（簡易 VM）或 Hetzner（生產 VPS）。

當你的筆記型電腦經常休眠但你希望代理永遠線上時，這是理想的選擇。

2) 家用桌面執行閘道，筆記型電腦是遠端控制

筆記型電腦不執行代理。它遠端連接：

• 使用 macOS 應用程式的透過 SSH 遠端模式（設定 → 一般 → 「Moltbot 執行」）。
• 應用程式開啟並管理通道，因此 WebChat + 健康檢查「就能運作」。

操作手冊：macOS 遠端存取。

3) 筆記型電腦執行閘道，從其他機器遠端存取

保持閘道本地但安全地暴露它：

• 從其他機器透過 SSH 通道到筆記型電腦，或
• Tailscale Serve 控制介面並保持閘道僅 loopback。

指南：Tailscale 與 Web 總覽。

指令流程（什麼在哪裡執行）

一個閘道服務擁有狀態 + 頻道。節點是周邊設備。

流程範例（Telegram → 節點）：

• Telegram 訊息到達閘道。
• 閘道執行代理並決定是否呼叫節點工具。
• 閘道透過閘道 WebSocket（node.* RPC）呼叫節點。
• 節點返回結果；閘道回覆到 Telegram。

注意事項：

• **節點不執行閘道服務。**除非你有意執行隔離設定檔（參見多個閘道），否則每個主機應該只執行一個閘道。
• macOS 應用程式「節點模式」只是透過閘道 WebSocket 的節點客戶端。

SSH 通道（CLI + 工具）

建立到遠端閘道 WS 的本地通道：

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

通道啟動後：

• moltbot health 和 moltbot status --deep 現在透過 ws://127.0.0.1:18789 到達遠端閘道。
• moltbot gateway {status,health,send,agent,call} 也可以在需要時透過 --url 以轉發的 URL 為目標。

注意：將 18789 替換為你配置的 gateway.port（或 --port/CLAWDBOT_GATEWAY_PORT）。

CLI 遠端預設值

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

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

當閘道僅為 loopback 時，將 URL 保持在 ws://127.0.0.1:18789 並先開啟 SSH 通道。

透過 SSH 的聊天介面

WebChat 不再使用單獨的 HTTP 埠。SwiftUI 聊天介面直接連接到閘道 WebSocket。

• 透過 SSH 轉發 18789（見上文），然後將客戶端連接到 ws://127.0.0.1:18789。
• 在 macOS 上，偏好應用程式的「透過 SSH 遠端」模式，它會自動管理通道。

macOS 應用程式「透過 SSH 遠端」

macOS 選單列應用程式可以端到端驅動相同的設定（遠端狀態檢查、WebChat 與語音喚醒轉發）。

操作手冊：macOS 遠端存取。

安全規則（遠端/VPN）

簡短版本：保持閘道僅 loopback，除非你確定需要綁定。

• Loopback + SSH/Tailscale Serve 是最安全的預設值（無公開暴露）。
• 非 loopback 綁定（lan/tailnet/custom，或當 loopback 不可用時的 auto）必須使用驗證權杖/密碼。
• gateway.remote.token 僅用於遠端 CLI 呼叫——它不啟用本地驗證。
• gateway.remote.tlsFingerprint 在使用 wss:// 時固定遠端 TLS 憑證。
• 當 gateway.auth.allowTailscale: true 時，Tailscale Serve 可以透過身分標頭進行驗證。 如果你想要權杖/密碼，請將其設定為 false。
• 將瀏覽器控制視為操作者存取：僅 tailnet + 有意的節點配對。

深入探討：安全性。