一、前置条件检查与环境准备

在开始部署 OpenClaw 前，请务必完成以下系统级验证——这一步看似简单，却是后续所有环节稳定运行的基石。macOS 对架构、权限和工具链高度敏感，跳过检查可能导致构建失败、运行崩溃或权限弹窗反复触发。

首先，打开终端（Terminal），执行以下命令确认基础环境：

sw_vers && arch

✅ 预期输出示例（Apple Silicon）：

ProductName:    macOS
ProductVersion: 14.6
BuildVersion:   23G80
arm64

✅ 预期输出示例（Intel + Rosetta 2）：

ProductName:    macOS
ProductVersion: 14.5
BuildVersion:   23F79
x86_64

⚠️ 关键提示：

  • 最低系统要求：macOS Sonoma 14.5 或更高版本（Sequoia 15.0+ 完全兼容）；
  • 架构要求：Apple Silicon（M1/M2/M3）原生支持；Intel 用户必须已启用 Rosetta 2（若未启用，运行 softwareupdate --install-rosetta 并输入管理员密码）；
  • SIP（系统完整性保护）全程无需禁用——本方案所有操作均在用户空间完成，严格遵守 Apple 安全模型。

接下来验证开发工具链：

# 检查 Xcode Command Line Tools
xcode-select -p  # 应返回类似 /Library/Developer/CommandLineTools

# 若报错 "command not found" 或路径不存在，则安装：
xcode-select --install

安装过程中会弹出图形化窗口，点击「安装」→「同意许可协议」→ 等待完成（约 2–5 分钟）。完成后再次运行 xcode-select -p 确认。

再检查 Homebrew 是否就绪：

brew --version

若未安装，执行官方单行命令（自动适配 Apple Silicon 路径）：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装后建议立即运行诊断修复（尤其对首次安装或迁移用户的常见权限问题）：

/opt/homebrew/bin/brew doctor  # Apple Silicon
# 或（Intel）
/usr/local/bin/brew doctor

按提示执行 brew cleanup、brew update 及权限修复（如 sudo chown -R $(whoami) /opt/homebrew）。

验证 macOS 版本、架构与 Homebrew 状态

二、Node.js 24.13.0 原生安装（Apple Silicon 优先）

OpenClaw v0.8.2 依赖 Node.js 24.13.0 的实验性快照（--experimental-snapshot）与 OpenSSL 3.0+ TLS 1.3 支持，严禁使用 brew install node ——Homebrew 默认提供 x86_64 构建或旧版 LTS，易引发 dyld: bad CPU type in executable 或 ERR_SSL_VERSION_OR_CIPHER_MISMATCH 错误。

✅ 推荐方案 A：官方 .pkg 直装（最稳定）

  • 访问 https://nodejs.org/dist/v24.13.0/
  • Apple Silicon 用户下载：node-v24.13.0-darwin-arm64.pkg
  • Intel 用户下载：node-v24.13.0-darwin-x64.pkg（需确保已启用 Rosetta 2）
  • 双击安装 → 全程默认选项 → 输入管理员密码完成

安装后验证：

node -v && npm -v && node --version-check
# 输出应为：v24.13.0、10.9.0、[✓] Node.js version check passed

✅ 关键能力验证（OpenSSL 3.0+）：

node -e "console.log(process.versions.openssl >= '3.0.0' ? '✅ OpenSSL 3.0+ OK' : '❌ OpenSSL too old')"

✅ 方案 B：nvm 精确管理（适合多版本开发者）

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# 重启终端或 source ~/.zshrc
nvm install 24.13.0
nvm use 24.13.0
nvm alias default 24.13.0

⚠️ 注意：Intel 用户若通过 nvm 安装，需确保 nvm 自动选用 darwin-x64 构建（nvm ls-remote --lts 可查看架构标识）。

三、OpenClaw 源码获取与依赖精简构建

避免 npm install 全量拉取（含 Windows/Linux 专用 native 模块），我们采用 pnpm + 生产环境裁剪 + ARM64 专项优化策略。

git clone https://github.com/openclaw/openclaw.git
cd openclaw
git checkout v0.8.2  # 稳定发布版，非 main 分支

安装 pnpm（比 npm 快 3×，硬链接节省磁盘）：

brew install pnpm

执行仅生产依赖安装（跳过 devDependencies 中的 Electron、Windows 构建工具等）：

pnpm install --prod --no-optional

手动优化 package.json（关键！）：

  • 删除 devDependencies 中的 "electron": "^30.x"、"windows-build-tools" 等非 macOS 条目；
  • 确保 dependencies 包含：
    "@openclaw/core": "^0.8.2",
"sharp": "^0.33.0",
"ffmpeg-static": "^5.2.0"

✅ 强制安装 macOS ARM64 专属 FFmpeg：

FFMPEG_STATIC=arm64 pnpm install ffmpeg-static

✅ 重编译 sharp（规避 Homebrew libvips 冲突）：

SHARP_IGNORE_GLOBAL_LIBVIPS=1 pnpm rebuild sharp --runtime=node --target=24.13.0 --platform=darwin --arch=arm64

构建命令（优先使用项目预设）：

pnpm run build:mac-native

若脚本不存在，执行手动构建：

tsc --build tsconfig.json
cp -r resources/ dist/

