macOS 开发者环境配置

本文介绍从源码构建和运行 OpenClaw macOS 应用的必要步骤。

前提条件

开始构建前，确保已安装以下内容：

1. Xcode 26.2+：Swift 开发必需。
2. Node.js 24 & pnpm：推荐用于 Gateway、CLI 和打包脚本。Node 22 LTS（当前 22.14+）仍支持兼容。

1. 安装依赖

安装项目级依赖：

pnpm install

2. 构建并打包应用

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

./scripts/package-mac-app.sh

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

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

注意：临时签名的应用可能触发安全提示。如果应用立即崩溃并显示"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 工具链。

系统依赖（必需）：

• 软件更新中最新的 macOS 版本（Xcode 26.2 SDK 要求）
• Xcode 26.2（Swift 6.2 工具链）

检查命令：

xcodebuild -version
xcrun swift --version

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

授权权限时应用崩溃

如果在允许语音识别或麦克风访问时应用崩溃，可能是 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）。万不得已时，杀掉上面找到的 PID。