Skip to main content
此仓库通过在专用主机（桌面/服务器）上保持单个 Gateway（主节点）运行，并将客户端连接到它，来支持远程网关访问。
  • 对于 操作者（你 / macOS 应用）：当网关可达时，直接使用 LAN/Tailnet WebSocket 是最简单的；SSH 隧道是通用的兜底方案。
  • 对于 节点（iOS/Android 和未来设备）：连接到 Gateway WebSocket（按需通过 LAN/tailnet 或 SSH 隧道）。

​
核心思路

  • Gateway WebSocket 通常绑定到你所配置端口上的 loopback（默认为 18789）。
  • 对于远程使用，可通过 Tailscale Serve 或受信任的 LAN/Tailnet 绑定将其暴露，或者通过 SSH 将 loopback 端口转发出去。

​
常见的 VPN 和 tailnet 方案

把 Gateway 主机 看作 agent 所在的位置。它拥有会话、身份验证配置、通道和状态。你的笔记本、台式机以及节点都连接到这台主机。

​
在你的 tailnet 中始终在线的 Gateway

在持久化主机（VPS 或家用服务器）上运行 Gateway，并通过 Tailscale 或 SSH 访问它。
  • 最佳体验： 保持 gateway.bind: "loopback"，并为 Control UI 使用 Tailscale Serve。
  • 受信任的 LAN/Tailnet： 将 gateway 绑定到私有接口，并使用 gateway.remote.transport: "direct" 直接连接。
  • 兜底方案： 保持 loopback，并从任何需要访问的机器建立 SSH 隧道。
  • 示例： exe.dev（易用的 VM）或 Hetzner（生产环境 VPS）。
适用于你的笔记本经常休眠、但又希望 agent 一直在线的场景。

​
家用桌面运行 Gateway

笔记本不运行 agent。它通过远程方式连接：
  • 使用 macOS 应用的远程模式（Settings → General → OpenClaw runs）。
  • 当网关在 LAN/Tailnet 上可达时，应用会直接连接；当你选择 SSH 时，则会打开并管理 SSH 隧道。
运行手册：macOS 远程访问。

​
笔记本运行 Gateway

保持 Gateway 在本地运行，但安全地对外提供访问：
  • 从其他机器通过 SSH 隧道连接到这台笔记本，或者
  • 使用 Tailscale Serve 提供 Control UI，并让 Gateway 仅绑定 loopback。
指南：Tailscale 和 Web 概览。

​
命令流（哪些东西运行在哪里）

一个 gateway 服务负责状态 + 通道。节点只是外围设备。 流程示例（Telegram → 节点）：
  • Telegram 消息到达 Gateway。
  • Gateway 运行 agent，并决定是否调用节点工具。
  • Gateway 通过 Gateway WebSocket（node.* RPC）调用 node。
  • Node 返回结果；Gateway 再把回复发回 Telegram。
说明：
  • 节点不运行 gateway 服务。 除非你有意运行隔离配置文件（参见 多个 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、openclaw gateway health、openclaw gateway probe 和 openclaw gateway 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 隧道。 在 macOS 应用的 SSH 隧道传输中，检测到的 gateway 主机名应放在 gateway.remote.sshTarget 中；gateway.remote.url 仍然是本地隧道 URL。 如果这些端口不同，请将 gateway.remote.remotePort 设为 SSH 主机上的 gateway 端口。 对于已经能在受信任的 LAN 或 Tailnet 上访问的 gateway，请使用直接模式： 
{
  gateway: {
    mode: "remote",
    remote: {
      transport: "direct",
      url: "ws://192.168.0.202:18789",
      token: "your-token",
    },
  },
}

​
凭据优先级

Gateway 凭据解析在 call/probe/status 路径以及 Discord exec-approval 监控中遵循同一共享契约。Node-host 使用相同的基础契约，但有一个本地模式例外（它会有意忽略 gateway.remote.*）：
  • 显式凭据（--token、--password 或工具 gatewayToken）总是在接受显式认证的 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 输入未设置时适用）
    • 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 环境覆盖只使用 OPENCLAW_GATEWAY_*。

​
Chat UI 远程访问

WebChat 不再使用单独的 HTTP 端口。SwiftUI 聊天 UI 直接连接到 Gateway WebSocket。
  • 通过 SSH 转发 18789（见上文），然后将客户端连接到 ws://127.0.0.1:18789。
  • 对于 LAN/Tailnet 直接模式，将客户端连接到已配置的私有 ws:// 或安全的 wss:// URL。
  • 在 macOS 上，优先使用应用的远程模式，它会自动管理所选传输方式。

​
macOS 应用远程模式

macOS 菜单栏应用可以端到端驱动同一套配置（远程状态检查、WebChat 和 Voice Wake 转发）。 运行手册：macOS 远程访问。

​
安全规则（远程/VPN）

简短版：保持 Gateway 仅绑定 loopback，除非你确定需要绑定到其他地址。
  • Loopback + SSH/Tailscale Serve 是最安全的默认方案（不会公开暴露）。
  • 明文 ws:// 仅接受用于 loopback、LAN、link-local、.local、.ts.net 以及 Tailscale CGNAT 主机。公共远程主机必须使用 wss://。
  • 非 loopback 绑定（lan/tailnet/custom，或在 loopback 不可用时的 auto）必须使用 gateway 身份验证：token、password，或带有 gateway.auth.mode: "trusted-proxy" 的身份感知反向代理。
  • gateway.remote.token / .password 是客户端凭据来源。它们本身不会配置服务器认证。
  • 本地 call 路径仅在 gateway.auth.* 未设置时才可将 gateway.remote.* 作为回退。
  • 如果 gateway.auth.token / gateway.auth.password 通过 SecretRef 显式配置且未解析，则解析会失败关闭（不会被远程回退掩盖）。
  • 在使用 wss:// 时，gateway.remote.tlsFingerprint 会固定远程 TLS 证书，包括 macOS 直接模式。如果没有配置或之前已存储的 pin，macOS 只会在正常系统信任通过后固定首次使用的证书；自签名或私有 CA 的 gateway 若 macOS 尚不信任，则需要显式指纹或通过 SSH 的远程访问。
  • Tailscale Serve 可通过身份头认证 Control UI/WebSocket 流量，前提是 gateway.auth.allowTailscale: true；HTTP API 端点不会使用该 Tailscale 头认证，而是遵循 gateway 的常规 HTTP 认证模式。这种无 token 流程假设 gateway 主机是可信的。如果你希望所有地方都使用共享密钥认证，请将其设为 false。
  • Trusted-proxy 认证默认期望非 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
隧道会在登录时自动启动，在崩溃后重启，并保持转发端口持续可用。
如果你从旧配置中遗留了 com.openclaw.ssh-tunnel LaunchAgent，请将其卸载并删除。

​
故障排查

检查隧道是否正在运行： 
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 -NSSH 不执行远程命令（仅端口转发）
KeepAlive如果隧道崩溃，自动重启它
RunAtLoad在 LaunchAgent 于登录时加载时启动隧道

​
相关内容