Mac 上安装 OpenClaw：一篇搞定（含 zsh / bash 环境变量与避坑）
目标读者：第一次在 macOS 上安装 OpenClaw 的同学
特点：步骤短、坑点全、装完能跑
一、环境准备（Mac）
先确认基础环境：
uname -m
node -v
npm -v
建议：
• 芯片：Apple Silicon（arm64）或 Intel 都可
• Node.js：建议使用较新 LTS（推荐 20+）
• npm：跟随 Node 更新即可
如果没有 Node，推荐用 nvm 安装（方便多版本切换）。
二、安装 OpenClaw
npm install -g openclaw
安装后验证：
openclaw --version
openclaw help
如果看到版本号和帮助信息，说明安装成功。
三、重点：mac 默认 zsh，为什么你配了 bash 却不生效？
很多教程会让你改 ~/.bashrc 或 ~/.bash_profile，但macOS 终端默认 shell 是 zsh，所以你改了 bash 文件，zsh 会“看不见”。
1）先确认当前 shell
echo $SHELL
• 如果输出 /bin/zsh：你应改 ~/.zshrc
• 如果输出 /bin/bash：你应改 ~/.bashrc 或 ~/.bash_profile
2）把 npm 全局 bin 加到 PATH（以 zsh 为例）
npm config get prefix
假设返回 /opt/homebrew 或你自定义目录，把它的 bin 加进 PATH：
写入 ~/.zshrc
export PATH="$(npm config get prefix)/bin:$PATH"
生效：
source ~/.zshrc
再测：
which openclaw
openclaw --version
四、初始化与运行（最小可用）
openclaw status
如果服务未运行，再看网关状态：
openclaw gateway status
openclaw gateway start
常用命令：
openclaw gateway restart
openclaw gateway stop
五、常见问题（高频）
1）zsh: command not found: openclaw
原因：PATH 没配到当前 shell。
排查顺序：
1. npm install -g openclaw 是否成功
2. npm config get prefix 对应 bin 是否在 PATH
3. echo $SHELL 看你到底用 zsh 还是 bash
4. source ~/.zshrc 后重开终端再试
2）全局安装报权限错误（EACCES）
不要乱用 sudo npm -g。推荐两种方案：
• 用 nvm 管理 Node（首选）
• 或配置 npm 全局目录到用户目录，再把该目录 bin 加入 PATH
3）装了但命令版本不对 / 命令冲突
which -a openclaw
看是否有多个路径命中（旧版本残留）。
解决思路：清理旧路径、保证 PATH 顺序正确、重新安装一次。
4）网关起不来 / 状态异常 先看：
openclaw gateway status
openclaw status
再尝试：
openclaw gateway restart
若仍失败，建议记录报错日志（尤其端口占用、权限、网络问题）。
六、我自己的安装建议（省时间版）
-
用 nvm 装 Node（避免权限坑）
-
明确你是 zsh 还是 bash（90% Mac 用户是 zsh）
-
PATH 只改当前 shell 对应配置文件
-
安装后先跑 openclaw --version + openclaw status，不要直接上复杂配置
七、总结 在 Mac 上安装 OpenClaw 本身不难，真正容易卡住的是两件事：
• Shell 搞错（zsh vs bash）****
• PATH 没生效****
把这两点理顺，基本就是 10 分钟可完成安装与启动。
