Appearance
OpenClaw Gateway 远程访问主要通过 SSH 隧道或 Tailscale 实现：在专用宿主机运行 Gateway，客户端通过 WebSocket（默认端口 18789）连接。CLI 支持 openclaw health 等命令通过隧道访问，macOS 应用提供自动隧道管理。凭据解析分本地/远程模式，--url 需显式提供 --token。安全上建议保持 loopback-only，非 loopback 绑定必须配置 auth token/password。
OpenClaw 远程访问配置（SSH 隧道与 Tailscale）
核心思路
Gateway WebSocket 默认绑定到 loopback（端口 18789）。远程使用时通过 SSH 转发该端口，或使用 Tailscale/VPN 减少隧道需求。
常见部署场景
1. Always-on Gateway 在 tailnet 中
在 VPS 或家庭服务器上持续运行 Gateway，通过 Tailscale 或 SSH 访问。
- 最佳体验：保持
gateway.bind: "loopback"，用 Tailscale Serve 暴露控制 UI。 - 受信 LAN/Tailnet：绑定到私有接口，使用
gateway.remote.transport: "direct"。 - 后备方案：loopback + SSH 隧道。
2. 家庭台式机运行 Gateway，笔记本远程控制
笔记本通过 macOS 应用的 Remote mode（设置 → 通用 → OpenClaw runs）连接。应用在 LAN/Tailnet 可达时直接连接，否则自动管理 SSH 隧道。
详细操作：macOS 远程访问。
3. 笔记本运行 Gateway，暴露给其他设备
- 其他机器 SSH 隧道连接到笔记本，或
- 用 Tailscale Serve 暴露控制 UI，Gateway 保持 loopback-only。
命令流向
一个 Gateway 服务拥有状态和频道，Node 是外围设备。
示例：Telegram 消息 → Gateway → Agent 决定调用 Node 工具 → Gateway 通过 WebSocket 调用 node → Node 返回结果 → Gateway 回复。
注意：Node 不运行 Gateway 服务。每台宿主机只应运行一个 Gateway（除非有多 profile，见多 Gateway）。macOS 应用的"node 模式"只是 WebSocket 客户端。
SSH 隧道（CLI + 工具）
bash
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 命令默认使用：
json5
{
gateway: {
mode: "remote",
remote: {
url: "ws://127.0.0.1:18789",
token: "your-token",
},
},
}当 Gateway loopback-only 时，URL 保持 ws://127.0.0.1:18789，先建立 SSH 隧道。macOS 应用 SSH 隧道运输时，已发现的网关主机名放在 gateway.remote.sshTarget，gateway.remote.url 保持本地隧道 URL。如果远端端口不同，设置 gateway.remote.remotePort。
对于已通过 LAN/Tailnet 直接可达的 Gateway：
json5
{
gateway: {
mode: "remote",
remote: {
transport: "direct",
url: "ws://192.168.0.202:18789",
token: "your-token",
},
},
}凭据优先级
Gateway 凭据解析在 call/probe/status 路径和 Discord exec-approval 监控中共享同一规则。Node 宿主使用相同基本规则，但本地模式有意忽略 gateway.remote.*。
- 显式凭据（
--token、--password或工具gatewayToken）在 call 路径上始终优先。 - URL 覆盖安全：
- CLI
--url不复用隐式配置/环境凭据。 - 环境变量
OPENCLAW_GATEWAY_URL仅使用环境凭据（OPENCLAW_GATEWAY_TOKEN/OPENCLAW_GATEWAY_PASSWORD）。
- CLI
- 本地模式默认：
- token:
OPENCLAW_GATEWAY_TOKEN→gateway.auth.token→gateway.remote.token（仅当本地 auth token 未设置时才回退 remote） - password:
OPENCLAW_GATEWAY_PASSWORD→gateway.auth.password→gateway.remote.password（类似）
- token:
- 远程模式默认：
- token:
gateway.remote.token→OPENCLAW_GATEWAY_TOKEN→gateway.auth.token - password:
OPENCLAW_GATEWAY_PASSWORD→gateway.remote.password→gateway.auth.password
- token:
- Node 宿主本地模式例外：忽略
gateway.remote.token/gateway.remote.password。 - 远程 probe/status token 检查严格：仅使用
gateway.remote.token（无本地回退）。 - Gateway 环境覆盖仅使用
OPENCLAW_GATEWAY_*。
Chat UI 远程访问
WebChat 不再用独立的 HTTP 端口，SwiftUI 聊天 UI 直接连接 Gateway WebSocket。转发 18789 后，客户端连接到 ws://127.0.0.1:18789。对于 LAN/Tailnet direct 模式，连接私有 ws:// 或安全 wss:// URL。macOS 建议使用应用的远程模式，自动管理传输。
macOS 应用远程模式
macOS 菜单栏应用可端到端处理远程状态检查、WebChat 和 Voice Wake 转发。
详细：macOS 远程访问。
安全规则（远程/VPN）
保持 Gateway loopback-only，除非确定需要绑定。
- Loopback + SSH/Tailscale Serve 最安全，无公网暴露。
- 明文
ws://仅接受 loopback、LAN、link-local、.local、.ts.net、Tailscale CGNAT 主机。公共远程主机必须用wss://。 - 非 loopback 绑定（
lan/tailnet/custom，或 loopback 不可用时auto）必须配置 gateway auth（token、password 或身份感知反向代理 +gateway.auth.mode: "trusted-proxy"）。 gateway.remote.token/.password是客户端凭据来源，不配置服务端 auth。- 仅当
gateway.auth.*未设置时，本地 call 路径才使用gateway.remote.*作为回退。 - 若
gateway.auth.token/gateway.auth.password通过 SecretRef 显式配置且解析失败，则失败关闭（不静默回退 remote）。 gateway.remote.tlsFingerprint在使用wss://时固定远端 TLS 证书，包括 macOS direct 模式。未配置或存储指纹时，macOS 仅固定首次使用的证书（需系统信任通过）；自签名或私有 CA 网关需显式指纹或使用 Remote over SSH。- Tailscale Serve 可在
gateway.auth.allowTailscale: true时通过身份头部认证控制 UI/WebSocket 流量；HTTP API 端点不使用该头部，遵循普通 HTTP auth 模式。无 token 流程假设网关宿主机受信。设为false则全部要求共享密钥 auth。 - Trusted-proxy auth 默认期望非 loopback 身份感知代理。同主机 loopback 反向代理需显式设置
gateway.auth.trustedProxy.allowLoopback = true。 - 浏览器控制视为 operator 访问：仅在 tailnet 内 + 主动节点配对。
完整：Security。
macOS：通过 LaunchAgent 保持 SSH 隧道持久化
对于 macOS 客户端连接远程 Gateway，最省心的持久方案：SSH LocalForward 配置 + LaunchAgent 保持隧道自动启动、崩溃重连。
Step 1：添加 SSH 配置
编辑 ~/.ssh/config：
ssh
Host remote-gateway
HostName <REMOTE_IP>
User <REMOTE_USER>
LocalForward 18789 127.0.0.1:18789
IdentityFile ~/.ssh/id_rsaStep 2：拷贝 SSH 密钥
bash
ssh-copy-id -i ~/.ssh/id_rsa <REMOTE_USER>@<REMOTE_IP>Step 3：配置 Gateway Token
bash
openclaw config set gateway.remote.token "<your-token>"Step 4：创建 LaunchAgent
保存为 ~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist：
xml
<?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>Step 5：加载 LaunchAgent
bash
launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist登录时自动启动，崩溃自动重启。
旧版 com.openclaw.ssh-tunnel 需先卸载。
故障排查
bash
ps aux | grep "ssh -N remote-gateway" | grep -v grep
lsof -i :18789重启隧道：
bash
launchctl kickstart -k gui/$UID/ai.openclaw.ssh-tunnel停止隧道：
bash
launchctl bootout gui/$UID/ai.openclaw.ssh-tunnel| 配置项 | 作用 |
|---|---|
LocalForward 18789 127.0.0.1:18789 | 转发本地 18789 到远端 18789 |
ssh -N | 仅端口转发，不执行命令 |
KeepAlive | 崩溃自动重启 |
RunAtLoad | 登录时启动 |
常见问题
SSH 隧道连不上远程 Gateway 怎么办？
先确认 SSH 连接本身是否正常（ssh user@host 能否登录）。检查本地端口是否被占用：lsof -i :18789。确保远程 Gateway 正在运行且端口配置正确。如果远程 Gateway 绑定 loopback，隧道后的地址必须是 ws://127.0.0.1:18789。
远程 Gateway 需要开放哪些端口到公网？
推荐不开放任何公网端口。使用 Tailscale 或 SSH 隧道（只需 SSH 端口可达）。如果必须直接暴露，需使用 wss:// 并配置 auth token/password。gateway.auth.mode 在非 loopback 绑定下必须设置，否则连接会失败。
openclaw gateway status 报错 "missing credentials" 怎么解决？
该错误通常出现在使用 --url 时未提供 --token 或 --password。CLI 在使用 --url 时不会自动读取配置文件中的凭据，必须显式提供。如果不用 --url，则确保配置文件中 gateway.remote.token 已设置且 Gateway 的 auth 配置匹配。