摘要：本文记录在搭载 Intel 芯片的 Mac（系统为 macOS Sequoia）上，从零开始安装 OpenClaw 时遇到的一系列典型报错（Homebrew 浅克隆、Node.js 版本不足、Sharp 依赖编译失败等）及其完整解决方案。通过手动修复环境、指定安装特定版本组件，最终成功完成安装。

一、适用条件与问题背景

1. 适用条件（必看！）

• 芯片类型：本文方案仅适配 Intel 架构的 Mac（如 MacBook Pro/Air Intel 版）。
• 系统版本：macOS Sequoia（本方案会解决 sequoia版本检测报错，其他 macOS 版本亦可参考）。
• ARM 芯片用户：若为 M1/M2/M3 等 ARM 架构 Mac，请跳转至文末的“M系列芯片适配说明”，仅需替换一个链接。

2. 问题背景

在 Intel 芯片的 macOS Sequoia 系统上，执行 OpenClaw 官方安装脚本 curl -fsSL |bash时，通常会触发一系列连锁报错：

• Homebrew 报错：homebrew-core is a shallow clone，无法正常更新。
• 系统版本检测失败：提示不支持的 macOS 版本 sequoia，导致通过 brew安装 Node.js@22 失败。
• npm install失败：安装 OpenClaw 时，其依赖的 sharp图像处理库因网络或编译问题安装失败。
• 版本校验不通过：OpenClaw 要求 Node.js ≥ 22.16.0，而系统现有或通过包管理器安装的版本过低。

下文将分步解决所有问题，直达成功。

二、核心解决方案（分步骤执行）

请严格按照顺序执行以下命令。

步骤 1：修复 Homebrew 核心仓库（解决 shallow clone 报错）

Homebrew 的 homebrew-core仓库状态异常，需重建并关联至国内镜像（以中科大为示例）。

# 1. 删除异常的 homebrew-core 目录 sudo rm -rf /usr/local/Homebrew/Library/Taps/homebrew/homebrew-core

2. 重建目录并修改权限

sudo mkdir -p /usr/local/Homebrew/Library/Taps/homebrew/homebrew-core sudo chown -R $(whoami) /usr/local/Homebrew/Library/Taps/homebrew

3. 初始化仓库并关联镜像

cd /usr/local/Homebrew/Library/Taps/homebrew/homebrew-core git init git remote add origin https://mirrors.ustc.edu.cn/homebrew-core.git git fetch –depth=1 origin main git checkout -b main origin/main

4. 解除浅克隆限制（使Homebrew可正常更新）

git -C /usr/local/Homebrew/Library/Taps/homebrew/homebrew-core fetch –unshallow

5. 更新Homebrew

brew update

步骤 2：清理 Homebrew 锁定文件（解决进程锁定报错）

清理可能存在的下载缓存锁，避免更新或安装时冲突。

GPT plus 代充 只需 145rm -rf /Users/$(whoami)/Library/Caches/Homebrew/downloads/*.incomplete

步骤 3：手动安装 Node.js 22.16.0（Intel Mac 专属）

为绕过 brew可能存在的版本兼容问题，我们直接下载官方二进制包进行安装。

# 1. 下载 Node.js 22.16.0 官方包 (Intel版本， darwin-x64) curl -fsSL https://nodejs.org/dist/v22.16.0/node-v22.16.0-darwin-x64.tar.gz -o /tmp/node22.tar.gz

2. 解压到Homebrew的标准软件目录，保持路径规范

sudo mkdir -p /usr/local/Cellar/node@²²⁄₂₂.16.0 sudo tar -xzf /tmp/node22.tar.gz -C /usr/local/Cellar/node@²²⁄₂₂.16.0 –strip-components=1

3. 创建全局软链接，使 node, npm, npx 命令生效

sudo ln -sf /usr/local/Cellar/node@²²⁄₂₂.16.0/bin/node /usr/local/bin/node sudo ln -sf /usr/local/Cellar/node@²²⁄₂₂.16.0/bin/npm /usr/local/bin/npm sudo ln -sf /usr/local/Cellar/node@²²⁄₂₂.16.0/bin/npx /usr/local/bin/npx

4. 清理临时文件并修复目录权限

rm -f /tmp/node22.tar.gz sudo chown -R \((whoami) /usr/local/Cellar/node@22 sudo chown -R \)(whoami) /usr/local/bin/node /usr/local/bin/npm /usr/local/bin/npx

5. 【关键】验证安装

node -v # 预期输出：v22.16.0 npm -v # 预期输出：10.7.0 或相近版本 which node # 预期输出：/usr/local/bin/node

步骤 4：配置 Sharp 依赖镜像（解决 OpenClaw 安装失败）

OpenClaw 依赖的 sharp库在国内下载预编译二进制文件经常失败，必须配置国内镜像。

GPT plus 代充 只需 145# 设置 Sharp 国内镜像（至关重要！） export SHARP_DIST_BASE_URL="https://npmmirror.com/mirrors/sharp-libvips/" export SHARP_IGNORE_GLOBAL_LIBVIPS=1

重新执行 OpenClaw 官方安装脚本

curl -fsSL https://openclaw.ai/install.sh | bash

注意：如果 openclaw.ai的安装脚本因网络问题无法访问（链接内容显示ERR_EMPTY_RESPONSE），你可能需要寻找该脚本的替代源或离线安装方案。本文档中的链接内容显示该安装脚本链接当前可能无法访问。

三、安装结果验证

执行完所有步骤后，使用以下命令验证环境是否就绪：

# 1. 验证 Node.js 版本（必须为 22.16.0 或更高） node -v

2. 验证 OpenClaw 是否安装成功

openclaw -v

成功则会输出版本号，如 v2026.3.13

四、常见问题排查 (Q&A)

1、权限报错 (EACCES)

• 在所有需要系统目录操作的命令前加 sudo。
• 或执行 sudo chown -R $(whoami) /usr/local/Cellar修复整个目录的归属。

2、node或 npm命令未找到

• 执行 which node，检查输出是否为 /usr/local/bin/node。
• 如果不是，请返回步骤3，重新执行创建软链接的命令。

3、Sharp 依赖依然编译/下载失败

• 确认 SHARP_DIST_BASE_URL环境变量已正确设置。
• 可以在执行 npm install或 OpenClaw 安装脚本前，重新执行一次 export SHARP_DIST_BASE_URL=…命令。

4、架构不兼容报错

• 如果提示 “Architecture mismatch” 等错误，请务必确认你下载的 Node.js 包与芯片匹配。本文步骤3使用的是 Intel (darwin-x64) 的链接。

五、M1/M2/M3 芯片适配说明

如果您使用的是 Apple Silicon (ARM架构) 的 Mac，解决方案完全一致，只需修改一个地方：

在 步骤3 的第1条命令​ 中，将 Node.js 下载链接替换为 ARM 版本：

GPT plus 代充 只需 145# 将原Intel版下载命令替换为以下命令（针对M1/M2/M3）： curl -fsSL https://nodejs.org/dist/v22.16.0/node-v22.16.0-darwin-arm64.tar.gz -o /tmp/node22.tar.gz

其余所有步骤与 Intel 版本完全一致。

结语：通过以上步骤，可以系统性地解决在 Intel Mac 上安装 OpenClaw 遇到的环境依赖问题。核心思路是：修复 Homebrew 源 -> 手动安装指定版本的 Node.js -> 为 npm 依赖配置国内镜像。希望这篇指南能帮助到大家。