English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

远程访问

远程访问

此仓库通过在专用主机（桌面电脑/服务器）上运行单个 Gateway 网关（主节点），并让客户端连接到它，支持“通过 SSH 远程访问”。

  • 对于操作端（你 / macOS 应用）：SSH 隧道是通用回退方案。
  • 对于节点（iOS/Android 和未来设备）：按需连接到 Gateway 网关 WebSocket（LAN/tailnet 或 SSH 隧道）。

核心思路

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

常见 VPN 和 tailnet 设置

将 Gateway 网关主机视为 agent 所在的位置。它拥有会话、认证配置、渠道和状态。你的笔记本电脑、桌面电脑和节点会连接到这台主机。

在你的 tailnet 中始终运行的 Gateway 网关

在持久主机（VPS 或家庭服务器）上运行 Gateway 网关，并通过 Tailscale 或 SSH 访问它。

  • 最佳体验： 保持 gateway.bind: "loopback"，并为控制 UI 使用 Tailscale Serve。
  • 回退方案： 保持 loopback，并从任何需要访问的机器建立 SSH 隧道。
  • 示例： exe.dev（易用 VM）或 Hetzner（生产 VPS）。

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

家庭桌面电脑运行 Gateway 网关

笔记本电脑不运行 agent。它远程连接：

  • 使用 macOS 应用的通过 SSH 远程访问模式（Settings → General → OpenClaw runs）。
  • 应用会打开并管理隧道，因此 WebChat 和健康检查可以直接工作。

运行手册：macOS 远程访问。

笔记本电脑运行 Gateway 网关

保持 Gateway 网关在本地运行，但安全地暴露它：

  • 从其他机器通过 SSH 隧道连接到笔记本电脑，或
  • 使用 Tailscale Serve 暴露控制 UI，并让 Gateway 网关仅绑定 loopback。

指南：Tailscale 和 Web 概览。

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

一个 gateway 服务拥有状态 + 渠道。节点是外围设备。

流程示例（Telegram → 节点）：

  • Telegram 消息到达 Gateway 网关。
  • Gateway 网关运行 agent，并决定是否调用节点工具。
  • 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、openclaw gateway health、openclaw gateway probe 和 openclaw gateway call 也可以在需要时通过 --url 指向转发后的 URL。

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 隧道。 在 macOS 应用的 SSH 隧道传输中，发现的 gateway 主机名属于 gateway.remote.sshTarget；gateway.remote.url 仍然是本地隧道 URL。

凭证优先级

Gateway 网关凭证解析在 call/probe/status 路径和 Discord 执行审批监控中遵循一套共享契约。Node-host 使用相同的基础契约，但有一个本地模式例外（它会有意忽略 gateway.remote.*）：

  • 显式凭证（--token、--password 或工具 gatewayToken）在接受显式认证的调用路径上始终优先。
  • URL 覆盖安全性：
    • CLI URL 覆盖（--url）永远不会复用隐式 config/env 凭证。
    • Env URL 覆盖（OPENCLAW_GATEWAY_URL）只能使用 env 凭证（OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD）。
  • 本地模式默认值：
    • token: OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token -> gateway.remote.token（仅当本地 auth token 输入未设置时才应用远程回退）
    • password: OPENCLAW_GATEWAY_PASSWORD -> gateway.auth.password -> gateway.remote.password（仅当本地 auth password 输入未设置时才应用远程回退）
  • 远程模式默认值：
    • token: gateway.remote.token -> OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token
    • password: OPENCLAW_GATEWAY_PASSWORD -> gateway.remote.password -> gateway.auth.password
  • Node-host 本地模式例外：gateway.remote.token / gateway.remote.password 会被忽略。
  • 远程 probe/status token 检查默认严格：在指向远程模式时，它们只使用 gateway.remote.token（没有本地 token 回退）。
  • Gateway 网关 env 覆盖只使用 OPENCLAW_GATEWAY_*。

通过 SSH 使用聊天 UI

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

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

