# OpenClaw Mac 节点配置与云端控制完全指南

本文档汇总了关于将 Mac 注册为 OpenClaw Gateway 节点的操作指南，以及在云端部署 Gateway 控制本地 Mac 的场景可行性分析。

---

## 1. 核心概念：Gateway 与 Node

在 OpenClaw 架构中：
- **Gateway (网关)**: 系统的"大脑"与控制中心。负责运行 AI 智能体、管理会话、连接消息平台（如 WhatsApp/Telegram）。它可以部署在任何地方（本地 Manjaro、云端 Ubuntu 服务器等）。
- **Node (节点)**: 系统的"手脚"与执行单元。它连接到 Gateway，暴露本地设备的能力（如屏幕显示、摄像头、执行系统命令）。Mac 可以作为一个高权限节点加入网络。

---

## 2. 实操指南：将 Mac 注册到 Gateway

无论 Gateway 运行在本地局域网（Manjaro）还是云端（Ubuntu），连接 Mac 的步骤基本一致。

### 方案选择

| 方案 | 适用场景 | 优势 | 劣势 |
| :--- | :--- | :--- | :--- |
| **A. macOS App (Remote 模式)** | **推荐** | ✅ 支持 Canvas (网页显示)<br>✅ 支持摄像头/录屏<br>✅ 完整的权限管理 (TCC)<br>✅ 系统通知 | 需要安装 App |
| **B. 纯 CLI (无头模式)** | 服务器/轻量级 | ✅ 无需 GUI<br>✅ 部署简单 | ❌ 无 Canvas/摄像头/录屏支持 |

### 详细配置步骤

#### 第一步：环境准备
1. **Gateway 端 (Manjaro/Ubuntu)**:
   - 确保 Gateway 已启动。
   - 获取连接 Token：
     ```bash
     openclaw config get gateway.auth.token
     # 记录下输出的 Token
     ```
   - 确保网络可达（云端需开放端口或使用 Tailscale/SSH 隧道）。

2. **Mac 端 (节点)**:
   - 安装 OpenClaw CLI: `npm install -g openclaw`
   - (推荐) 下载并安装 **OpenClaw.app**。

#### 第二步：连接 Gateway

**方式 A: 使用 macOS App (推荐)**
1. 打开 OpenClaw.app，进入 **Settings** -> **General**。
2. **Mode**: 选择 **Remote**。
3. **Gateway Host**: 输入 Gateway 的 IP 或域名（如 `1.2.3.4` 或 `myserver.tailscale.net`）。
4. **Gateway Port**: 默认为 `18789`。
5. **Gateway Token**: 填入第一步获取的 Token。
6. 应用会自动启动本地节点服务并尝试连接。

**方式 B: 使用 CLI**
在 Mac 终端运行：
```bash
# 前台运行测试
openclaw node run --host <gateway-ip> --port 18789 --token <token> --display-name "MyMac"

# 或安装为后台服务
openclaw node install --host <gateway-ip> --port 18789 --token <token> --display-name "MyMac"
openclaw node start
```

#### 第三步：批准连接 (在 Gateway 端)
出于安全考虑，新节点连接需要批准。
```bash
# 在 Gateway 机器上运行
openclaw devices list       # 查看待批准请求
openclaw devices approve <request-id>
```

#### 第四步：验证
```bash
# 在 Gateway 机器上运行
openclaw nodes status       # 应显示 Mac 节点在线
openclaw nodes describe --node "MyMac"
```

---

## 3. 功能手册：Gateway 可控制 Mac 做什么

连接成功后，Gateway 上的 AI Agent 可以通过 `node.invoke` 调用 Mac 的能力：

### 基础能力
- **执行命令**: `system.run` (如 `uname -a`, `ls -la`)
  - *安全提示*: 需在 Mac 的 `~/.openclaw/exec-approvals.json` 中配置允许列表。
- **系统通知**: `system.notify` (发送弹窗通知到 Mac 桌面)
- **获取位置**: `location.get`

### 多媒体与 UI (需 macOS App)
- **浏览器控制 (Canvas)**:
  - 打开网页: `canvas.present --target https://google.com`
  - 执行 JS: `canvas.eval --js "document.title"`
  - 截图: `canvas.snapshot`
- **摄像头**: `camera.snap` (拍照), `camera.clip` (录短视频)
- **屏幕录制**: `screen.record`

---

## 4. 场景深度分析：云端 Gateway + Mac Node

**问题**: 如果 Gateway 在云端 Ubuntu，Mac 作为节点，OpenClaw 能否"像人一样"使用 Mac（如写代码、做 PPT）？

**结论**: **可以做到，但更像是"远程脚本专家"，而非"人类操作员"。**

由于网络延迟和架构限制，AI 的操作模式与人类不同：

### 场景 A: 修改代码 (Code Modification)
*   **人类模式 (不推荐)**: 打开 VS Code GUI，点击光标，输入字符。
    *   *AI 限制*: 视觉识别+模拟点击在云端到本地的高延迟下体验极差。
*   **OpenClaw 模式 (推荐)**:
    1.  **Git流**: AI 在云端修改代码 -> Push 到仓库 -> 指挥 Mac 节点 `git pull` -> 指挥 Mac 运行 `npm run dev` 预览。
    2.  **命令行流**: AI 通过 `system.run` 发送 `sed`/`echo` 命令直接修改 Mac 文件（风险较高，容易改错）。

### 场景 B: 制作 PPT (Presentation)
*   **人类模式 (不推荐)**: 打开 Keynote，鼠标拖拽文本框，调整字体。
    *   *AI 限制*: 无法精准控制鼠标拖拽，且无法实时"看"到效果。
*   **OpenClaw 模式 (推荐 - AppleScript)**:
    *   Mac 节点支持执行 AppleScript。AI 可以编写脚本直接控制 Keynote/PowerPoint。
    *   *指令示例*: `tell application "Keynote" to make new slide with title "AI Report"`。
    *   *优势*: 速度极快，精确，无需视觉反馈。

### 关键限制与建议
1.  **网络延迟**: 云端控制本地 UI 会有显著延迟。如果需要频繁的"看屏幕-点击"交互，建议将 Gateway 部署在本地。
2.  **文件访问**: Gateway 默认无法直接读取 Mac 文件系统（除非通过 `cat` 命令回传）。建议通过 Git 或云同步文件夹共享工作区。
3.  **最佳实践**: 让 AI 充当**指挥官**（在云端思考、规划、写脚本），让 Mac 充当**执行器**（运行脚本、渲染 UI、跑测试），而不是让 AI 模拟鼠标键盘。