远程访问（SSH、隧道和 tailnet�?

此仓库通过让单�?Gateway（主站）在专用主机上运行并连接客户端来支�?远程 SSH”�?

对于 **operators（您/macOS 应用�?*：SSH 隧道是通用后备�?
对于 节点（iOS/Android 和未来设备）：连接到 Gateway WebSocket（根据需要使�?LAN/tailnet �?SSH 隧道）�?

核心思路

Gateway WebSocket 绑定到您配置端口上的回环（默认为 18789）�?
对于远程使用，您通过 SSH 转发该回环端口（或使�?tailnet/VPN 并减少隧道）�?

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

�?Gateway 主机视为”代理所在的位置”。它拥有会话、认证配置文件、渠道和状态�? 您的笔记本电�?桌面（和节点）连接到该主机�?

1) 在您�?tailnet 中始终运行的 Gateway（VPS 或家用服务器�?

在持久化主机上运�?Gateway 并通过 Tailscale �?SSH 访问它�?

**最佳用户体验：**保持 gateway.bind: "loopback" 并使�?Tailscale Serve 提供控制 UI�?
**后备�?*保持回环 + 从任何需要访问的机器进行 SSH 隧道�?
*示例�? exe.dev（简�?VM）或 Hetzner（生�?VPS）�?

当您的笔记本电脑经常睡眠但您希望代理始终在线时，这是理想的�?

2) 家用桌面运行 Gateway，笔记本电脑是远程控�?

笔记本电�?*�?*运行代理。它远程连接�?

使用 macOS 应用�?远程 SSH 模式*（设�?�?常规 �?”OpenClaw 运行”）�?
应用打开并管理隧道，因此 WebChat + 健康检�?正常工作”�?

运行手册：macOS 远程访问�?

3) 笔记本电脑运�?Gateway，从其他机器远程访问

保持 Gateway 本地但安全地暴露它：

从其他机�?SSH 隧道到笔记本电脑，或
Tailscale Serve 控制 UI 并保�?Gateway 仅回环�?

指南：Tailscale �?Web 概述�?

命令流程（什么在哪里运行�?

一�?Gateway 服务拥有状�?+ 渠道。节点是外设�?

流程示例（Telegram �?节点）：

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

注意�?

**节点不运�?Gateway 服务�?*每个主机只应运行一�?Gateway，除非您故意运行隔离的配置（请参阅多个 Gateway）�?
macOS 应用”节点模式”只是 Gateway WebSocket 上的节点客户端�?

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 仅回环时，将 URL 保持�?ws://127.0.0.1:18789 并首先打开 SSH 隧道�?

凭据优先�?

Gateway 调用/探测凭据解析现在遵循一个共享合约：

显式凭据（--token、--password 或工�?gatewayToken）始终优先�?
本地模式默认值：
- 令牌：OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token -> gateway.remote.token
- 密码：OPENCLAW_GATEWAY_PASSWORD -> gateway.auth.password -> gateway.remote.password
远程模式默认值：
- 令牌：gateway.remote.token -> OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token
- 密码：OPENCLAW_GATEWAY_PASSWORD -> gateway.remote.password -> gateway.auth.password
远程探测/状态令牌检查默认是严格的：当定位远程模式时，它们仅使用 gateway.remote.token（无本地令牌后备）�?
旧版 CLAWDBOT_GATEWAY_* 环境变量仅由兼容性调用路径使用；探测/状�?认证解析仅使�?OPENCLAW_GATEWAY_*�?

通过 SSH 的聊�?UI

WebChat 不再使用单独�?HTTP 端口。SwiftUI 聊天 UI 直接连接�?Gateway WebSocket�?

通过 SSH 转发 18789（见上文），然后将客户端连接�?ws://127.0.0.1:18789�?
�?macOS 上，优先使用应用�?远程 SSH”模式，它自动管理隧道�?

macOS 应用”远程 SSH”

macOS 菜单栏应用可以端到端驱动相同的设置（远程状态检查、WebChat 和语音唤醒转发）�?

运行手册：macOS 远程访问�?

安全规则（远�?VPN�?

简短版本：**保持 Gateway 仅回�?*，除非您确定需要绑定�?

回环 + SSH/Tailscale Serve 是最安全的默认值（无公开暴露）�?
**非回环绑�?*（lan/tailnet/custom，或当回环不可用时的 auto）必须使用认证令�?密码�?
gateway.remote.token / .password 是客户端凭据来源。它�?*�?*自行配置服务器认证�?
�?gateway.auth.* 未设置时，本地调用路径可以使�?gateway.remote.* 作为后备�?
gateway.remote.tlsFingerprint 在使�?wss:// 时固定远�?TLS 证书�?
Tailscale Serve 可以�?gateway.auth.allowTailscale: true 时通过身份验证头认证控�?UI/WebSocket 流量；HTTP API 端点仍然需要令�?密码认证。此无令牌流程假�?Gateway 主机�? 受信任的。如果您希望到处使用令牌/密码，请将其设置�?false�?
像操作员访问一样对待浏览器控制：仅 tailnet + 故意节点配对�?

深入了解：安全�?