给mac本搭建openclaw

原创已于 2026-03-12 11:43:18 修改 · 1.6k 阅读

7 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

于 2026-03-12 11:18:26 首次发布

AI 时代程序员必备技能

Codex、Claude Code、Cursor、Hermes Agent、OpenClaw等工程化实战专栏，讲透 AI 如何接管脏活累活

一键订阅

为您整理了一份专为 Apple Silicon (M1/M2/M3/M4) 芯片 MacBook 优化的 OpenClaw 安装教程。针对 M 芯片的特性进行了全面调整，所有镜像源均使用阿里云镜像，并重点处理了 SSL 证书和架构兼容性问题。

🍎 Apple Silicon M芯片 MacBook 安装 OpenClaw 完全指南（阿里云镜像版）

📋 针对 M 芯片的特别优化说明

优化项	说明
Homebrew 安装路径	M 芯片 Mac 默认安装路径为 `/opt/homebrew`，与 Intel 芯片的 `/usr/local` 不同
Node.js 架构	确保安装 ARM64 版本的 Node.js，获得最佳性能和兼容性
Rosetta 2 兼容性	部分旧版工具可能需要 Rosetta 2 转译，本教程已规避此问题
SSL 证书路径	M 芯片 Mac 的证书路径与 Intel 版本一致，但需特别处理 npm 镜像的 SSL 验证
环境变量配置	根据 M 芯片的 shell 配置调整 PATH 设置

⚙️ 第一阶段：安装基础工具

1️⃣ 检查芯片型号

首先确认你的 Mac 确实是 Apple Silicon 芯片：

uname -m

预期输出: arm64 （如果是 x86_64，说明正在使用 Rosetta 2 转译模式，请退出终端并重新打开原生终端）

2️⃣ 安装 Homebrew（ARM64 原生版本）

Apple Silicon 芯片需要安装原生 ARM64 版本的 Homebrew，安装路径为 /opt/homebrew。

步骤 1：设置阿里云镜像源环境变量

# 设置 Homebrew 所有仓库和二进制文件使用阿里云镜像
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.aliyun.com/homebrew/brew.git"
export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.aliyun.com/homebrew/homebrew-core.git"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.aliyun.com/homebrew/homebrew-bottles"
export HOMEBREW_API_DOMAIN="https://mirrors.aliyun.com/homebrew-bottles/api"

步骤 2：执行安装命令

/bin/bash -c "$(curl -fsSL https://mirrors.aliyun.com/homebrew/install/install.sh)"

步骤 3：将 Homebrew 添加到 PATH
安装完成后，终端会提示你运行以下命令。注意：M 芯片 Mac 的路径是 /opt/homebrew/bin，请务必按提示执行：

# 查看提示信息，找到类似下面的命令（具体路径以屏幕提示为准）
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

步骤 4：验证安装

brew --version
# 检查安装路径是否正确（应该显示 /opt/homebrew）
which brew
# 预期输出: /opt/homebrew/bin/brew

步骤 5：配置 Homebrew 镜像为阿里云（永久生效）

# 设置 brew 命令使用的镜像源
echo 'export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.aliyun.com/homebrew/brew.git"' >> ~/.zshrc
echo 'export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.aliyun.com/homebrew/homebrew-core.git"' >> ~/.zshrc
echo 'export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.aliyun.com/homebrew/homebrew-bottles"' >> ~/.zshrc
echo 'export HOMEBREW_API_DOMAIN="https://mirrors.aliyun.com/homebrew-bottles/api"' >> ~/.zshrc
source ~/.zshrc

3️⃣ 安装 Git（ARM64 原生版本）

brew install git

验证安装：

git --version
# 检查架构（应该显示 aarch64 或 arm64）
file $(which git)
# 预期输出包含: Mach-O 64-bit executable arm64

4️⃣ 安装 Node.js（ARM64 原生版本）

Apple Silicon 芯片需要安装 ARM64 版本的 Node.js 以获得最佳性能。

步骤 1：通过 Homebrew 安装 Node.js

brew install node

Homebrew 会自动检测芯片架构并安装对应的 ARM64 版本。

步骤 2：验证架构和版本

node --version
# 检查 Node.js 架构（必须显示 arm64）
node -p "process.arch"
# 预期输出: arm64

npm --version

步骤 3：配置 npm 阿里云镜像（解决 SSL 和下载加速）

# 设置 npm 全局镜像源为阿里云镜像
npm config set registry https://registry.npmmirror.com/

# 设置 npm 的 strict-ssl 为 false（解决可能的证书问题）
npm config set strict-ssl false

# 验证配置
npm config get registry
npm config get strict-ssl

步骤 4：配置 npm 全局安装路径（避免权限问题）

# 创建 npm 全局目录（使用用户目录避免权限问题）
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

# 将 npm 全局 bin 目录添加到 PATH
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

