OpenClaw 科普系列(17):远程访问——随时随地连接你的 Agent

前几期我们聊了安全模型，确保 Agent 在安全的环境中运行。但安全不应以牺牲便利性为代价——当你不在家或办公室时，如何远程访问你的 Agent？这就是 远程访问 要解决的问题。

本期我们来深入了解 OpenClaw 的远程访问方案：SSH 隧道、Tailscale 集成以及各种配置模式。

远程访问的核心思想

OpenClaw 的架构设计支持"远程使用"：

• Gateway 作为中心：在一台常驻主机（VPS/服务器/家用电脑）上运行 Gateway
• 客户端远程连接：通过 SSH 隧道或 VPN/tailnet 连接到 Gateway
• 状态集中管理：所有会话、配置、频道状态都保存在 Gateway 主机上

这种方式特别适合：

• 笔记本电脑经常睡眠，但希望 Agent 始终在线
• 多台设备需要访问同一个 Agent
• 在外出时通过手机/平板控制家里的 Agent

三种常见部署模式

模式1：VPS/服务器常驻 Gateway

在云端或家庭服务器上运行 Gateway，通过 Tailscale 或 SSH 访问。

最佳实践：

• 保持 gateway.bind: "loopback"
• 使用 Tailscale Serve 暴露 Control UI
• 作为备选，使用 SSH 隧道

适用场景：

• 需要 7×24 小时在线的 Agent
• 多设备访问同一个 Agent
• 家庭自动化、监控等长期运行任务

模式2：家用电脑运行 Gateway，笔记本远程控制

Gateway 运行在家里的台式机上，笔记本通过远程模式连接。

配置方式：

• macOS 应用：设置 → 通用 → "OpenClaw runs" → 选择"Remote over SSH"
• 应用自动管理 SSH 隧道

适用场景：

• 家里电脑性能更强，适合运行大模型
• 笔记本作为轻量级终端使用
• 外出时通过手机访问家里的 Agent

模式3：笔记本运行 Gateway，其他设备远程访问

Gateway 运行在笔记本上，其他设备通过 SSH 或 Tailscale 连接。

配置方式：

• 从其他设备 SSH 隧道到笔记本
• 或使用 Tailscale Serve 暴露 Control UI

适用场景：

• 个人使用，笔记本是主要工作设备
• 偶尔需要从手机/平板访问

SSH 隧道（通用方案）

SSH 隧道是最通用的远程访问方案，不需要额外软件。

建立隧道

ssh -N -L 18789:127.0.0.1:18789 user@gateway-host

参数说明：

• -N：不执行远程命令，仅做端口转发
• -L：本地端口转发，将本地 18789 映射到远程的 18789
• user@gateway-host：Gateway 主机的 SSH 登录信息

使用隧道

隧道建立后，本地访问 ws://127.0.0.1:18789 就会转发到远程 Gateway：

openclaw health
openclaw status --deep
openclaw gateway status

注意：使用 --url 时需要显式提供凭证：

openclaw gateway status --url ws://127.0.0.1:18789 --token <token>

持久化配置

在客户端配置远程默认值：

{
  gateway: {
    mode: "remote",
    remote: {
      url: "ws://127.0.0.1:18789",
      token: "your-token",
    },
  },
}

这样 CLI 命令会自动使用远程 Gateway。

Tailscale 集成（推荐方案）

Tailscale 提供零配置 VPN，是 OpenClaw 远程访问的推荐方案。

Tailscale Serve（Tailnet 内访问）

保持 Gateway 在 loopback 上，通过 Tailscale Serve 暴露：

{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "serve" },
  },
}

或使用 CLI：

openclaw gateway --tailscale serve

访问地址：

https://<magic-dns-name>/

Serve 模式特点：

• 仅在 Tailnet 内可访问（你的私有网络）
• 自动 HTTPS
• 支持 Tailscale 身份验证头部
• Gateway 仍绑定在 loopback，安全级别高

Tailscale Funnel（公网访问）

如果需要从公网访问，使用 Funnel：

{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "funnel" },
    auth: { mode: "password", password: "strong-password" },
  },
}

或使用 CLI：

openclaw gateway --tailscale funnel --auth password

Funnel 模式特点：

• 通过公网 HTTPS 访问
• 必须设置密码认证（安全要求）
• 使用 Tailscale 的公网入口节点
• 适合临时共享或特定场景

安全警告：

• Funnel 将服务暴露到公网，风险较高
• 务必使用强密码
• 考虑使用允许列表限制访问

