Skip to main content

​
macOS 开发者设置

从源代码构建并运行 OpenClaw macOS 应用。

​
先决条件

  • Xcode 26.2+（Swift 6.2 工具链），在 Software Update 中可用的最新 macOS 上。
  • Node.js 24.15+ 和 pnpm，用于网关、CLI 和打包脚本。Node 22.22.3+ 也可以。

​
1. 安装依赖

​
2. 构建并打包应用

输出 dist/OpenClaw.app。如果没有 Apple Developer ID 证书， 脚本会回退到临时签名。 有关开发运行模式、签名标志以及 Team ID 故障排查，请参见 apps/macos/README.md。 从仓库根目录快速进行开发循环：scripts/restart-mac.sh（添加 --no-sign 可进行 临时签名；使用 --no-sign 时，TCC 权限不会保留）。
临时签名的应用可能会触发安全提示。如果应用 立即崩溃并显示“Abort trap 6”，请参见故障排查。

​
3. 安装 CLI 和 Gateway

打包后的应用内置了权威的 scripts/install-cli.sh 安装程序。在一个 全新的配置文件中，在引导过程中选择 This Mac；应用会先安装 匹配的用户空间 CLI 和运行时，然后再启动 Gateway 向导。 对于手动开发恢复，请自行安装匹配的 CLI：
pnpm add -g openclaw@<version> 和 bun add -g openclaw@<version> 也 可以使用。对于 Gateway 本身，仍然推荐使用 Node 运行时。

​
故障排查

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

macOS 应用构建需要最新的 macOS SDK 和 Swift 6.2 工具链 （Xcode 26.2+）。
如果版本不匹配，请更新 macOS/Xcode 后重新运行构建。

​
授权后应用崩溃

如果你在尝试允许 Speech Recognition 或 Microphone 访问时应用崩溃，可能是 TCC 缓存损坏或签名不匹配。
  1. 为调试 bundle id 重置 TCC 权限：
  2. 如果仍然失败，临时修改 scripts/package-mac-app.sh 中的 BUNDLE_ID，以强制 macOS 创建一个全新的状态。

​
Gateway 一直显示“Starting…”

检查是否有僵尸进程占用了该端口：
如果是手动运行占用了端口，请停止它（Ctrl+C），或者最后手段是杀掉上面找到的 PID。

​
相关内容