本文档汇总了 OpenClaw 官方文档站 网关与运维 > 远程访问 子模块下的全部 3 篇内容，源自 docs.openclaw.ai/zh-CN。

📄 远程访问

原文：https://docs.openclaw.ai/zh-CN/gateway/remote

此仓库通过在专用主机（桌面电脑/服务器）上运行单个 Gateway 网关（主节点），并让客户端连接到它，支持“通过 SSH 远程访问”。

• 对于操作端（你 / macOS 应用）：SSH 隧道是通用回退方案。
• 对于节点（iOS/Android 和未来设备）：按需连接到 Gateway 网关 WebSocket（LAN/tailnet 或 SSH 隧道）。

核心思路

• Gateway 网关 WebSocket 会绑定到你配置端口上的 loopback（默认为 18789）。
• 远程使用时，你通过 SSH 转发该 loopback 端口（或使用 tailnet/VPN 并减少隧道使用）。

常见 VPN 和 tailnet 设置

将 Gateway 网关主机视为 agent 所在的位置。它拥有会话、认证配置、渠道和状态。你的笔记本电脑、桌面电脑和节点会连接到这台主机。

在你的 tailnet 中始终运行的 Gateway 网关

在持久主机（VPS 或家庭服务器）上运行 Gateway 网关，并通过 Tailscale 或 SSH 访问它。

• 最佳体验： 保持 gateway.bind: "loopback"，并为控制 UI 使用 Tailscale Serve。
• 回退方案： 保持 loopback，并从任何需要访问的机器建立 SSH 隧道。
• 示例： exe.dev（易用 VM）或 Hetzner（生产 VPS）。

当你的笔记本电脑经常休眠，但你希望 agent 始终在线时，这是理想选择。

家庭桌面电脑运行 Gateway 网关

笔记本电脑不运行 agent。它远程连接：

• 使用 macOS 应用的通过 SSH 远程访问模式（Settings → General → OpenClaw runs）。
• 应用会打开并管理隧道，因此 WebChat 和健康检查可以直接工作。

运行手册：macOS 远程访问。

笔记本电脑运行 Gateway 网关

保持 Gateway 网关在本地运行，但安全地暴露它：

• 从其他机器通过 SSH 隧道连接到笔记本电脑，或
• 使用 Tailscale Serve 暴露控制 UI，并让 Gateway 网关仅绑定 loopback。

指南：Tailscale 和 Web 概览。

命令流（在哪里运行什么）

一个 gateway 服务拥有状态 + 渠道。节点是外围设备。

流程示例（Telegram → 节点）：

• Telegram 消息到达 Gateway 网关。
• Gateway 网关运行 agent，并决定是否调用节点工具。
• Gateway 网关通过 Gateway 网关 WebSocket 调用节点（node.* RPC）。
• 节点返回结果；Gateway 网关再回复到 Telegram。

注意：

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

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 网关凭证解析在 call/probe/status 路径和 Discord 执行审批监控中遵循一套共享契约。Node-host 使用相同的基础契约，但有一个本地模式例外（它会有意忽略 gateway.remote.*）：

• 显式凭证（--token、--password 或工具 gatewayToken）在接受显式认证的调用路径上始终优先。
• URL 覆盖安全性：
• CLI URL 覆盖（--url）永远不会复用隐式 config/env 凭证。
• Env URL 覆盖（OPENCLAW_GATEWAY_URL）只能使用 env 凭证（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 网关 env 覆盖只使用 OPENCLAW_GATEWAY_*。

通过 SSH 使用聊天 UI

WebChat 不再使用单独的 HTTP 端口。SwiftUI 聊天 UI 会直接连接到 Gateway 网关 WebSocket。

• 通过 SSH 转发 18789（见上文），然后将客户端连接到 ws://127.0.0.1:18789。
• 在 macOS 上，优先使用应用的“通过 SSH 远程访问”模式，它会自动管理隧道。

macOS 应用通过 SSH 远程访问

macOS 菜单栏应用可以端到端驱动同一套设置（远程状态检查、WebChat 和 Voice Wake 转发）。

运行手册：macOS 远程访问。

安全规则（远程/VPN）

简短版本：除非你确定需要绑定，否则保持 Gateway 网关仅限 loopback。

• Loopback + SSH/Tailscale Serve 是最安全的默认方式（不公开暴露）。
• 明文 ws:// 默认仅限 loopback。对于受信任的专用网络，
  在客户端进程上设置 OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 作为
  break-glass。没有对应的 openclaw.json 设置；这必须是建立 WebSocket 连接的客户端进程
  环境。