构建成功后，dist/ 目录下将生成可执行的 OpenClaw.app。

四、macOS 原生权限配置与沙盒绕过（零越狱）

OpenClaw 需要三项核心隐私权限：屏幕录制、辅助功能、全盘访问。我们不修改 SIP，而是通过 macOS 原生 TCC（Transparency, Consent, and Control）机制授权。

第一步：清理旧权限缓存（可选）

tccutil reset All  # 仅重置当前用户，非全局

第二步：首次启动触发系统弹窗

open dist/OpenClaw.app

系统将依次弹出三个授权窗口（请逐一点击「选项」→「始终允许」）：

  • 「屏幕录制」→ 允许 OpenClaw 录制屏幕
  • 「辅助功能」→ 允许控制其他应用（如窗口聚焦、键盘模拟）
  • 「全盘访问」→ 仅授予 dist/ 目录读写权限（不涉及 /System /usr 等受保护分区）

第三步：脚本化辅助功能授权（用户可选）

sudo sqlite3 "/Library/Application Support/com.apple.TCC/TCC.db" \
  "INSERT OR REPLACE INTO access VALUES('kTCCServiceAccessibility','group.openclaw',0,1,1,NULL,NULL,NULL,'UNUSED',NULL,0,1638400000);"

🔐 此命令需管理员密码，仅写入 TCC.db 的 accessibility 权限项，安全可控。

✅ 验证权限状态：

tccutil list | grep openclaw
# 应显示类似：
# accessibility: ✅
# screen_capture: ✅
# full_disk_access: ✅

OpenClaw 权限授权弹窗示意（屏幕录制 + 辅助功能）

五、启动、调试与首屏验证

启动前请退出所有 Electron 应用（避免端口/IPC 冲突）：

cd dist
./OpenClaw.app/Contents/MacOS/OpenClaw \
  --disable-gpu \
  --disable-features=IsolateOrigins,site-per-process \
  --enable-logging=stderr

💡 --disable-features 是关键：绕过 Electron 14+ 默认启用的进程隔离沙盒，解决 macOS 上白屏/卡死问题。

调试技巧

  • 启用远程调试：追加 --remote-debugging-port=9222
  • 在 Chrome 访问 chrome://inspect → 点击「Open dedicated DevTools for Node」→ 查看主进程日志

✅ 首屏成功标志：

  • 终端输出 OPENCLAW_READY: true
  • GUI 界面左上角显示绿色摄像头图标（设备就绪）与麦克风图标

❗ 常见问题速解

现象诊断命令解决方案
黑屏无响应node -e "require('sharp')"若报错，重跑 pnpm rebuild sharp...
摄像头灰显sudo killall VDCAssistant重置 macOS 视频采集服务
TCC denied 日志tccutil list | grep screen手动前往「系统设置 > 隐私与安全性 > 屏幕录制」补授权

六、持久化部署与自动更新配置

让 OpenClaw 开机自启并静默更新：

创建 LaunchAgent（用户级守护进程）

新建文件：~/Library/LaunchAgents/group.openclaw.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>group.openclaw</string>
  <key>ProgramArguments</key>
  <array>
    <string>/full/path/to/openclaw/dist/OpenClaw.app/Contents/MacOS/OpenClaw</string>
    <string>--no-sandbox</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
</dict>
</plist>

⚠️ 将 /full/path/to/... 替换为你的实际路径（可用 pwd 获取）

加载并启动：

launchctl load ~/Library/LaunchAgents/group.openclaw.plist
launchctl start group.openclaw

启用 Sparkle 自动更新

defaults write group.openclaw SUEnableAutomaticChecks -bool TRUE
defaults write group.openclaw SULastCheckTime -date "2024-01-01T00:00:00Z"

✅ 验证：下次启动时，右上角菜单栏将显示「检查更新」选项，且后台静默下载增量包。

OpenClaw 首屏就绪界面（绿色设备图标 + OPENCLAW_READY 日志）

七、故障排除速查表（Q&A）

遇到报错？先复制粘贴以下命令快速定位：

echo "=== ENV ===" && sw_vers && arch && node -v && npm list -g --depth=0 2>/dev/null && echo "=== OPENCLAW ===" && cd openclaw && git rev-parse HEAD && pnpm list --prod --depth=1

🔧 高频问题速查

  • ❌ dlopen(.../sharp.node): incompatible architecture
    → 卸载冲突的 libvips 并重编译：

    brew uninstall vips
pnpm rebuild sharp --runtime=node --target=24.13.0 --platform=darwin --arch=arm64

  • ❌ TCC error: Failed to authorize screen capture
    → 重置权限并跳转设置页：

    tccutil reset ScreenCapture
open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"

  • ❌ JavaScript heap out of memory
    → 启动时增加内存限制：

    ./OpenClaw.app/Contents/MacOS/OpenClaw --max-old-space-size=4096

✅ 终极验证：全部步骤完成后，重启 Mac → 登录即自动启动 OpenClaw → 设备列表绿色就绪 → 录制/推流功能正常。你已拥有一套完全原生、零越狱、符合 Apple 安全规范的 macOS 屏幕协作环境。

OpenClaw 在 macOS Sequoia 上的完整工作流示意（从权限授权到推流就绪）