01 概述

背景

OpenClaw 是一个开源的 AI 编排平台， 允许 AI Agent 通过网关（Gateway）控制设备。默认情况下，网关和受控设备运行在同一台机器上。 本文介绍一种更实用的部署方式：网关运行在远程服务器（AWS EC2）上， macOS 伴侣 App 运行在本地 MacBook 上，通过公网连接。

连接成功后，AI Agent 可以：

  • 在 Mac 的 WebView 中打开 URL、浏览页面
  • 截图并读取页面内容
  • 通过 system.run 执行 shell 命令
  • 从任意消息渠道（如 Telegram）触发上述操作

架构

用户（Telegram / 任意渠道）
    ↕  聊天
AI Agent（Claude / 任意模型）
    ↕  WebSocket  wss://your-domain.com/openclaw-ws
OpenClaw 网关（AWS EC2，Linux）
    ↕  WebSocket（已批准的设备连接）
macOS 伴侣 App（MacBook）
    ↕  macOS 原生 API
浏览器 / Shell / 截图

关键点在于：macOS App 作为 node，主动向网关发起出站连接， Mac 本身不需要暴露任何端口。所有入站流量都打到服务器侧。

02 配置步骤

Step 1 — 部署网关

在 AWS EC2 实例上（推荐 Ubuntu），安装 OpenClaw：

npm install -g openclaw
openclaw gateway start

默认情况下，网关只监听 localhost。 要允许外部设备接入，需要修改监听地址： 

openclaw config set gateway.bind lan
systemctl --user restart openclaw-gateway

网关现在会在默认端口上监听所有网卡。 在 AWS 控制台的安全组中，添加对应端口的入站规则（EC2 → 安全组 → 入站规则 → 自定义 TCP）。

网关所有连接都需要 token 验证，开放端口不会导致未授权访问。 如需进一步收紧，可以限制来源 IP，或使用 Tailscale 等 VPN。

Step 2 — 通过 Nginx + Cloudflare 暴露 WSS 端点

macOS 伴侣 App 要求非本地连接必须使用安全 WebSocket（wss://）。 最简单的做法是用 Nginx 反代网关，由 Cloudflare 在前面做 TLS 终止。

在 Nginx 的 server 配置中添加：

location /openclaw-ws {
    proxy_pass http://127.0.0.1:<gateway-port>;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_read_timeout 86400;
}

重载 Nginx：

sudo nginx -t && sudo systemctl reload nginx

此后 wss://your-domain.com/openclaw-ws 即为可用的 WSS 端点。 Cloudflare 负责 TLS，Nginx 将升级后的 WebSocket 连接转发给本地网关，无需手动管理证书。

Cloudflare SSL 模式设为 Flexible 时，源站只需支持 HTTP，网关本身不需要 TLS 证书。

Step 3 — 安装 macOS 伴侣 App

从 OpenClaw GitHub Releases 页面 下载 macOS 伴侣 App 并安装。

在 App 设置中配置远程连接：

  • OpenClaw runs： Remote (ws/wss)
  • Gateway URL： wss://your-domain.com/openclaw-ws
  • Token： 网关 token（在服务器运行 openclaw config get gateway.token 获取）

保存设置，App 会自动连接网关并注册为待审批设备。

Step 4 — 批准设备

在服务器上查看待审批列表并批准：

openclaw devices list
openclaw devices approve <request-id>

验证连接状态：

openclaw nodes status

MacBook 应显示为 paired · connected， 能力（capabilities）中包含 canvas、screen、system.run。

03 使用

浏览器控制

在 Mac 的 WebView 中打开指定 URL：

openclaw nodes invoke \
  --node "<node-name>" \
  --command canvas.navigate \
  --params '{"url":"https://example.com"}'

截图：

openclaw nodes canvas snapshot \
  --node "<node-name>" \
  --format jpg

AI Agent 接收截图后可以读取页面内容，并继续执行后续操作—— 使用的是 Mac 本地的网络环境和已登录的 session。

执行 Shell 命令

在 system.run 可用的前提下，AI 也可以在 Mac 上执行 shell 命令， 具体权限由伴侣 App 中配置的 exec 审批策略决定。

04 常见问题

  • "node not connected" — WebSocket 连接断开。检查伴侣 App 是否仍在运行， 以及服务器上的网关进程是否正常（openclaw gateway status）， 同时确认云安全组的端口规则没有被修改。
  • 必须用 wss:// — macOS App 对非本机连接强制要求加密 WebSocket，直接用 ws:// 加公网地址会被拒绝。 按上述 Nginx 方案做一层代理是最省事的解决办法。
  • system.run 报格式错误 — 该问题只出现在命令行 node 模式下。伴侣 App 模式下 system.run 可以正常使用。
  • App 连接成功但 node 显示为 disconnected — App 默认以 operator 身份连接。完成设备配对审批后，才会同时注册为 node。