OpenClaw 🦞

远程访问

远程访问（SSH、隧道和 tailnet）

此仓库支持"通过 SSH 远程"，方法是在专用主机（桌面/服务器）上运行单个网关（主节点）并让客户端连接到它。

  • 对于operators（你 / macOS 应用）：SSH 隧道是通用回退方案。
  • 对于nodes（iOS/Android 和未来设备）：连接到网关WebSocket（根据需要选择 LAN/tailnet 或 SSH 隧道）。

核心思想

  • 网关 WebSocket 绑定到你配置的端口上的环回地址（默认为 18789）。
  • 对于远程使用，你通过 SSH 转发该环回端口（或使用 tailnet/VPN 并减少隧道使用）。

常见 VPN/tailnet 设置（代理所在位置）

将网关机视为"代理所在的位置"。它拥有会话、auth 配置文件、channels 和状态。你的笔记本/台式机（和节点）连接到该主机。

1) tailnet 中的常开网关（VPS 或家庭服务器）

在持久主机上运行网关并通过Tailscale或 SSH 访问它。

  • 最佳体验： 保持 gateway.bind: "loopback" 并使用Tailscale Serve来提供 Control UI。
  • 回退方案： 保持环回 + 从任何需要访问的机器通过 SSH 隧道。
  • 示例： exe.dev（简易 VM）或 Hetzner（生产 VPS）。

当你的笔记本经常休眠但你希望代理始终在线时，这是理想选择。

2) 家庭台式机运行网关，笔记本作为远程控制

笔记本不运行代理。它远程连接：

  • 使用 macOS 应用的Remote over SSH模式（设置 → 常规 → "OpenClaw 运行位置"）。
  • 应用打开并管理隧道，因此 WebChat + 健康检查"正常工作"。

操作手册：macOS 远程访问。

3) 笔记本运行网关，从其他机器远程访问

保持网关本地但安全地暴露它：

  • 从其他机器通过 SSH 隧道连接到笔记本，或
  • 使用 Tailscale Serve 提供 Control UI 并保持网关仅限环回。

指南：Tailscale 和 Web 概览。

命令流（在哪里运行什么）

一个网关服务拥有状态 + channels。节点是外围设备。

流程示例（Telegram → 节点）：

  • Telegram 消息到达网关。
  • 网关运行代理并决定是否调用节点工具。
  • 网关通过网关 WebSocket（node.* RPC）调用节点。
  • 节点返回结果；网关回复回 Telegram。

注意：

  • 节点不运行网关服务。 每台主机只应运行一个网关，除非你有意运行隔离的配置文件（参见 多个网关）。
  • macOS 应用"节点模式"只是通过网关 WebSocket 连接的节点客户端。

SSH 隧道（CLI + 工具）

创建到远程网关 WS 的本地隧道：

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

隧道建立后：

  • openclaw health 和 openclaw status --deep 现在通过 ws://127.0.0.1:18789 访问远程网关。
  • openclaw gateway {status,health,send,agent,call} 也可以通过 --url 在需要时定位到转发的 URL。

注意：将 18789 替换为你配置的 gateway.port（或 --port/OPENCLAW_GATEWAY_PORT）。 注意：当你传递 --url 时，CLI 不会回退到配置或环境凭据。 显式包含 --token 或 --password。缺少显式凭据会报错。

CLI 远程默认值

你可以持久化远程目标，以便 CLI 命令默认使用它：

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

当网关仅限环回时，将 URL 保持为 ws://127.0.0.1:18789 并首先打开 SSH 隧道。

凭据优先级

网关调用/探测凭据解析现在遵循一个共享约定：

  • 显式凭据（--token、--password 或工具 gatewayToken）始终优先。
  • 本地模式默认值：
    • token：OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token -> gateway.remote.token
    • password：OPENCLAW_GATEWAY_PASSWORD -> gateway.auth.password -> gateway.remote.password
  • 远程模式默认值：
    • token：gateway.remote.token -> OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token
    • password：OPENCLAW_GATEWAY_PASSWORD -> gateway.remote.password -> gateway.auth.password
  • 远程探测/状态 token 检查默认是严格的：当定位到远程模式时，它们仅使用 gateway.remote.token（没有本地 token 回退）。
  • 传统 CLAWDBOT_GATEWAY_* 环境变量仅由兼容性调用路径使用；探测/状态/auth 解析仅使用 OPENCLAW_GATEWAY_*。

通过 SSH 的 Chat UI

WebChat 不再使用单独的 HTTP 端口。SwiftUI chat UI 直接连接到网关 WebSocket。

  • 通过 SSH 转发 18789（见上文），然后将客户端连接到 ws://127.0.0.1:18789。
  • 在 macOS 上，优先使用应用的"Remote over SSH"模式，它会自动管理隧道。

macOS 应用"Remote over SSH"

macOS 菜单栏应用可以端到端地驱动相同的设置（远程状态检查、WebChat 和 Voice Wake 转发）。

操作手册：macOS 远程访问。

安全规则（远程/VPN）

简而言之：保持网关仅限环回，除非你确定需要绑定。

  • 环回 + SSH/Tailscale Serve 是最安全的默认设置（无公开暴露）。
  • 明文 ws:// 默认仅限环回。对于受信任的私有网络，在客户端进程上设置 OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 作为紧急措施。
  • 非环回绑定（lan/tailnet/custom，或当环回不可用时的 auto）必须使用 auth tokens/passwords。
  • gateway.remote.token / .password 是客户端凭据来源。它们本身不配置服务器认证。
  • 当 gateway.auth.* 未设置时，本地调用路径可以将 gateway.remote.* 用作回退。
  • 当使用 wss:// 时，gateway.remote.tlsFingerprint pin 远程 TLS 证书。
  • Tailscale Serve 可以在启用 gateway.auth.allowTailscale: true 时通过身份头认证 Control UI/WebSocket 流量；HTTP API 端点仍然需要 token/password 认证。此无 token 流程假设网关主机是受信任的。如果你希望 everywhere 都使用 tokens/passwords，请将其设置为 false。
  • 将浏览器控制视为 operator 访问：仅限 tailnet + 故意的节点配对。

深入探讨：安全。