• 非 loopback 绑定（lan/tailnet/custom，或 loopback 不可用时的 auto）必须使用 gateway auth：token、password，或带有 gateway.auth.mode: "trusted-proxy" 的身份感知反向代理。
• gateway.remote.token / .password 是客户端凭证来源。它们本身不会配置服务器认证。
• 仅当 gateway.auth.* 未设置时，本地调用路径才可以使用 gateway.remote.* 作为回退。
• 如果通过 SecretRef 显式配置了 gateway.auth.token / gateway.auth.password 但无法解析，解析会关闭失败（不会用远程回退掩盖）。
• 使用 wss:// 时，gateway.remote.tlsFingerprint 会固定远程 TLS 证书。
• Tailscale Serve 可以在 gateway.auth.allowTailscale: true 时通过身份
  标头认证控制 UI/WebSocket 流量；HTTP API 端点不使用
  该 Tailscale 标头认证，而是遵循 gateway 的常规 HTTP
  auth 模式。这个无 token 流程假定 gateway 主机可信。如果你希望所有地方都使用共享密钥认证，请将其设为
  false。
• Trusted-proxy auth 默认预期非 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

相关

• Tailscale
• 认证
• 远程 gateway 设置

📄 远程 Gateway 网关设置

原文：https://docs.openclaw.ai/zh-CN/gateway/remote-gateway-readme

此内容已合并到 远程访问。当前指南请参见该页面。

使用远程 Gateway 网关运行 OpenClaw.app

OpenClaw.app 使用 SSH 隧道连接到远程 Gateway 网关。本指南将向你展示如何进行设置。

概览

flowchart TB
    subgraph Client["客户端机器"]
        direction TB
        A["OpenClaw.app"]
        B["ws://127.0.0.1:18789\n（本地端口）"]
        T["SSH 隧道"]

        A --> B
        B --> T
    end
    subgraph Remote["远程机器"]
        direction TB
        C["Gateway 网关 WebSocket"]
        D["ws://127.0.0.1:18789"]

        C --> D
    end
    T --> C

快速开始

第 1 步：添加 SSH 配置

编辑 ~/.ssh/config 并添加：

Host remote-gateway
    HostName <REMOTE_IP>          # 例如：172.27.187.184
    User <REMOTE_USER>            # 例如：jefferson
    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 步：启动 SSH 隧道

ssh -N remote-gateway &

第 5 步：重启 OpenClaw.app

# 退出 OpenClaw.app（⌘Q），然后重新打开：
open /path/to/OpenClaw.app

应用现在将通过 SSH 隧道连接到远程 Gateway 网关。

登录时自动启动隧道

如果你希望 SSH 隧道在登录时自动启动，可以创建一个 Launch Agent。

创建 PLIST 文件

将以下内容保存为 ~/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>

加载 Launch Agent

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

工作原理

OpenClaw.app 会连接到你客户端机器上的 ws://127.0.0.1:18789。SSH 隧道会将该连接转发到远程机器上的 18789 端口，也就是 Gateway 网关运行的端口。

相关内容

• 远程访问
• Tailscale

📄 Tailscale

原文：https://docs.openclaw.ai/zh-CN/gateway/tailscale

OpenClaw 可以为 Gateway 网关仪表盘和 WebSocket 端口自动配置 Tailscale Serve（tailnet）或 Funnel（公网）。这会让 Gateway 网关继续绑定到环回地址，同时由 Tailscale 提供 HTTPS、路由，以及（对 Serve 而言）身份标头。

模式

• serve：通过 tailscale serve 使用仅 tailnet 的 Serve。Gateway 网关保持在 127.0.0.1。
• funnel：通过 tailscale funnel 使用公网 HTTPS。OpenClaw 需要一个共享密码。
• off：默认值（不自动化 Tailscale）。

Status 和审计输出会使用 Tailscale 暴露 来表示这个 OpenClaw Serve/Funnel 模式。off 表示 OpenClaw 未管理 Serve 或 Funnel；它并不表示本地 Tailscale 守护进程已停止或已登出。

凭证

设置 gateway.auth.mode 来控制握手：

• none（仅私有入口）
• token（设置 OPENCLAW_GATEWAY_TOKEN 时的默认值）
• password（通过 OPENCLAW_GATEWAY_PASSWORD 或配置提供共享密钥）
• trusted-proxy（具备身份感知能力的反向代理；见 可信代理凭证）

