macOS 开发者设置

本指南涵盖了从源代码构建和运行 OpenClaw macOS 应用程序所需的步骤。

先决条件

在构建应用程序之前，请确保已安装以下内容：

1. Xcode 26.2+: 用于 Swift 开发。
2. Node.js 22+ & pnpm: 用于网关、CLI 和打包脚本。

1. 安装依赖

安装项目范围内的依赖：

pnpm install

2. 构建和打包应用程序

要构建 macOS 应用程序并将其打包到 dist/OpenClaw.app，请运行：

./scripts/package-mac-app.sh

如果您没有 Apple 开发者 ID 证书，脚本将自动使用 adhoc 签名 (-)。

有关开发运行模式、签名标志和团队 ID 故障排除，请参阅 macOS 应用程序 README： https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md

注意: adhoc 签名的应用程序可能会触发安全提示。如果应用程序立即崩溃并显示 “Abort trap 6”，请参阅 故障排除 部分。

3. 安装 CLI

macOS 应用程序期望全局安装 openclaw CLI 来管理后台任务。

要安装它（推荐）：

1. 打开 OpenClaw 应用程序。
2. 转到 常规 设置选项卡。
3. 点击 “安装 CLI”。

或者手动安装：

npm install -g openclaw@<version>

故障排除

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

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

系统依赖项（必需）：

• 软件更新中可用的最新 macOS 版本（由 Xcode 26.2 SDKs 所需）
• Xcode 26.2（Swift 6.2 工具链）

检查：

xcodebuild -version
xcrun swift --version

如果版本不匹配，请更新 macOS/Xcode 并重新运行构建。

应用程序在授予权限时崩溃

如果您在尝试允许 语音识别 或 麦克风 访问时应用程序崩溃，可能是由于 TCC 缓存损坏或签名不匹配。

解决方法：

1. 重置 TCC 权限：

   tccutil reset All bot.molt.mac.debug
   

2. 如果上述方法无效，请暂时更改 scripts/package-mac-app.sh 中的 BUNDLE_ID 以强制 macOS 进入“干净状态”。

网关“正在启动…”无限期

如果网关状态保持在“正在启动…”，请检查是否有僵尸进程占用端口：

openclaw gateway status
openclaw gateway stop

# If you’re not using a LaunchAgent (dev mode / manual runs), find the listener:
lsof -nP -iTCP:18789 -sTCP:LISTEN

如果手动运行占用了该端口，请停止该进程（Ctrl+C）。作为最后手段，终止您找到的 PID。