无尘阁日记

无尘阁日记

macOS 12 安装 OpenClaw 全流程实战教程：从踩坑到跑通，一次讲透
2026-03-22

这篇教程，不是照着官网机械翻译出来的“标准答案”，而是基于我们昨天在一台 macOS 12 的 MacBook Air 上，真实一步一步排障、修复、安装 OpenClaw 的完整过程整理出来的实战版教程。

它最大的价值不在于“理论上怎么安装”，而在于：

你下一次再装的时候，可以直接照着做，尽量少走弯路。
尤其是那些我们已经踩过的坑，这次我会重点标出来，并把正确处理顺序写清楚。

这篇教程适合的人群是：

适合使用 macOS 12 的用户
适合中国大陆网络环境下安装 OpenClaw 的用户
适合之前装 Node、brew、GitHub 访问、npm 安装经常报错的用户
适合希望“从零开始，一步步照着执行就能跑通”的用户

一、先说最终结论：这次安装卡住的根因到底有哪些

我们这次安装 OpenClaw，表面上看像是“总在报错”，但本质上主要是以下几个问题叠加造成的。

1. Homebrew 访问 GitHub 原始资源失败

最早安装 Node 的时候，Homebrew 需要访问：

raw.githubusercontent.com

但这个域名在当前网络环境下访问不稳定，导致 brew install node 失败。

2. 终端里残留了错误代理配置

一开始终端里配了：

http_proxy=http://127.0.0.1:7890
https_proxy=http://127.0.0.1:7890

但本机 7890 端口根本没有代理服务在运行，导致所有网络请求都被错误转发到一个不存在的代理上。

3. 多次重复执行 brew 命令，导致锁文件残留

前一个 brew install node 还没正常结束，又再次执行新的安装命令，导致 Homebrew 一直提示：

process has already locked

4. OpenClaw 的 Git 安装方式依赖 GitHub 仓库直连

使用 --install-method git 时，安装器会直接执行 git clone https://github.com/openclaw/openclaw.git，而当终端访问 GitHub 不稳定时，这一步直接失败。

5. npm 安装阶段又遇到依赖通过 SSH 拉 GitHub 仓库

OpenClaw 某个依赖不是走普通 npm 包下载，而是走：

ssh://git@github.com/...

这时如果本机没有配置 GitHub SSH Key，就会报：

Permission denied (publickey)

所以，这次整个安装过程不是一个单点问题，而是：

网络问题、brew 镜像问题、锁文件问题、npm 问题、Git SSH 问题一起叠加。

二、安装前你要先明白一个现实

macOS 12 不是最友好的环境

Homebrew 会提示：

你正在使用 macOS 12
这是一个较老的系统
支持层级较低

这并不代表一定装不上，但意味着：

你遇到兼容性、网络、依赖、下载问题的概率会比新系统更高。

重点提醒：macOS 12 不是不能装，而是更需要按顺序来，不能乱试、不能一边报错一边反复重装。

三、正确的整体安装顺序

下一次你重新装，请严格按这个顺序来：

第一步，处理终端网络环境
第二步，处理 Homebrew 国内镜像
第三步，安装并验证 Node
第四步，处理 npm 国内源
第五步，修复 GitHub SSH 依赖问题
第六步，安装 OpenClaw
第七步，执行 OpenClaw 初始化

这个顺序很重要。
很多人失败，不是因为命令不会，而是顺序错了。

四、第一步：先清理终端里的错误代理配置

我们这次一开始最大的坑之一，就是终端里有错误代理配置，但本地代理并没有真正启动。

先执行： 

unset http_proxy
unset https_proxy
unset HTTP_PROXY
unset HTTPS_PROXY
unset all_proxy
unset ALL_PROXY
env | grep -i proxy

如果最后没有任何输出，说明终端代理变量已经清干净了。

如果还有输出，说明你还有残留代理配置，需要继续处理。

你还可以检查这些代理配置是不是写进了启动文件： 

grep -n "127.0.0.1:7890" ~/.zshrc ~/.bash_profile ~/.bashrc ~/.zprofile 2>/dev/null

如果查到了类似： 

export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890

就把它删掉或者注释掉，然后执行： 

source ~/.zshrc

如果你改的是别的文件，就 source 对应文件。

重点提醒：如果本机没有真正运行代理软件，就千万不要乱设 127.0.0.1:7890 这种代理地址。否则终端所有网络请求都会被你自己堵死。

