macOS

概述

macOS 是 OpenClaw 的主要开发平台，提供最完整的功能支持，包括 iMessage 集成、Apple Notes 访问和菜单栏伴侣应用等独占特性。

安装前提

Xcode Command Line Tools

OpenClaw 依赖 Xcode Command Line Tools 提供的编译工具链。安装 OpenClaw 之前，请先确认已安装：

xcode-select --install

如果已安装，会提示「command line tools are already installed」，可以忽略。

TIP

如果你之前安装过 Homebrew 或做过 iOS/macOS 开发，大概率已经装过了。

安装 OpenClaw

推荐使用 Node.js 或 Docker 方式安装，详见 安装指南。

# Node.js 方式（推荐）
npm install -g openclaw

# 引导式配置
openclaw onboard --install-daemon

macOS 独占特性

iMessage 集成

macOS 上的 OpenClaw 可以通过 iMessage 收发消息，直接在 iPhone/iPad/Mac 的「信息」应用中和 AI 对话。

该功能依赖 macOS 原生的 AppleScript 接口，仅在 macOS 上可用。

# 启用 iMessage 频道
openclaw channels enable imessage

详见 iMessage 频道配置。

Apple Notes 技能

通过 AppleScript 接口，OpenClaw 可以读写 Apple Notes（备忘录）。例如让 AI 把每日摘要写入备忘录、从备忘录中读取待办事项等。

# 启用 Apple Notes 技能
openclaw skills enable apple-notes

INFO

iMessage 和 Apple Notes 技能均依赖 macOS 原生 AppleScript，首次使用时系统会弹出权限请求，请点击「允许」。

菜单栏伴侣应用

OpenClaw 提供了一个 macOS 菜单栏应用（源码位于 apps/macos/），提供以下功能：

功能	说明
一键启停 Gateway	无需打开终端，点击即可启动或停止 Gateway 服务
查看 Channel 状态	实时显示各频道连接状态（在线/离线/错误）
快速访问 Dashboard	一键在浏览器中打开 Web 控制台
系统通知	当 Gateway 异常或频道断连时，通过 macOS 通知中心提醒

安装菜单栏应用

# 从源码构建
cd apps/macos/
swift build -c release

# 或使用预编译版本（如果可用）
brew install --cask openclaw-companion

推荐部署方案

对于 macOS 用户，推荐以下组合方案：

Mac（运行 Gateway + 菜单栏应用）
  ├── 本机直接使用 Web UI（localhost:3000）
  ├── iPhone / iPad 通过 Tailscale 访问
  └── 其他设备通过局域网或 Tailscale 访问

方案说明

1. Mac 作为 Gateway 主机：利用 macOS 的稳定性和 AppleScript 独占能力
2. 菜单栏应用监控：随时掌握 Gateway 状态，无需开终端
3. 移动设备远程访问：通过 Tailscale 组建安全内网，手机/平板随时连接

Tailscale 推荐理由

Tailscale 提供免费的 WireGuard 组网，配置简单（装上就能用），无需公网 IP 和端口转发。是远程访问家中 Gateway 的最佳方案。

配合 Tailscale 的远程访问

# Mac 和移动设备都安装 Tailscale 后
# 假设 Mac 的 Tailscale IP 是 100.64.0.1

# 移动设备浏览器访问
http://100.64.0.1:3000/

# 或配置频道直接通过 Telegram 等平台对话

常见问题

Gateway 开机自启

使用 --install-daemon 完成配置后，Gateway 会通过 launchd 自动启动：

# 查看守护进程状态
launchctl list | grep openclaw

# 手动启停
launchctl start com.openclaw.gateway
launchctl stop com.openclaw.gateway

"Gateway did not become ready" 报错

现象：打开 macOS App 后提示 Gateway did not become ready. Check that it is running.

原因：macOS App 不再内置 Gateway 运行时，必须依赖机器上单独安装的 openclaw CLI。

排查步骤：

# 1. 确认 Node.js 版本 ≥ 22
node --version

# 2. 确认 CLI 已安装且在系统路径中
which openclaw
openclaw --version

# 3. 如缺失，安装 Node.js 22 和 CLI
nvm install 22
nvm use 22
npm install -g openclaw@latest

安装完成后重启 OpenClaw App，向导应能正常启动网关。

验证网关状态：

# 检查 launchd 服务
launchctl list | grep openclaw

# 查看最近日志
openclaw logs --tail 20

WARNING

此问题仅出现在使用 macOS App（菜单栏应用）的场景。如果你通过命令行 openclaw daemon start 启动网关，不会遇到此问题。

AppleScript 权限问题

首次使用 iMessage 或 Apple Notes 技能时，macOS 会弹出权限请求。如果误点了「拒绝」：

1. 打开 系统设置 > 隐私与安全性 > 自动化
2. 找到 OpenClaw（或 Terminal/iTerm），勾选相关应用的权限

下一步

• 引导式配置 --- 完成首次配置
• iMessage 频道 --- 配置 iMessage 集成
• 远程访问 --- 从外部设备连接 Gateway