直接绑定到 Tailnet IP

如果你想让 Gateway 直接监听 Tailnet IP：

{
  gateway: {
    bind: "tailnet",
    auth: { mode: "token", token: "your-token" },
  },
}

注意：

• 此时 http://127.0.0.1:18789 将无法访问
• 必须通过 Tailnet IP 访问：http://<tailscale-ip>:18789

身份验证流程

Tailscale Serve 身份验证

当 gateway.auth.allowTailscale 为 true（Serve 模式默认）时：

1. Tailscale Serve 注入身份头部（tailscale-user-login）
2. OpenClaw 通过 tailscale whois 验证来源 IP
3. 验证通过后，Control UI/WebSocket 可免 Token 访问
4. HTTP API 端点（如 /v1/*、/tools/invoke）仍需要 Token/Password

安全边界：

• 此流程假设 Gateway 主机是可信的
• 如果同一主机上有不可信代码运行，应禁用 allowTailscale
• 不要从自己的反向代理转发这些头部

凭证优先级

Gateway 凭证解析遵循以下优先级：

1. 显式凭证：--token、--password 或工具中的 gatewayToken
2. 环境变量：OPENCLAW_GATEWAY_TOKEN、OPENCLAW_GATEWAY_PASSWORD
3. 本地配置：gateway.auth.token、gateway.auth.password
4. 远程回退：gateway.remote.token、gateway.remote.password（仅当本地未设置时）

特殊规则：

• 节点主机在本地模式下忽略 gateway.remote.*
• URL 覆盖（--url）时不复用隐式配置/环境凭证

命令流向（远程场景）

以 Telegram 消息处理为例：

1. Telegram 消息到达 Gateway（在远程主机上）
2. Gateway 运行 Agent，决定是否需要调用节点工具
3. Gateway 通过 WebSocket 调用 Node（可能在另一台设备上）
4. Node 返回结果，Gateway 回复给 Telegram

关键点：

• Node 不运行 Gateway 服务
• 每个主机只应运行一个 Gateway（除非故意隔离）
• macOS 应用的"Node 模式"只是通过 WebSocket 连接到 Gateway

浏览器控制（远程 Gateway + 本地浏览器）

如果 Gateway 运行在远程，但你想在本地机器上控制浏览器：

推荐方案：

1. 在本地机器上运行 Node Host
2. 将 Node Host 和 Gateway 加入同一个 Tailnet
3. Gateway 会代理浏览器操作到 Node

避免：

• 使用 Funnel 暴露浏览器控制端点
• 将浏览器控制暴露到公网

安全最佳实践

网络绑定

• 首选：bind: "loopback" + SSH/Tailscale Serve
• 次选：bind: "tailnet" + Token 认证
• 避免：bind: "lan" 或 bind: "0.0.0.0" 无认证

传输安全

• ws://（明文）默认只允许 loopback
• 可信私有网络需要设置 OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1
• 生产环境使用 wss:// + TLS

认证要求

• 非 loopback 绑定必须使用 Token 或 Password
• 定期轮换凭证
• 不要将密码提交到版本控制（使用环境变量）

故障排除

连接失败

# 检查 Gateway 是否运行
openclaw gateway status

# 检查端口监听
netstat -an | grep 18789

# 测试 WebSocket
openclaw health --url ws://127.0.0.1:18789 --token <token>

Tailscale 问题

# 检查 Tailscale 状态
tailscale status

# 检查 Serve/Funnel 配置
tailscale serve status
tailscale funnel status

# 重新启动 Tailscale 服务
sudo tailscale up

SSH 隧道断开

使用 autossh 保持隧道：

autossh -M 0 -N -L 18789:127.0.0.1:18789 user@gateway-host

总结

OpenClaw 提供灵活的远程访问方案：

• SSH 隧道：通用、无需额外软件、适合临时使用
• Tailscale Serve：推荐方案，Tailnet 内安全访问，自动 HTTPS
• Tailscale Funnel：公网访问，需谨慎使用，必须密码认证
• 直接绑定：Tailnet IP 绑定，适合特定网络架构

核心安全原则：

• 尽可能保持 Gateway 在 loopback 上
• 非 loopback 绑定必须认证
• 浏览器控制等敏感操作限制在 Tailnet 内
• 定期审计和轮换凭证

通过合理的远程访问配置，你可以在任何地方安全地连接你的 Agent，既享受便利，又不牺牲安全。

下一期，我们将探讨 监控与日志——如何追踪 Agent 的运行状态和排查问题。