五、第二步：给 Homebrew 配置国内镜像

因为 raw.githubusercontent.com 在中国大陆网络环境下容易不稳定，所以我们后来切换了 Homebrew 镜像。

将以下内容写入 ~/.zshrc： 

echo 'export HOMEBREW_API_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api"' >> ~/.zshrc
echo 'export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"' >> ~/.zshrc
source ~/.zshrc

这样做的作用是：

让 Homebrew 尽量通过国内镜像拉取 API 和 bottle 资源，而不是直接去海外地址。

然后执行安装时，如果看到类似：

API Source node.rb
Verified ...

说明镜像已经生效了。

重点提醒：如果你不先处理镜像，Homebrew 很可能在下载 node.rb 这一步就卡住。

六、第三步：安装 Node，并处理 Homebrew 锁文件问题

安装 Node： 

brew install node

如果这一步报：

A brew install node process has already locked ...

那说明你之前有残留的 brew 进程或者未完成文件。

这时候不要继续重复执行 brew install node，而要先清理。

先看是否有挂起任务： 

jobs

如果有挂起任务，比如：

suspended brew install node

用下面命令杀掉： 

kill %1

然后杀掉残留 brew 进程： 

pkill -f "brew install node"
pkill -f "brew install"
pkill -f brew

删除未完成文件： 

