14.1 开发配置

macOS伴侣应用macOS伴侣应用

本文档介绍如何在 macOS 上构建 OpenClaw 应用的开发环境配置。

前置要求

必需软件

  • Xcode 26.2 或更高版本
  • Node.js 22 或更高版本
  • pnpm 包管理器

构建步骤

1. 安装依赖

# 安装 Node.js 依赖
pnpm install

2. 打包应用

# 运行打包脚本
./scripts/package-mac-app.sh

该脚本会构建 macOS 应用程序包,默认使用临时签名(ad-hoc signing)。

3. 安装 CLI 工具

有两种方式安装 OpenClaw CLI:

方式一: 通过应用设置

  • 启动 OpenClaw.app
  • 打开设置面板
  • 在 CLI 部分点击安装

方式二: 通过 npm 全局安装

# 全局安装 OpenClaw CLI
npm install -g openclaw@latest

验证安装

# 查看版本
openclaw --version

# 查看帮助信息
openclaw --help

# 检查状态
openclaw status

常见问题排查

构建失败

  • 确认 Xcode 版本是否满足 26.2+
  • 检查 Node.js 版本是否为 22+
  • 确认已正确安装 pnpm: npm install -g pnpm
  • 清理并重新安装依赖: rm -rf node_modules && pnpm install

权限相关崩溃

如果应用启动时崩溃并显示 "Abort trap 6" 错误:

  • 检查系统隐私与安全性设置
  • 确认应用已被授予必要的权限
  • 查看控制台日志获取详细错误信息

Gateway 挂起

如果 Gateway 进程无响应:

  • 检查 Gateway 进程是否正常运行: ps aux | grep openclaw
  • 查看日志文件: ~/Library/Logs/OpenClaw/
  • 尝试重启应用

代码签名问题

  • 默认使用临时签名(ad-hoc signing),不需要 Apple 开发者证书
  • 如需发布或分发,需要使用有效的开发者证书进行签名
  • 检查签名状态: codesign -dv --verbose=4 /path/to/OpenClaw.app

开发工作流

日常开发

# 监听代码变更并自动重新构建
pnpm dev

# 运行测试
pnpm test

# 代码格式化
pnpm format

调试应用

  • 在 Xcode 中打开项目: open apps/macos/OpenClaw.xcodeproj
  • 使用 Xcode 调试器进行断点调试
  • 查看控制台输出和系统日志
相关资源