1. OpenClaw 在 macOS 上的安装准备
OpenClaw 是一个跨平台的开发工具集,在 macOS 上安装需要做好以下准备工作。首先确保你的 Mac 满足以下系统要求:
- macOS Monterey (12.0) 或更高版本
- 至少 8GB 内存
- 至少 20GB 可用存储空间
- 管理员权限
提示:建议使用较新的 Mac 机型(2018年及之后),因为某些功能如神经引擎加速需要较新的硬件支持。
1.1 开发工具链安装
在开始安装 OpenClaw 之前,需要先配置好开发环境:
- 安装 Xcode 命令行工具:
bash复制xcode-select --install
- 安装 Homebrew(如果尚未安装):
bash复制/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
- 通过 Homebrew 安装必要的依赖:
bash复制brew install node@18 pnpm git
- 配置 Node.js 环境变量:
bash复制echo 'export PATH="/opt/homebrew/opt/node@18/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
1.2 环境验证
安装完成后,运行以下命令验证环境是否配置正确:
bash复制node -v # 应显示 v18.x.x
pnpm -v # 应显示 8.x.x
git --version # 应显示 2.x.x
xcodebuild -version # 应显示 Xcode 14.x 或更高
如果任何命令返回错误或版本不符,请先解决这些问题再继续。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. OpenClaw 核心安装流程
2.1 通过官方应用安装
最简单的安装方式是使用官方提供的 macOS 应用:
- 从 OpenClaw 官网下载最新的 .dmg 文件
- 双击打开下载的镜像文件
- 将 OpenClaw 应用拖拽到 Applications 文件夹
- 首次运行时需要在系统偏好设置 > 安全性与隐私中允许应用运行
安装完成后,应用会自动引导你完成初始设置,包括安装 CLI 工具和配置基础环境。
2.2 通过源码编译安装
对于开发者或需要自定义构建的用户,可以从源码编译安装:
- 克隆仓库:
bash复制git clone https://github.com/openclaw/openclaw.git
cd openclaw
- 安装项目依赖:
bash复制pnpm install
- 构建 macOS 应用:
bash复制./scripts/package-mac-app.sh
- 构建完成后,应用会生成在 dist/OpenClaw.app,可以手动拖到 Applications 文件夹
注意:源码编译需要 Xcode 完整安装(不仅仅是命令行工具),且会占用较多磁盘空间。
3. CLI 工具安装与配置
OpenClaw 命令行工具是管理后台任务和开发工作流的核心组件。
3.1 通过应用安装 CLI
推荐的方式是通过已安装的 OpenClaw 应用安装 CLI:
- 打开 OpenClaw 应用
- 进入 Preferences > General
- 点击 "Install CLI" 按钮
- 按照提示完成安装
3.2 手动安装 CLI
如果应用安装失败,可以手动安装:
bash复制npm install -g openclaw@latest
安装完成后验证:
bash复制openclaw --version
3.3 CLI 常用命令
安装完成后,可以开始使用 CLI 工具:
- 检查服务状态:
bash复制openclaw status
- 启动网关服务:
bash复制openclaw gateway start
- 查看日志:
bash复制openclaw logs
- 更新 CLI 工具:
bash复制openclaw update
4. 常见问题排查
4.1 应用启动崩溃
如果应用启动后立即崩溃,可能是签名问题导致:
- 尝试重置应用权限:
bash复制tccutil reset All ai.openclaw.mac.debug
- 如果是源码编译版本,尝试使用临时签名:
bash复制codesign --force --deep --sign - /Applications/OpenClaw.app
- 检查控制台日志获取详细错误信息:
bash复制log show --predicate 'process == "OpenClaw"' --last 1h
4.2 网关服务无法启动
如果网关状态一直显示"正在启动...":
- 检查端口占用:
bash复制lsof -nP -iTCP:18789 -sTCP:LISTEN
- 停止占用端口的进程:
bash复制kill -9 <PID>
- 完全重置网关服务:
bash复制openclaw gateway reset
4.3 权限问题
某些功能需要额外权限:
- 麦克风访问:系统偏好设置 > 安全性与隐私 > 麦克风
- 辅助功能:系统偏好设置 > 安全性与隐私 > 辅助功能
- 完全磁盘访问:系统偏好设置 > 安全性与隐私 > 完全磁盘访问
每次添加权限后,建议重启应用。
5. 进阶配置与优化
5.1 开发模式运行
对于开发者,可以启用开发模式获取更多日志和调试功能:
bash复制openclaw dev
这会启动一个带有实时重载的开发服务器,并打开调试控制台。
5.2 自定义构建配置
通过修改项目根目录下的 openclaw.config.js 可以调整构建参数:
javascript复制module.exports = {
mac: {
bundleId: 'com.yourcompany.openclaw',
teamId: 'YOUR_TEAM_ID', // 用于正式签名
entitlements: {
// 调整应用权限
'com.apple.security.app-sandbox': true,
'com.apple.security.network.client': true
}
}
}
5.3 性能优化
对于资源密集型任务,可以调整内存限制:
bash复制openclaw config set memory.limit 4096 # 设置为4GB
也可以启用硬件加速:
bash复制openclaw config set hardware.accelerate true
6. 日常维护与更新
6.1 检查更新
定期检查更新可以确保获得最新功能和安全修复:
bash复制openclaw update check
6.2 备份配置
建议定期备份你的配置:
bash复制openclaw config backup ~/openclaw_backup
6.3 卸载 OpenClaw
如果需要完全卸载:
- 删除应用:
bash复制rm -rf /Applications/OpenClaw.app
- 删除 CLI 工具:
bash复制npm uninstall -g openclaw
- 清理残留文件:
bash复制rm -rf ~/.openclaw
rm -rf ~/Library/Application\ Support/OpenClaw
rm -rf ~/Library/Caches/ai.openclaw.mac
rm -rf ~/Library/Preferences/ai.openclaw.mac.plist
7. 实际使用技巧
7.1 快捷键配置
可以在应用设置中自定义快捷键,或直接编辑配置文件:
bash复制openclaw config edit shortcuts
7.2 插件管理
OpenClaw 支持通过插件扩展功能:
- 列出可用插件:
bash复制openclaw plugin list
- 安装插件:
bash复制openclaw plugin install <plugin-name>
- 更新所有插件:
bash复制openclaw plugin update --all
7.3 多项目管理
对于同时处理多个项目的开发者:
bash复制openclaw project create my-project
openclaw project switch my-project
openclaw project list
每个项目都有独立的配置和环境。