当 tailscale.mode = "serve" 且 gateway.auth.allowTailscale 为 true 时，控制 UI/WebSocket 凭证可以使用 Tailscale 身份标头（tailscale-user-login），无需提供令牌/密码。OpenClaw 会通过本地 Tailscale 守护进程（tailscale whois）解析 x-forwarded-for 地址，并在接受请求前确认它与标头匹配，从而验证该身份。只有当请求来自环回地址，并带有 Tailscale 的 x-forwarded-for、x-forwarded-proto 和 x-forwarded-host 标头时，OpenClaw 才会将其视为 Serve 请求。
对于包含浏览器设备身份的控制 UI 操作员会话，这条经过验证的 Serve 路径还会跳过设备配对往返。它不会绕过浏览器设备身份：无设备客户端仍会被拒绝，节点角色或非控制 UI WebSocket 连接仍会遵循正常的配对和凭证检查。
HTTP API 端点（例如 /v1/*、/tools/invoke 和 /api/channels/*）不会使用 Tailscale 身份标头凭证。它们仍会遵循 Gateway 网关的正常 HTTP 凭证模式：默认使用共享密钥凭证，或使用有意配置的可信代理 / 私有入口 none 设置。
这个无令牌流程假定 Gateway 网关主机是可信的。如果不受信任的本地代码可能在同一主机上运行，请禁用 gateway.auth.allowTailscale，并改为要求令牌/密码凭证。
要要求显式共享密钥凭据，请设置 gateway.auth.allowTailscale: false，并使用 gateway.auth.mode: "token" 或 "password"。

配置示例

仅 tailnet（Serve）

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

打开：https://<magicdns>/（或你配置的 gateway.controlUi.basePath）

仅 tailnet（绑定到 tailnet IP）

当你希望 Gateway 网关直接监听 tailnet IP（不使用 Serve/Funnel）时使用此配置。

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

从另一台 tailnet 设备连接：

• 控制 UI：http://<tailscale-ip>:18789/
• WebSocket：ws://<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，不要把密码提交到磁盘。

CLI 示例

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

说明

• Tailscale Serve/Funnel 要求已安装并登录 tailscale CLI。
• tailscale.mode: "funnel" 会拒绝启动，除非凭证模式为 password，以避免公网暴露。
• 如果希望 OpenClaw 在关闭时撤销 tailscale serve 或 tailscale funnel 配置，请设置 gateway.tailscale.resetOnExit。
• 设置 gateway.tailscale.preserveFunnel: true 可在 Gateway 网关重启期间保留外部配置的 tailscale funnel 路由。启用后，当 Gateway 网关以 mode: "serve" 运行时，OpenClaw 会在重新应用 Serve 前检查 tailscale funnel status，并在已有 Funnel 路由覆盖 Gateway 网关端口时跳过应用。OpenClaw 管理的 Funnel 仅密码策略保持不变。
• gateway.bind: "tailnet" 是直接 tailnet 绑定（无 HTTPS，无 Serve/Funnel）。
• gateway.bind: "auto" 优先使用环回地址；如果你想要仅 tailnet，请使用 tailnet。
• Serve/Funnel 只暴露 Gateway 网关控制 UI + WS。节点通过同一个 Gateway 网关 WS 端点连接，因此 Serve 可用于节点访问。

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

如果你在一台机器上运行 Gateway 网关，但想驱动另一台机器上的浏览器，请在浏览器机器上运行一个节点主机，并让两者保持在同一个 tailnet 中。Gateway 网关会把浏览器操作代理到节点；不需要单独的控制服务器或 Serve URL。

浏览器控制应避免使用 Funnel；将节点配对视作操作员访问来处理。

Tailscale 前提条件 + 限制

• Serve 要求你的 tailnet 已启用 HTTPS；如果缺失，CLI 会提示。
• Serve 会注入 Tailscale 身份标头；Funnel 不会。
• Funnel 要求 Tailscale v1.38.3+、MagicDNS、已启用 HTTPS，以及 Funnel 节点属性。
• Funnel 只支持通过 TLS 使用端口 443、8443 和 10000。
• macOS 上的 Funnel 需要开源 Tailscale 应用变体。

了解更多

• Tailscale Serve 概览：https://tailscale.com/kb/1312/serve
• tailscale serve 命令：https://tailscale.com/kb/1242/tailscale-serve
• Tailscale Funnel 概览：https://tailscale.com/kb/1223/tailscale-funnel
• tailscale funnel 命令：https://tailscale.com/kb/1311/tailscale-funnel

相关

• 远程访问
• 设备发现
• 身份验证