macOS 应用通过 SSH 远程访问

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

运行手册：macOS 远程访问。

安全规则（远程/VPN）

简短版本：除非你确定需要绑定，否则保持 Gateway 网关仅限 loopback。

  • Loopback + SSH/Tailscale Serve 是最安全的默认方式（不公开暴露）。
  • 明文 ws:// 默认仅限 loopback。对于受信任的专用网络， 在客户端进程上设置 OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 作为 break-glass。没有对应的 openclaw.json 设置；这必须是建立 WebSocket 连接的客户端进程 环境。
  • 非 loopback 绑定（lan/tailnet/custom，或 loopback 不可用时的 auto）必须使用 gateway auth：token、password，或带有 gateway.auth.mode: "trusted-proxy" 的身份感知反向代理。
  • gateway.remote.token / .password 是客户端凭证来源。它们本身不会配置服务器认证。
  • 仅当 gateway.auth.* 未设置时，本地调用路径才可以使用 gateway.remote.* 作为回退。
  • 如果通过 SecretRef 显式配置了 gateway.auth.token / gateway.auth.password 但无法解析，解析会关闭失败（不会用远程回退掩盖）。
  • 使用 wss:// 时，gateway.remote.tlsFingerprint 会固定远程 TLS 证书。
  • Tailscale Serve 可以在 gateway.auth.allowTailscale: true 时通过身份 标头认证控制 UI/WebSocket 流量；HTTP API 端点不使用 该 Tailscale 标头认证，而是遵循 gateway 的常规 HTTP auth 模式。这个无 token 流程假定 gateway 主机可信。如果你希望所有地方都使用共享密钥认证，请将其设为 false。
  • Trusted-proxy auth 默认预期非 loopback 的身份感知代理设置。 同主机 loopback 反向代理需要显式设置 gateway.auth.trustedProxy.allowLoopback = true。
  • 将浏览器控制视为操作端访问：仅限 tailnet + 有意的节点配对。

深入说明：安全。

macOS：通过 LaunchAgent 持久化 SSH 隧道

对于连接到远程 gateway 的 macOS 客户端，最简单的持久化设置是使用 SSH LocalForward 配置项，再加上一个 LaunchAgent，以便在重启和崩溃后保持隧道存活。

步骤 1：添加 SSH 配置

编辑 ~/.ssh/config：

Host remote-gateway
    HostName <REMOTE_IP>
    User <REMOTE_USER>
    LocalForward 18789 127.0.0.1:18789
    IdentityFile ~/.ssh/id_rsa

将 <REMOTE_IP> 和 <REMOTE_USER> 替换为你的值。

步骤 2：复制 SSH 密钥（一次性）

ssh-copy-id -i ~/.ssh/id_rsa <REMOTE_USER>@<REMOTE_IP>

步骤 3：配置 gateway token

将 token 存储到配置中，使其在重启后仍然保留：

openclaw config set gateway.remote.token "<your-token>"

步骤 4：创建 LaunchAgent

将其保存为 ~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>ai.openclaw.ssh-tunnel</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/bin/ssh</string>
        <string>-N</string>
        <string>remote-gateway</string>
    </array>
    <key>KeepAlive</key>
    <true/>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>

步骤 5：加载 LaunchAgent

launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist

隧道会在登录时自动启动，崩溃后重启，并保持转发端口可用。

故障排除

检查隧道是否正在运行：

ps aux | grep "ssh -N remote-gateway" | grep -v grep
lsof -i :18789

重启隧道：

launchctl kickstart -k gui/$UID/ai.openclaw.ssh-tunnel

停止隧道：

launchctl bootout gui/$UID/ai.openclaw.ssh-tunnel
配置项 作用
LocalForward 18789 127.0.0.1:18789 将本地端口 18789 转发到远程端口 18789
ssh -N 不执行远程命令的 SSH（仅端口转发）
KeepAlive 如果隧道崩溃，会自动重启隧道
RunAtLoad LaunchAgent 在登录时加载后启动隧道

相关