macOS 本地部署 OpenClaw

本教程将指导您在 macOS 上完成 OpenClaw 的安装和配置，支持 Intel 和 Apple Silicon（M1/M2/M3/M4）芯片。

系统要求

  • 操作系统: macOS 12 Monterey 或更高版本
  • 处理器: Intel 或 Apple Silicon（M1/M2/M3/M4）
  • 内存: 8 GB RAM（推荐 16 GB）
  • 磁盘空间: 至少 2 GB 可用空间
  • 网络: 稳定的互联网连接
  • 软件依赖: Node.js ≥ 22.0.0、Homebrew（推荐）

安装步骤

步骤 1: 安装 Homebrew

Homebrew 是 macOS 上最流行的包管理器。如果尚未安装：

bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装完成后，按照终端提示将 Homebrew 添加到 PATH（Apple Silicon 用户需要额外步骤）：

bash
# Apple Silicon 用户需要执行
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

步骤 2: 安装 Node.js

OpenClaw 2026 版要求 Node.js ≥ 22.0.0：

bash
brew install node@22

或使用 nvm 管理多版本：

bash
# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.zshrc

# 安装 Node.js 22
nvm install 22
nvm use 22

验证版本：

bash
node --version   # 应显示 v22.x.x
npm --version

步骤 3: 安装 OpenClaw

方式 A：npm 全局安装（推荐）

bash
npm install -g openclaw

方式 B：从 GitHub Release 下载

bash
# 下载最新版本（根据芯片选择 arm64 或 x64）
curl -LO https://github.com/openclaw/openclaw/releases/latest/download/openclaw-macos-arm64.tar.gz

# 解压
tar -xzf openclaw-macos-arm64.tar.gz

# 移动到 PATH
sudo mv openclaw /usr/local/bin/

步骤 4: 初始化配置

bash
openclaw init

配置文件生成在 ~/.openclaw/config.yaml。

步骤 5: 配置百炼 API Key

获取百炼 API Key（查看详细申请购买教程），然后配置：

bash
openclaw config set model.provider "bailian"
openclaw config set model.apiKey "your-api-key-here"

获取 API Key：访问 阿里云百炼平台。

步骤 6: 启动 OpenClaw

bash
openclaw start

访问 http://localhost:18789 进入管理后台。

💡 提示: macOS 可能弹出"允许传入网络连接"的提示，点击"允许"即可。

安装验证

bash
# 检查服务状态
openclaw status

# 发送测试消息
openclaw test "你好"

# 在浏览器中访问
open http://localhost:18789

Apple Silicon 注意事项

M1/M2/M3/M4 芯片的 Mac 需要注意以下几点：

  • Homebrew 路径: Apple Silicon 上 Homebrew 安装在 /opt/homebrew/，而非 Intel 的 /usr/local/
  • Rosetta 2: 部分 npm 原生依赖可能需要 Rosetta 2 转译。如遇到编译错误，安装 Rosetta：
bash
softwareupdate --install-rosetta --agree-to-license
  • 权限问题: 如果遇到"无法验证开发者"的提示，在 系统设置 → 隐私与安全性 中点击"仍要打开"

常见问题

问题 1: Homebrew 安装失败

解决方案: 确保已安装 Xcode Command Line Tools：

bash
xcode-select --install

如果网络问题导致安装慢，可以使用国内镜像：

bash
/bin/bash -c "$(curl -fsSL https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh)"

问题 2: npm 权限问题

解决方案: 不要使用 sudo npm install -g，改为修改 npm 目录权限：

bash
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

问题 3: 端口被占用

解决方案:

bash
# 查找占用端口的进程
lsof -i :18789

# 终止进程
kill -9 <PID>

# 或修改端口
openclaw config set port 18790

问题 4: Apple Silicon 编译错误

解决方案: 安装 Rosetta 2 并重试：

bash
softwareupdate --install-rosetta --agree-to-license
npm install -g openclaw