mac node to manjaro gateway

2026-02-08 22:48:58 +08:00 · 2026-02-08 22:48:58 +08:00 · daa2a6e631
parent cbc48df08b
commit daa2a6e631
1 changed files with 126 additions and 0 deletions
--- a/OPENCLAW_MAC_NODE_COMPLETE_GUIDE.md
+++ b/OPENCLAW_MAC_NODE_COMPLETE_GUIDE.md
@ -0,0 +1,126 @@
+# 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 模拟鼠标键盘。