网络与远程访问

本页介绍如何从远程机器安全地访问运行在其他机器上的 OpenClaw Gateway。

核心概念

Gateway 的 WebSocket 默认绑定在本机回环地址（127.0.0.1:18789）。 远程访问有两种主要方式：

1. SSH 隧道：通用方案，适合任何环境
2. Tailscale：更优雅的方案，适合有 Tailscale 网络的用户

常见使用场景

场景 1：VPS 或家庭服务器运行 Gateway（推荐）

在一台常开的主机（VPS 或家用服务器）上运行 Gateway，其他设备通过 Tailscale 或 SSH 连接。

• 最佳体验：保持 gateway.bind: "loopback"，使用 Tailscale Serve 暴露控制面板
• 备选方案：保持回环绑定 + SSH 隧道

适合笔记本经常休眠但需要 Agent 常驻在线的场景。

场景 2：台式机运行 Gateway，笔记本远程控制

笔记本不运行 Agent，通过远程方式连接：

• 使用 macOS 应用的 Remote over SSH 模式（设置 → General → "OpenClaw runs"）
• 应用自动管理 SSH 隧道，WebChat 和健康检查开箱即用

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

• 从其他机器 SSH 隧道到笔记本
• 或使用 Tailscale Serve 暴露控制面板，同时 Gateway 只监听回环地址

SSH 隧道

将远程 Gateway 的端口转发到本地：

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

隧道建立后，本地即可访问远程 Gateway：

openclaw health
openclaw status --deep

注意：

• 18789 替换为你配置的 gateway.port
• 若传入 --url，CLI 不会从配置读取凭据，需显式传入 --token 或 --password

持久化远程配置

在配置文件中设置远程连接默认值，避免每次指定参数：

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

凭据优先级

本地模式：

• token：OPENCLAW_GATEWAY_TOKEN → gateway.auth.token → gateway.remote.token
• password：OPENCLAW_GATEWAY_PASSWORD → gateway.auth.password → gateway.remote.password

远程模式：

• token：gateway.remote.token → OPENCLAW_GATEWAY_TOKEN → gateway.auth.token
• password：OPENCLAW_GATEWAY_PASSWORD → gateway.remote.password → gateway.auth.password

显式参数（--token、--password）始终优先。

Tailscale 集成

OpenClaw 可自动配置 Tailscale Serve（内网）或 Funnel（公网）来暴露控制面板，同时 Gateway 保持绑定在本机回环地址。

Tailscale 模式

• serve：通过 tailscale serve 暴露给 Tailnet（内网专用）
• funnel：通过 tailscale funnel 暴露到公网（需配置 password 认证）
• off：默认，不启用 Tailscale 自动化

配置示例

仅内网访问（Serve）

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

访问地址：https://<你的MagicDNS域名>/

直接绑定到 Tailnet IP

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

从 Tailnet 其他设备访问：http://<tailscale-ip>:18789/

注意：此模式下 http://127.0.0.1:18789 不可用。

公网访问（Funnel + 密码保护）

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

建议使用环境变量 OPENCLAW_GATEWAY_PASSWORD 代替在配置文件中写明文密码。

Tailscale CLI 快捷启动

openclaw gateway --tailscale serve
openclaw gateway --tailscale funnel --auth password

Tailscale Serve 身份验证

当 tailscale.mode = "serve" 且 gateway.auth.allowTailscale: true 时，控制面板和 WebSocket 可通过 Tailscale 身份头（tailscale-user-login）免 token 访问。

注意：HTTP API 端点（/v1/*、/tools/invoke、/api/channels/*）仍需 token/password 认证。

如果同一主机上可能运行不受信任的本地代码，建议设置 gateway.auth.allowTailscale: false。

Tailscale 前提条件

• Serve 需要启用 Tailnet HTTPS
• Funnel 需要 Tailscale v1.38.3+、MagicDNS、HTTPS 和 funnel node 属性
• Funnel 仅支持端口 443、8443、10000
• macOS 上 Funnel 需要开源版 Tailscale 客户端

安全建议

核心原则：除非有明确需求，保持 Gateway 绑定在回环地址。

• 回环 + SSH/Tailscale Serve = 最安全的默认配置（无公网暴露）
• 明文 ws:// 仅用于回环地址。若在受信任的私有网络中使用，客户端进程需设置 OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1
• 非回环绑定（lan/tailnet/custom）必须配置 token 或 password 认证
• gateway.remote.tlsFingerprint 可固定远程 TLS 证书（使用 wss:// 时）
• 浏览器控制功能应视为操作员级访问权限，仅限 tailnet 内使用