macOS 开发环境搭建

本指南涵盖从源码构建和运行 OpenClaw macOS 应用的必要步骤。

前提条件

构建前请确保安装了以下工具：

1. Xcode 26.2+：Swift 开发必备。
2. Node.js 24 & pnpm：用于 Gateway、CLI 和打包脚本。Node 22 LTS 目前 22.16+ 也可兼容使用。

1. 安装依赖

安装项目全局依赖：

pnpm install

2. 构建和打包应用

构建 macOS 应用并打包为 dist/OpenClaw.app：

./scripts/package-mac-app.sh

如果你没有 Apple Developer ID 证书，脚本会自动使用 ad-hoc 签名（-）。

关于开发运行模式、签名参数和 Team ID 问题排查，见 macOS 应用 README： https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md

注意：ad-hoc 签名的应用可能触发安全提示。如果应用立即崩溃并显示 “Abort trap 6”，见下方 故障排查 部分。

3. 安装 CLI

macOS 应用需要全局安装的 openclaw CLI 来管理后台任务。

推荐安装方式：

1. 打开 OpenClaw 应用。
2. 进入 General 设置标签。
3. 点击 “Install CLI”。

或者手动安装：

npm install -g openclaw@<version>

故障排查

构建失败：工具链或 SDK 不匹配

macOS 应用构建需要最新的 macOS SDK 和 Swift 6.2 工具链。

系统依赖（必须）：

• Software Update 中可用的最新 macOS 版本（Xcode 26.2 SDK 要求）
• Xcode 26.2（Swift 6.2 工具链）

检查：

xcodebuild -version
xcrun swift --version

版本不匹配的话，更新 macOS/Xcode 后重新构建。

授权权限时应用崩溃

如果在允许 Speech Recognition 或 Microphone 访问时应用崩溃，可能是 TCC 缓存损坏或签名不匹配。

修复方法：

1. 重置 TCC 权限：

   tccutil reset All ai.openclaw.mac.debug

2. 如果还是不行，临时修改 scripts/package-mac-app.sh 中的 BUNDLE_ID，强制 macOS 重新识别应用。

Gateway 一直显示 “Starting…”

如果 Gateway 状态一直停在 “Starting…”，检查是否有僵尸进程占着端口：

openclaw gateway status
openclaw gateway stop

# 如果没使用 LaunchAgent（开发模式 / 手动运行），找出监听进程：
lsof -nP -iTCP:18789 -sTCP:LISTEN

如果是手动运行的进程占着端口，停掉它（Ctrl+C）。实在不行就 kill 掉上面找到的 PID。