Files

Josh Palmer 5676a6b38d Docs: normalize zh-CN terminology + tone

What: switch to 你/你的 tone; standardize Skills/Gateway网关/local loopback/私信 wording
Why: align zh-CN docs with issue 6995 feedback + idiomatic tech style
Tests: pnpm docs:build

2026-02-02 16:38:25 +01:00

5.5 KiB

Raw Blame History

read_when, summary, title, x-i18n

read_when

summary

title

x-i18n

运行或排查远程 Gateway网关设置问题

使用 SSH 隧道（Gateway网关 WebSocket）和 tailnet 进行远程访问

远程访问

generated_at	model	provider	source_hash	source_path	workflow
2026-02-01T20:35:58Z	claude-opus-4-5	pi	7e00bd2e048dfbd829913bef0f40a791b8d8c3e2f8a115fc0a13b03f136ebc93	gateway/remote.md	14

远程访问（SSH、隧道和 tailnet）

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

对于操作者（你 / macOS 应用）：SSH 隧道是通用的后备方案。
对于节点（iOS/Android 及未来设备）：连接到 Gateway网关的 WebSocket（根据需要通过局域网/tailnet 或 SSH 隧道）。

核心思路

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

常见的 VPN/tailnet 设置（智能体运行的位置）

将 Gateway网关主机视为"智能体运行的位置"。它拥有会话、认证配置、渠道和状态。你的笔记本/桌面（及节点）连接到该主机。

1) 在 tailnet 中常驻运行的 Gateway网关（VPS 或家庭服务器）

在持久化主机上运行 Gateway网关，通过 Tailscale 或 SSH 访问。

**最佳体验：**保持 gateway.bind: "loopback" 并使用 Tailscale Serve 提供控制界面。
**后备方案：**保持 local loopback + 从需要访问的任何机器建立 SSH 隧道。
示例：exe.dev（简易虚拟机）或 Hetzner（生产 VPS）。

当你的笔记本经常休眠但希望智能体始终在线时，这是理想方案。

2) 家庭桌面运行 Gateway网关，笔记本作为远程控制

笔记本不运行智能体。它通过远程连接：

使用 macOS 应用的通过 SSH 远程连接模式（设置 → 通用 → "OpenClaw 运行位置"）。
应用会打开并管理隧道，因此 WebChat + 健康检查"开箱即用"。

操作指南：macOS 远程访问。

3) 笔记本运行 Gateway网关，从其他机器远程访问

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

从其他机器通过 SSH 隧道连接到笔记本，或
通过 Tailscale Serve 提供控制界面并保持 Gateway网关仅绑定 local loopback。

指南：Tailscale 和 Web 概览。

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

一个 Gateway网关服务拥有状态和渠道。节点是外围设备。

流程示例（Telegram → 节点）：

Telegram 消息到达 Gateway网关。
Gateway网关运行智能体并决定是否调用节点工具。
Gateway网关通过 Gateway网关 WebSocket（node.* RPC）调用节点。
节点返回结果；Gateway网关将回复发送回 Telegram。

说明：

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

SSH 隧道（CLI + 工具）

创建到远程 Gateway网关 WebSocket 的本地隧道：

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,health,send,agent,call} 也可以在需要时通过 --url 指向转发的 URL。

注意：将 18789 替换为你配置的 gateway.port（或 --port/OPENCLAW_GATEWAY_PORT）。

CLI 远程默认值

你可以持久化远程目标，使 CLI 命令默认使用它：

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

当 Gateway网关仅绑定 local loopback 时，保持 URL 为 ws://127.0.0.1:18789 并先打开 SSH 隧道。

通过 SSH 访问聊天界面

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

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

macOS 应用"通过 SSH 远程连接"

macOS 菜单栏应用可以端到端驱动相同的设置（远程状态检查、WebChat 和语音唤醒转发）。