• 芯片類(lèi)型：本文方案僅適配 Intel 架構(gòu)的 Mac（如 MacBook Pro/Air Intel 版）。
• 系統(tǒng)版本：macOS Sequoia（本方案會(huì)解決 sequoia版本檢測(cè)報(bào)錯(cuò)，其他 macOS 版本亦可參考）。
• ARM 芯片用戶：若為 M1/M2/M3 等 ARM 架構(gòu) Mac，請(qǐng)?zhí)D(zhuǎn)至文末的“M系列芯片適配說(shuō)明”，僅需替換一個(gè)鏈接。

2. 問(wèn)題背景

在 Intel 芯片的 macOS Sequoia 系統(tǒng)上，執(zhí)行 OpenClaw 官方安裝腳本 curl -fsSL |bash時(shí)，通常會(huì)觸發(fā)一系列連鎖報(bào)錯(cuò)：

• Homebrew 報(bào)錯(cuò)：homebrew-core is a shallow clone，無(wú)法正常更新。
• 系統(tǒng)版本檢測(cè)失?。禾崾静恢С值?macOS 版本 sequoia，導(dǎo)致通過(guò) brew安裝 Node.js@22 失敗。
• npm install失?。喊惭b OpenClaw 時(shí)，其依賴的 sharp圖像處理庫(kù)因網(wǎng)絡(luò)或編譯問(wèn)題安裝失敗。
• 版本校驗(yàn)不通過(guò)：OpenClaw 要求 Node.js ≥ 22.16.0，而系統(tǒng)現(xiàn)有或通過(guò)包管理器安裝的版本過(guò)低。

報(bào)錯(cuò)圖片

下文將分步解決所有問(wèn)題，直達(dá)成功。

二、核心解決方案（分步驟執(zhí)行）

請(qǐng)嚴(yán)格按照順序執(zhí)行以下命令。

步驟 1：修復(fù) Homebrew 核心倉(cāng)庫(kù)（解決 shallow clone 報(bào)錯(cuò)）

Homebrew 的 homebrew-core倉(cāng)庫(kù)狀態(tài)異常，需重建并關(guān)聯(lián)至國(guó)內(nèi)鏡像（以中科大為示例）。

# 1. 刪除異常的 homebrew-core 目錄
sudo rm -rf /usr/local/Homebrew/Library/Taps/homebrew/homebrew-core
# 2. 重建目錄并修改權(quán)限
sudo mkdir -p /usr/local/Homebrew/Library/Taps/homebrew/homebrew-core
sudo chown -R $(whoami) /usr/local/Homebrew/Library/Taps/homebrew
# 3. 初始化倉(cāng)庫(kù)并關(guān)聯(lián)鏡像
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 鎖定文件（解決進(jìn)程鎖定報(bào)錯(cuò)）

清理可能存在的下載緩存鎖，避免更新或安裝時(shí)沖突。

