文档
实战指南
从外部安全访问家里的 OpenClaw：拓扑、数据流与排障

从外部安全访问家里的 OpenClaw：拓扑、数据流与排障

本文是面向家庭服务器读者的原创指南，与家庭服务器运行 OpenClaw衔接；命令与配置键以 2026-11-06 检出的官方文档固定快照为准核对，步骤未在本站实机运行。完整的键与命令参考见远程访问参考页，本文不重复其全文。

家里跑着 OpenClaw，人在公司、通勤路上或被窝里想用——这件事的本质是：Gateway 在家里某台机器的 127.0.0.1:18789（默认端口，可配置）上，你的设备在外面。把两者接起来的每种方法，都是一次"暴露范围 vs 运维成本"的取舍。

一、先想清楚你在保护什么

Gateway 是 OpenClaw 的控制面：它持有会话历史、模型 Provider 凭据、聊天渠道账号和全部状态。把权限拆开看：网络可达（能建立连接）≠ Gateway 认证（token/password/tailnet 身份）≠ 节点配对 ≠ 角色与 scopes 授予的实际权限——网络可达本身不赋予任何操作员能力，但每多一层可达就多一分被凭据攻击面接触的机会。所以远程访问的安全目标是：链路加密 + 只有你和你的设备可达 + Gateway 认证把关，三者缺一不可。

二、四层拓扑，按暴露范围从小到大选

拓扑适合代价
仅本机（loopback 默认）只在那台机器上用出门就用不了
家庭局域网（bind 到 LAN 地址 + 认证）只在家里其他设备用出门仍不可达
Tailnet / Tailscale Serve（推荐的外出方案）你自己的手机/笔记本/平板，任意网络每台设备装 Tailscale
公网暴露（Funnel 或自建反向代理，均需 TLS）需要任意外网设备到达攻击面最大；认证按方案而异：Funnel 按官方要求配共享密码，反向代理按 trusted-proxy / token / password 契约配置（详见下文"公网暴露"）

选择判据（作者建议）：先问"需要访问的设备是不是都能进同一个 tailnet"——能，就用 Serve，这是暴露面最小的外出方案；不能且该设备能 SSH 登录你的服务器（有可达的 SSH 服务与有效登录身份，借来的公共电脑通常不满足），退到 SSH 隧道；确实要任意外网设备到达，再在 Funnel 与自建反向代理之间选，并接受公网暴露。

两条硬规则（官方）：Gateway 保持 loopback 除非你确定要绑定；任何非 loopback 绑定必须配 Gateway 认证（token/password/trusted-proxy）。

三、每层的链路与信任边界

Tailnet / Serve：流量走 Tailscale 的 WireGuard 加密，gateway.tailscale.mode: "serve" 让 Gateway 保持 loopback、由 Tailscale 提供 HTTPS 与路由；allowTailscale: true 时可用 Tailscale 身份 header 认证——注意该 header 认证只覆盖 Control UI/WebSocket 流量，HTTP API 端点仍走 Gateway 正常 HTTP 认证模式；这个免 token 流程假设 Gateway 主机本身受信。信任边界不止"是不是 tailnet 成员"：tailnet 的 ACL/grants、设备与节点配对状态、Gateway 自身的认证与角色仍然各自生效——Serve 缩小的是网络暴露面，不是授权模型。

SSH 隧道：在你外出设备上执行

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

（18789 为默认端口 gateway.port，可配置；远程端口不同时目的端口写 127.0.0.1:<远程端口>。）本地 18789 经你家服务器（SSH 服务）转发到 Gateway。前提是该设备能通过网络到达你的 SSH 服务并持有效登录身份；流量加密依赖 SSH；信任边界=能登录你家服务器 SSH 的密钥。注意 openclaw 的 --url 参数绝不回退到配置里的凭据——显式带 --token/--password，否则目标要求认证时直接失败（这是安全特性，不是 bug）。

公网暴露，两种做法要分开评估：

  • Tailscale Funnel：官方要求配置共享密码——这是 Funnel 模式自身的约束，不要泛化到其他方案。
  • 自建反向代理：按官方 trusted-proxy 契约配置（gateway.auth.mode: "trusted-proxy"，代理注入身份 header），或保留 token/password 认证；同主机 loopback 反代还需显式 trustedProxy.allowLoopback = true。

信任边界=知道凭据的任何人，含扫描器——公网是最后选项。

四、检查顺序：从链路到服务

“连不上"按这个顺序查，每步都有确定性命令（说明性示例，未实机运行）：

  1. 隧道/网络通不通：SSH 场景先确认隧道进程在（ps aux | grep "ssh -N"）；Tailscale 场景 tailscale status 确认两台设备都在线且同一 tailnet。
  2. 端口对不对：本地 curl http://127.0.0.1:18789 应有响应（哪怕 401）；没有就查 -L 的本地端口与 gateway.port 是否一致（远程端口不同时隧道目的端口要写成 127.0.0.1:<远程端口>）。
  3. 凭据对不对：openclaw gateway status --url ws://127.0.0.1:18789 --token <your-token>——能通就是链路+认证都好；报认证失败就核对 token（凭据解析优先级见参考页"凭据优先级"节）。
  4. Gateway 本身健康吗：openclaw health、openclaw status --deep。

五、失败与恢复

  • 隧道断开（网络切换/休眠）：macOS 可用 LaunchAgent 常驻隧道（KeepAlive 崩溃自动重启，完整 plist 与命令见远程访问参考页）；手动重启用完整标签 launchctl kickstart -k gui/$UID/ai.openclaw.ssh-tunnel。
  • 端口漂移/被占：lsof -i :18789 查占用；换本地端口时记得同步改客户端 URL。
  • 凭据作用域变化：SSH 别名重新指到另一台 Gateway 时，旧别名缓存的设备凭据可能被发往新目的地——连不同 Gateway 用新别名（官方语义）。
  • 远程端口与本地不同：隧道写 -L 18789:127.0.0.1:<远程端口>，客户端仍连 ws://127.0.0.1:18789，无需改配置。

与其他页面的分工

多设备使用 OpenClaw：会话同步与权限分层