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

本项目通过"远程 over SSH"方式支持远程访问：在专用宿主机（桌面/服务器）上运行一个 Gateway（主节点），客户端连接到它即可。

• 对于 operator（你/macOS 应用）：SSH 隧道是通用后备方案。
• 对于 node（iOS/Android 及未来设备）：直接连接到 Gateway WebSocket（局域网/tailnet 或按需 SSH 隧道）。

核心思路

• Gateway WebSocket 绑定到宿主机的 loopback，默认端口 18789。
• 远程使用时，通过 SSH 转发该 loopback 端口（或使用 tailnet/VPN 减少隧道需求）。

常见 VPN/tailnet 部署场景（龙虾住在哪里）

将 Gateway 宿主机理解为"我的龙虾的家"——它持有会话、auth profiles、频道和状态。你的笔记本/台式机（及节点）连接到这台宿主机。

1）always-on Gateway 部署在 tailnet 中（VPS 或家庭服务器）

在持久宿主机上运行 Gateway，通过 Tailscale 或 SSH 访问。

• 最佳体验：保持 gateway.bind: "loopback"，使用 Tailscale Serve 暴露控制 UI。
• 后备方案：保持 loopback + 从任意需要访问的机器建立 SSH 隧道。
• 示例：exe.dev（简单 VM）或 Hetzner（生产 VPS）。

适合笔记本频繁休眠、但希望 Agent 保持 always-on 的场景。

2）家用台式机运行 Gateway，笔记本远程控制

笔记本不运行 Agent，而是通过远程方式控制：

• 使用 macOS 应用的 Remote over SSH 模式（设置 → 通用 → "OpenClaw runs"）。
• 应用会自动建立和管理隧道，WebChat 和健康检查"开箱即用"。

操作手册：macOS 远程访问。

3）笔记本运行 Gateway，其他机器远程访问

将 Gateway 保持在本地但安全暴露：

• 从其他机器通过 SSH 隧道连接到笔记本，或
• 用 Tailscale Serve 暴露控制 UI，Gateway 保持 loopback-only。

指南：Tailscale 和 Web 概览。

命令流向（各组件分工）

一个 Gateway 服务持有状态和频道，Node 是外围设备。

流程示例（Telegram → node）：

• Telegram 消息到达 Gateway。
• Gateway 运行 Agent 并决定是否调用 node 工具。
• Gateway 通过 Gateway WebSocket（node.* RPC）调用 node。
• Node 返回结果，Gateway 将回复发送回 Telegram。

注意事项：

• Node 不运行 Gateway 服务。 除非你有意运行独立 profile（参见多 Gateway），否则每台宿主机只应运行一个 Gateway。
• macOS 应用的"node 模式"只是通过 Gateway WebSocket 连接的一个 node 客户端。

SSH 隧道（CLI + 工具）

创建到远端 Gateway WS 的本地隧道：

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

隧道建立后：

• openclaw health 和 openclaw status --deep 可通过 ws://127.0.0.1:18789 访问远端 Gateway。
• 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",
    },
  },
}

若 Gateway 仅绑定 loopback，URL 保持 ws://127.0.0.1:18789，并先建立 SSH 隧道。

凭据优先级

Gateway 凭据解析遵循一套跨 call/probe/status 路径和 Discord exec-approval 监控的统一规则。Node 宿主使用相同的基础规则，但本地模式有一个例外（会有意忽略 gateway.remote.*）：

• 显式凭据（--token、--password 或工具 gatewayToken）在接受显式 auth 的 call 路径上始终优先。
• URL 覆盖安全规则：
  • CLI URL 覆盖（--url）不复用隐式配置/环境变量凭据。
  • 环境变量 URL 覆盖（OPENCLAW_GATEWAY_URL）只使用环境变量凭据（OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD）。
• 本地模式默认值：
  • token：OPENCLAW_GATEWAY_TOKEN → gateway.auth.token → gateway.remote.token（仅当本地 auth token 输入未设置时才回退到 remote）
  • password：OPENCLAW_GATEWAY_PASSWORD → gateway.auth.password → gateway.remote.password（仅当本地 auth password 输入未设置时才回退到 remote）
• Remote 模式默认值：
  • token：gateway.remote.token → OPENCLAW_GATEWAY_TOKEN → gateway.auth.token
  • password：OPENCLAW_GATEWAY_PASSWORD → gateway.remote.password → gateway.auth.password
• Node 宿主本地模式例外：忽略 gateway.remote.token / gateway.remote.password。
• Remote probe/status token 检查默认严格：在以 remote 模式为目标时，仅使用 gateway.remote.token（无本地 token 回退）。
• Gateway 环境变量覆盖仅使用 OPENCLAW_GATEWAY_*。

通过 SSH 使用 Chat UI

WebChat 不再使用独立的 HTTP 端口，SwiftUI 聊天 UI 直接连接到 Gateway WebSocket。

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

macOS 应用"Remote over SSH"

macOS 菜单栏应用可以端到端处理同一套配置（远端状态检查、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）必须配置 auth token/password。
• gateway.remote.token / .password 是客户端凭据来源，它们本身不配置服务端 auth。
• 仅当 gateway.auth.* 未设置时，本地 call 路径才可使用 gateway.remote.* 作为回退。
• 若 gateway.auth.token / gateway.auth.password 通过 SecretRef 显式配置且解析失败，则解析以失败告终（不回退到 remote）。
• gateway.remote.tlsFingerprint 在使用 wss:// 时固定远端 TLS 证书。
• Tailscale Serve 可在 gateway.auth.allowTailscale: true 时通过 identity headers 认证控制 UI/WebSocket 流量；HTTP API 端点仍需 token/password auth。该无 token 流程假设 gateway 宿主机是受信的。若需要 token/password 全覆盖，请设为 false。
• 将浏览器控制视同 operator 访问：仅限 tailnet + 主动节点配对。

深度解析：Security。