rm -rf /Users/$(whoami)/Library/Caches/Homebrew/downloads/*.incomplete

步驟 3：手動(dòng)安裝 Node.js 22.16.0（Intel Mac 專(zhuān)屬）

為繞過(guò) brew可能存在的版本兼容問(wèn)題，我們直接下載官方二進(jìn)制包進(jìn)行安裝。

# 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的標(biāo)準(zhǔn)軟件目錄，保持路徑規(guī)范
sudo mkdir -p /usr/local/Cellar/node@22/22.16.0
sudo tar -xzf /tmp/node22.tar.gz -C /usr/local/Cellar/node@22/22.16.0 --strip-components=1

# 3. 創(chuàng)建全局軟鏈接，使 node, npm, npx 命令生效
sudo ln -sf /usr/local/Cellar/node@22/22.16.0/bin/node /usr/local/bin/node
sudo ln -sf /usr/local/Cellar/node@22/22.16.0/bin/npm /usr/local/bin/npm
sudo ln -sf /usr/local/Cellar/node@22/22.16.0/bin/npx /usr/local/bin/npx

# 4. 清理臨時(shí)文件并修復(fù)目錄權(quán)限
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. 【關(guān)鍵】驗(yàn)證安裝
node -v  # 預(yù)期輸出：v22.16.0
npm -v   # 預(yù)期輸出：10.7.0 或相近版本
which node  # 預(yù)期輸出：/usr/local/bin/node

步驟 4：配置 Sharp 依賴鏡像（解決 OpenClaw 安裝失?。?/h3>

OpenClaw 依賴的 sharp庫(kù)在國(guó)內(nèi)下載預(yù)編譯二進(jìn)制文件經(jīng)常失敗，必須配置國(guó)內(nèi)鏡像。

# 設(shè)置 Sharp 國(guó)內(nèi)鏡像（至關(guān)重要?。?
export SHARP_DIST_BASE_URL="https://npmmirror.com/mirrors/sharp-libvips/"
export SHARP_IGNORE_GLOBAL_LIBVIPS=1

# 重新執(zhí)行 OpenClaw 官方安裝腳本
curl -fsSL https://openclaw.ai/install.sh | bash

注意：如果 openclaw.ai的安裝腳本因網(wǎng)絡(luò)問(wèn)題無(wú)法訪問(wèn)（鏈接內(nèi)容顯示ERR_EMPTY_RESPONSE），你可能需要尋找該腳本的替代源或離線安裝方案。本文檔中的鏈接內(nèi)容顯示該安裝腳本鏈接當(dāng)前可能無(wú)法訪問(wèn)。

三、安裝結(jié)果驗(yàn)證

執(zhí)行完所有步驟后，使用以下命令驗(yàn)證環(huán)境是否就緒：

# 1. 驗(yàn)證 Node.js 版本（必須為 22.16.0 或更高）
node -v

# 2. 驗(yàn)證 OpenClaw 是否安裝成功
openclaw -v
# 成功則會(huì)輸出版本號(hào)，如 v2026.3.13

安裝成功

四、常見(jiàn)問(wèn)題排查 (Q&A)

1、權(quán)限報(bào)錯(cuò) (EACCES)

• 在所有需要系統(tǒng)目錄操作的命令前加 sudo。
• 或執(zhí)行 sudo chown -R $(whoami) /usr/local/Cellar修復(fù)整個(gè)目錄的歸屬。

2、node或 npm命令未找到

• 執(zhí)行 which node，檢查輸出是否為 /usr/local/bin/node。
• 如果不是，請(qǐng)返回步驟3，重新執(zhí)行創(chuàng)建軟鏈接的命令。

3、Sharp 依賴依然編譯/下載失敗

• 確認(rèn) SHARP_DIST_BASE_URL環(huán)境變量已正確設(shè)置。
• 可以在執(zhí)行 npm install或 OpenClaw 安裝腳本前，重新執(zhí)行一次 export SHARP_DIST_BASE_URL=...命令。

4、架構(gòu)不兼容報(bào)錯(cuò)

• 如果提示 “Architecture mismatch” 等錯(cuò)誤，請(qǐng)務(wù)必確認(rèn)你下載的 Node.js 包與芯片匹配。本文步驟3使用的是 Intel (darwin-x64) 的鏈接。

五、M1/M2/M3 芯片適配說(shuō)明

如果您使用的是 Apple Silicon (ARM架構(gòu)) 的 Mac，解決方案完全一致，只需修改一個(gè)地方：

在 步驟3 的第1條命令? 中，將 Node.js 下載鏈接替換為 ARM 版本：

# 將原Intel版下載命令替換為以下命令（針對(duì)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 版本完全一致。

結(jié)語(yǔ)：通過(guò)以上步驟，可以系統(tǒng)性地解決在 Intel Mac 上安裝 OpenClaw 遇到的環(huán)境依賴問(wèn)題。核心思路是：修復(fù) Homebrew 源 -> 手動(dòng)安裝指定版本的 Node.js -> 為 npm 依賴配置國(guó)內(nèi)鏡像。希望這篇指南能幫助到大家。

以上就是macOS本地安裝OpenClaw全流程：從報(bào)錯(cuò)到最終成功的詳細(xì)內(nèi)容，更多關(guān)于macOS本地安裝OpenClaw全流程的資料請(qǐng)關(guān)注腳本之家其它相關(guān)文章！