🚀 第二阶段：安装 OpenClaw

1️⃣ 通过 npm 全局安装 OpenClaw

# 由于已配置阿里云镜像，安装会非常快
npm install -g openclaw

如果遇到权限问题，可以使用：

sudo npm install -g openclaw

2️⃣ 验证安装

openclaw --version

如果提示 command not found，检查 PATH 配置：

# 查看 npm 全局安装位置
npm config get prefix
# 确保该路径下的 bin 目录在 PATH 中
echo $PATH | grep $(npm config get prefix)

🔐 第三阶段：SSL 证书配置（M 芯片特别处理）

Apple Silicon 芯片在处理某些旧版 SSL 证书时可能遇到验证问题。以下是完整的解决方案：

1️⃣ 更新系统 CA 证书

# 通过 Homebrew 安装最新的证书包
brew install ca-certificates

# 更新 OpenSSL 证书
brew install openssl@3

2️⃣ 配置 Node.js SSL 证书（可选）

如果遇到 SSL 证书错误，可以指定使用系统证书：

# 设置 Node.js 使用系统的证书
export NODE_EXTRA_CA_CERTS=/etc/ssl/cert.pem
# 将配置永久添加到 shell
echo 'export NODE_EXTRA_CA_CERTS=/etc/ssl/cert.pem' >> ~/.zshrc

3️⃣ 验证 SSL 配置

# 测试 npm 是否能正常访问阿里云镜像
curl -I https://registry.npmmirror.com/
# 应该返回 HTTP/2 200

# 测试 Node.js 的 https 请求
node -e "https.get('https://registry.npmmirror.com/', (res) => console.log('SSL OK:', res.statusCode))"

⚡ 第四阶段：初始化 OpenClaw

1️⃣ 运行配置向导

openclaw onboard

注意：初次运行时，可能会提示安装一些依赖，按 y 确认即可。

2️⃣ 启动 Gateway 服务

openclaw gateway start

3️⃣ 检查服务状态

openclaw status

4️⃣ 运行健康检查

openclaw doctor

如果 doctor 报告任何与架构相关的问题，请记录并参考后面的故障排除部分。

5️⃣ 访问 Web 控制台

openclaw dashboard

或手动在浏览器中打开：http://localhost:18789

🧠 第五阶段：配置 AI 模型（阿里云百炼专版）

1️⃣ 获取阿里云 API Key

访问阿里云百炼平台
创建 API Key（以 sk- 开头）

2️⃣ 配置 OpenClaw

openclaw configure

按照交互提示输入：

模型提供商: 选择 Custom 或 OpenAI Compatible
BASE URL: https://dashscope.aliyuncs.com/compatible-mode/v1
API Key: 粘贴你的 sk-xxx
模型名称: 例如 qwen-max 或 qwen-plus

🔧 故障排除（M 芯片专版）

问题 1：安装 Homebrew 时提示路径错误

症状：安装脚本提示 /usr/local 不可写
解决方案：M 芯片 Mac 应安装到 /opt/homebrew，确保已按教程设置环境变量

问题 2：Node.js 显示为 x64 架构

症状：node -p "process.arch" 输出 x64
原因：终端运行在 Rosetta 2 转译模式下
解决方案：

# 检查终端应用信息，确保使用 ARM64 版本
# 在终端中执行
arch
# 应该输出 arm64，如果是 i386 则需要重新安装终端

问题 3：SSL 证书错误

症状：Error: self signed certificate in certificate chain
解决方案：

# 方案 A：更新 CA 证书
brew reinstall ca-certificates

# 方案 B：临时允许（不推荐长期使用）
npm config set strict-ssl false

问题 4：npm 安装 openclaw 失败

症状：安装过程中断，提示网络错误
解决方案：

# 清理 npm 缓存
npm cache clean --force

# 使用阿里云镜像重试
npm install -g openclaw --registry=https://registry.npmmirror.com/

问题 5：openclaw 命令找不到

症状：安装成功但输入 openclaw 提示 command not found
解决方案：

# 查找 openclaw 安装位置
find ~/.npm-global -name "openclaw" -type f 2>/dev/null
# 或
find /opt/homebrew -name "openclaw" -type f 2>/dev/null

# 将找到的路径添加到 PATH
export PATH=/路径/to/bin:$PATH

✅ 最终验证清单

执行以下命令，验证所有组件是否正确安装：

# 1. 检查芯片架构
uname -m  # 应为 arm64

# 2. 检查 Homebrew
brew --version
which brew  # 应为 /opt/homebrew/bin/brew

# 3. 检查 Node.js 架构
node -p "process.arch"  # 应为 arm64

# 4. 检查 npm 镜像配置
npm config get registry  # 应为 https://registry.npmmirror.com/

# 5. 检查 OpenClaw
openclaw --version
openclaw status

# 6. 检查服务
curl http://localhost:18789  # 应返回 HTML 内容