需先安装node.js v22.x lts、git和homebrew，再执行官方安装脚本或手动npm全局安装，最后确保path包含node@22/bin并刷新shell配置。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您尝试在 macOS 上安装 OpenClaw AI，但终端无法识别 openclaw 命令或启动失败，则可能是由于系统缺少必要运行时依赖、Node.js 版本不兼容或环境变量未正确加载。以下是解决此问题的步骤：
一、验证并安装基础运行时依赖
OpenClaw 并非传统意义的“驱动”，而是基于 Node.js 的命令行智能体框架，其正常运行依赖于特定版本的 Node.js、Git 和包管理器。缺失任一组件均会导致命令不可用或初始化失败。
1、打开「终端」（应用程序 → 实用工具 → 终端）
2、依次执行以下命令检查当前环境：
3、运行 sw_vers -productVersion 确认系统版本 ≥ macOS 12（Monterey）
4、运行 git --version 检查 Git 是否已安装；若提示 command not found，则执行 xcode-select --install 安装命令行工具
5、运行 brew --version 验证 Homebrew；若未安装，粘贴运行：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
二、安装并锁定 Node.js v22.x LTS 版本
OpenClaw 明确要求 Node.js ≥ v22.0.0，且实测 v24.x 及更高版本存在兼容性问题，会导致 openclaw 命令解析失败或 gateway 启动崩溃。
1、卸载可能存在的高版本 Node.js：
brew uninstall node node@24
2、安装官方推荐的 v22 LTS：
brew install node@22
3、将 v22 的 bin 路径写入 shell 配置文件：
echo 'export PATH="/usr/local/opt/node@22/bin:$PATH"' >> ~/.zshrc
4、立即生效配置：
source ~/.zshrc
5、验证安装结果：
node -v 应输出类似 v22.14.2
npm -v 应输出 ≥ 9.9.0
三、执行官方一键安装脚本
该脚本会自动检测已安装组件、跳过重复项，并完成全局 npm 包安装、权限配置与 PATH 注册，是 macOS 下最稳定可靠的部署方式。
1、在终端中粘贴并执行完整命令：
curl -fsSL https://openclaw.ai/install.sh | bash
2、等待脚本自动完成以下动作：
✅ 检测 Homebrew / Node.js / Git 状态
✅ 安装或跳过对应依赖
✅ 执行 npm install -g openclaw@latest
✅ 创建 ~/.openclaw/ 配置目录
✅ 运行首次引导 openclaw onboard
3、如脚本中途报错（如 network timeout 或 signature verification failed），请确认网络可访问 GitHub 与 openclaw.ai 域名；必要时可切换至国内镜像源重试
四、修复命令未找到（command not found）问题
即使脚本显示“Installation successful”，仍可能出现终端输入 openclaw --version 提示 command not found，这通常由 shell 配置未刷新或 PATH 写入路径错误导致。
1、检查当前 shell 类型：
echo $SHELL —— 多数 macOS 为 /bin/zsh
2、确认 PATH 中是否包含 Node.js v22 的 bin 目录：
echo $PATH | grep node@22 —— 若无输出，说明写入失败
3、手动补全 PATH（适用于 zsh）：
echo 'export PATH="/usr/local/opt/node@22/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
4、重启终端应用后再次运行：
openclaw --version
五、手动安装（当一键脚本不可用时）
若因网络策略、企业防火墙或 MDM 管控导致 curl 脚本无法执行，可采用纯本地 npm 安装方式，绕过远程脚本依赖。
1、确保已完成步骤二中 Node.js v22 安装与 PATH 配置
2、运行以下命令之一（根据实际可用包管理器选择）：
npm install -g openclaw@latest
或
pnpm add -g openclaw@latest
或
yarn global add openclaw@latest
3、强制重建 shell 命令索引：
hash -d openclaw || true
rehash
4、验证命令可用性：
which openclaw 应返回路径如 /usr/local/bin/openclaw
openclaw --version