rm -f /Users/jt/Library/Caches/Homebrew/downloads/*.incomplete
brew cleanup

再重新安装： 

brew install node

安装完成后验证： 

node -v
npm -v

我们最终成功识别到的是：

Node.js v24.14.0
npm 11.9.0

重点提醒：不要在前一个 brew 命令没彻底退出时，重复敲新的 brew install。否则锁文件问题会反复出现。

七、第四步：不要随便用 Ctrl+Z 挂起命令

这是我们这次过程中一个非常典型的坑。

在终端里，如果你按了：

Ctrl+Z

这不是“终止”，而是“挂起”。

也就是说，命令没有结束，只是被丢到后台暂停了。
这会导致：

brew 进程还占着锁
curl 任务还挂着
端口和文件仍然可能被占用

真正想中断当前命令，应当用：

Ctrl+C

重点提醒：Ctrl+Z 是挂起，不是结束。这个坑特别容易让后续安装一直报锁文件占用。

八、第五步：安装 OpenClaw 时，不要优先选 git 方式

我们一开始尝试的是： 

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

结果失败了，因为它会执行：

git clone https://github.com/openclaw/openclaw.git

而终端访问 GitHub 443 不稳定，就会报：

Failed to connect to github.com port 443

所以正确做法是：

不要强制指定 git 方式，直接用默认安装方式，也就是 npm 方式。

执行： 

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

或者你也可以直接手工安装： 

npm install -g openclaw@latest

重点提醒：在中国大陆网络环境下，git clone GitHub 仓库往往比 npm 方案更容易失败，所以优先走 npm。

九、第六步：先把 npm 源切到国内镜像

这一步非常重要。
因为即使用 npm 方式安装，如果还是默认国外 registry，也可能下载不稳定。

切换 npm 镜像： 

npm config set registry https://registry.npmmirror.com
npm config get registry

如果输出： 

https://registry.npmmirror.com

说明已切换成功。

为了避免缓存干扰，再清一下缓存： 

npm cache clean --force
rm -rf ~/.npm/_cacache

重点提醒：Homebrew 镜像和 npm 镜像不是一回事。Homebrew 走清华镜像，不代表 npm 自动也走国内。npm 也要单独切。

十、第七步：OpenClaw 安装中出现 SSH GitHub 依赖报错的真正处理办法

这是我们这次安装过程中最核心、最隐蔽的坑之一。

虽然 OpenClaw 本体是通过 npm 安装的，但它的某个依赖会去拉一个 GitHub 仓库，而且走的不是 HTTPS，而是 SSH： 

ssh://git@github.com/whiskeysockets/libsignal-node.git

于是就报：

Permission denied (publickey)
Could not read from remote repository

这说明你的机器没有配 GitHub SSH 公钥。

这个时候，最简单的办法不是去配 SSH Key，而是把 GitHub 的 SSH 地址统一改写成 HTTPS 地址。

执行： 

git config --global url."https://github.com/".insteadOf git@github.com:
git config --global url."https://github.com/".insteadOf ssh://git@github.com/

你可以验证规则是否生效： 

git config --global --get-regexp 'url\..*\.insteadOf'

如果能看到类似下面内容，说明成功： 

url.https://github.com/.insteadof git@github.com:
url.https://github.com/.insteadof ssh://git@github.com/

然后重新执行： 

npm install -g openclaw@latest --verbose

重点提醒：这是本次安装最难发现的坑。表面上是 npm 安装失败，实际上是依赖偷偷走了 GitHub SSH，而你的机器没有 SSH 权限。

十一、第八步：如果 npm 全局安装报权限问题怎么办

如果安装时报类似：

EACCES
permission denied
cannot write to /usr/local/...

那就把 npm 全局安装路径改到用户目录。

执行： 

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
npm install -g openclaw@latest --verbose

然后验证： 

openclaw --version

虽然我们这次日志里最核心的不是权限问题，但这是 macOS 全局安装 npm 包时的高频坑，所以也一并写进来。

十二、第九步：初始化 OpenClaw

安装成功后，初始化： 

openclaw onboard --install-daemon

这个过程中如果出现类似提示：

I understand this is personal-by-default and shared/multi-user use requires lock-down. Continue?

对于个人电脑、个人本机使用场景，应当选：

Yes

因为它的意思是：

默认按个人设备使用方式继续
如果是共享服务器、多用户环境，才需要更严格加固

我们这台机器显然是个人 MacBook Air，所以选 Yes。

重点提醒：这个不是在问你“还装不装”，而是在问你“是否接受按个人使用模式继续配置”。个人电脑就选 Yes。

十三、下一次最推荐你直接照抄的完整安装流程

下面给你一套更接近“从零到安装”的可执行版命令。
下一次你重装时，按这个顺序来。

1. 清理代理环境 

unset http_proxy
unset https_proxy
unset HTTP_PROXY
unset HTTPS_PROXY
unset all_proxy
unset ALL_PROXY
env | grep -i proxy

2. 配置 Homebrew 国内镜像 

echo 'export HOMEBREW_API_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api"' >> ~/.zshrc
echo 'export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"' >> ~/.zshrc
source ~/.zshrc

3. 清理可能残留的 brew 锁 

pkill -f "brew install node"
pkill -f "brew install"
pkill -f brew
rm -f /Users/jt/Library/Caches/Homebrew/downloads/*.incomplete
brew cleanup

4. 安装 Node 

brew install node
node -v
npm -v

5. 配置 npm 国内源 

npm config set registry https://registry.npmmirror.com
npm config get registry
npm cache clean --force
rm -rf ~/.npm/_cacache

6. 将 GitHub SSH 地址改写为 HTTPS 

git config --global url."https://github.com/".insteadOf git@github.com:
git config --global url."https://github.com/".insteadOf ssh://git@github.com/
git config --global --get-regexp 'url\..*\.insteadOf'

7. 安装 OpenClaw 

npm install -g openclaw@latest --verbose

或者： 

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

但就我们的实际排障经验来说，手工执行 npm 安装更便于看清错误信息。

8. 初始化 

openclaw onboard --install-daemon

个人电脑选 Yes。

十四、这次安装过程中最值得记住的几个大坑

坑一：错误代理最致命

如果你设了本地代理端口，但代理没开，终端基本等于半瘫痪。

一定先确认本地代理是否真的在监听端口。

坑二：raw.githubusercontent.com 不稳定，会直接拖垮 Homebrew

所以 Homebrew 国内镜像很重要。

坑三：Ctrl+Z 会让命令挂起，不会结束

这会引发锁文件、进程残留等一系列连锁问题。

坑四：不要在 brew 安装没结束时重复敲命令

锁文件问题会越来越乱。

坑五：OpenClaw 不要优先走 git 安装

中国大陆网络环境下，git clone GitHub 仓库失败率明显更高。

坑六：npm 主包能下，不代表依赖都能下

有些依赖会偷偷走 GitHub SSH，这是最隐蔽的一类问题。

坑七：Permission denied (publickey) 不一定是你不会用 Git

更常见的是依赖默认用了 SSH 地址，而你本机没有配 GitHub 公钥。

十五、最后给你一个最务实的建议

下一次在 macOS 12 上安装 OpenClaw，不要“哪里报错修哪里”，而要按这条主线走：

先清代理
再配镜像
再装 Node
再切 npm 源
再把 GitHub SSH 改成 HTTPS
最后再装 OpenClaw

你只要按这个顺序执行，成功率会比乱试高很多。