远程访问

OpenClaw 在一台主机上运行一个 Gateway 网关（主节点），并将所有客户端连接到该网关。Gateway 网关负责管理会话、身份验证配置文件、渠道和状态；其他所有组件都是客户端。

• 操作员（你或 macOS 应用）：当 Gateway 网关可访问时，直接使用局域网/Tailnet WebSocket 最简单；SSH 隧道则是通用的后备方案。
• 节点（iOS/Android 和其他设备）：连接到 Gateway 网关的 WebSocket（通过局域网/Tailnet 或 SSH 隧道）。

核心思路

Gateway 网关的 WebSocket 默认绑定到 回环地址，端口为 18789（gateway.port）。如需远程使用，可以通过 Tailscale Serve / 受信任的局域网-Tailnet 绑定将其公开，或通过 SSH 转发回环端口。

拓扑选项

对于始终在线和笔记本电脑设置，建议保持 gateway.bind: "loopback"，并使用 Tailscale Serve 访问 Control UI，或使用受信任的局域网/Tailnet 绑定并配置 gateway.remote.transport: "direct"。SSH 隧道是适用于任何计算机的后备方案。

命令流（各部分在哪里运行）

一个 Gateway 网关负责管理状态和渠道；节点是外围设备。示例（将 Telegram 消息路由到节点工具）：

1. Telegram 消息到达 Gateway 网关。
2. Gateway 网关运行智能体，由智能体决定是否调用节点工具。
3. Gateway 网关通过 Gateway 网关 WebSocket（node.invoke RPC）调用节点。
4. 节点返回结果；Gateway 网关回复 Telegram。

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

SSH 隧道（CLI + 工具）

ssh -N -L 18789:127.0.0.1:18789 user@gateway-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 网关仅绑定到回环地址时，请将 URL 保持为 ws://127.0.0.1:18789，并先打开 SSH 隧道。在 macOS 应用的 SSH 隧道传输方式中，发现的 Gateway 网关主机名应填入 gateway.remote.sshTarget（user@host 或 user@host:port）；gateway.remote.url 仍应使用本地隧道 URL。如果远程端口与本地端口不同，请设置 gateway.remote.remotePort。

默认严格验证主机密钥（gateway.remote.sshHostKeyPolicy: "strict"）。将其设置为 "openssh" 可改为使用你实际生效的 OpenSSH 配置；启用前请检查你的用户级和系统级 SSH 设置。

对于已经可通过受信任局域网或 Tailnet 访问的 Gateway 网关，请使用直连模式：

{  gateway: {    mode: "remote",    remote: {      transport: "direct",      url: "ws://192.168.0.202:18789",      token: "your-token",    },  },}

凭据优先级

在调用、探测和状态路径以及 Discord Exec 审批监控中，Gateway 网关凭据解析遵循统一约定。节点主机使用相同约定，但有一个本地模式例外（它会忽略 gateway.remote.*）。

• 在接受显式身份验证的调用路径上，显式凭据（--token、--password 或工具的 gatewayToken）始终优先。
• URL 覆盖安全规则：
  • CLI 的 --url 绝不会复用隐式的配置/环境变量凭据。
  • 环境变量 OPENCLAW_GATEWAY_URL 只能使用环境变量凭据（OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD）。
• 本地模式默认值：
  • 令牌：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 / gateway.remote.password。
• 默认严格执行远程探测/状态令牌检查：以远程模式为目标时，只使用 gateway.remote.token（不回退到本地令牌）。
• Gateway 网关的环境变量覆盖仅使用 OPENCLAW_GATEWAY_*。

聊天界面的远程访问

WebChat 没有独立的 HTTP 端口；SwiftUI 聊天界面会直接连接到 Gateway 网关 WebSocket。

• 通过 SSH 转发 18789（见上文），然后将客户端连接到 ws://127.0.0.1:18789。
• 对于局域网/Tailnet 直连模式，将客户端连接到配置的私有 ws:// 或安全 wss:// URL。
• 在 macOS 上，应用的远程模式会自动管理所选传输方式。

macOS 应用远程模式

macOS 菜单栏应用会端到端管理同一套设置：远程状态检查、WebChat 和语音唤醒转发。操作手册：macOS 远程访问。

安全规则（远程/VPN）

除非你确定需要绑定到其他地址，否则请让 Gateway 网关仅绑定到回环地址。

• 回环地址 + SSH/Tailscale Serve 是最安全的默认方案（不会公开暴露）。
• 对于回环地址、私有网络/局域网（RFC 1918）、链路本地地址、CGNAT、.local 和 .ts.net 主机，可以使用明文 ws://。公共远程主机必须使用 wss://。
• 非回环地址绑定（lan/tailnet/custom，或在回环地址不可用时使用 auto）必须启用 Gateway 网关身份验证：令牌、密码，或设置了 gateway.auth.mode: "trusted-proxy" 的身份感知型反向代理。
• gateway.remote.token / .password 是客户端凭据来源；它们本身不会配置服务器身份验证。
• 仅当未设置 gateway.auth.* 时，本地调用路径才可回退使用 gateway.remote.*。
• 如果通过 SecretRef 显式配置了 gateway.auth.token / gateway.auth.password，但无法解析，解析过程将以关闭方式失败（不会使用远程回退来掩盖问题）。
• gateway.remote.tlsFingerprint 会固定 wss:// 远程 TLS 证书，包括 macOS 直连模式。如果没有已存储的指纹，macOS 只会在常规系统信任检查通过后首次使用时固定证书；使用自签名证书或私有 CA 的 Gateway 网关需要显式指纹，或使用基于 SSH 的远程连接。
• 当 gateway.auth.allowTailscale: true 时，Tailscale Serve 可以通过身份标头对 Control UI/WebSocket 流量进行身份验证。HTTP API 端点不使用这种标头身份验证，而是遵循 Gateway 网关的常规 HTTP 身份验证模式。此无令牌流程假设 Gateway 网关主机可信；如需在所有位置使用共享密钥身份验证，请将其设置为 false。
• 默认情况下，受信任代理身份验证要求使用非回环地址的身份感知型代理。同一主机上的回环地址反向代理需要显式设置 gateway.auth.trustedProxy.allowLoopback = true。
• 请将浏览器控制视为操作员访问：仅限 Tailnet，并有意执行节点配对。

深入了解：安全性。

macOS：通过 LaunchAgent 建立持久 SSH 隧道

对于 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 网关令牌

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

如果远程 Gateway 网关使用密码身份验证，请改用 gateway.remote.password。OPENCLAW_GATEWAY_TOKEN 仍可用作 Shell 级覆盖，但持久的远程客户端设置应使用 gateway.remote.token / gateway.remote.password。

第 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

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

故障排查

# Check if the tunnel is runningps aux | grep "ssh -N remote-gateway" | grep -v greplsof -i :18789 # Restart the tunnellaunchctl kickstart -k gui/$UID/ai.openclaw.ssh-tunnel # Stop the tunnellaunchctl bootout gui/$UID/ai.openclaw.ssh-tunnel

相关内容

• Tailscale
• 身份验证
• 远程 Gateway 网关设置