OpenClaw 在 macOS 上的完整搭建流程（超详细实战版）

这是一篇纯 OpenClaw 搭建指南，不包含与 RF/自动化框架联动内容。
目标：从 0 到可用，完成安装、启动、浏览器接管与高频问题排查。

---

一、搭建完成后的验收标准

完成本文步骤后，你应该能做到：

• 执行 openclaw --version 返回版本号
• 执行 openclaw gateway start 可成功启动服务
• 执行 openclaw gateway status 能看到运行状态
• Chrome Relay 成功连接到你指定的网页标签页
• 在会话中可调用页面截图和 DOM 采样能力

如果以上 5 条都满足，说明你的 OpenClaw 环境已经可稳定使用。

---

二、安装前环境准备

1）系统和工具要求

• macOS（Intel / Apple Silicon 都可以）
• Node.js（建议 LTS，推荐 20+ 或 22+）
• npm
• Google Chrome（用于页面接管）

2）先做环境核对

在终端依次执行：

• sw_vers
• node -v
• npm -v
• which node
• which npm

说明：

• which 命令可以帮助你确认 node/npm 实际来自哪个路径。
• 如果路径混乱（比如同时存在 brew 和 nvm 版本），后续很容易出现莫名其妙的报错。

3）推荐使用 nvm 统一管理 Node

步骤如下：

1. brew install nvm
2. mkdir -p ~/.nvm
3. 在 ~/.zshrc 追加以下内容：
   export NVM_DIR=“$HOME/.nvm"[-s"$(brew --prefix nvm)/nvm.sh” ] && . “$(brew --prefix nvm)/nvm.sh”
4. 执行 source ~/.zshrc
5. 执行 nvm install --lts
6. 执行 nvm use --lts
7. 再次确认 node -v 和 npm -v

这样做的好处是：后续升级 Node、切换版本、排查兼容性都更容易。

---

三、安装 OpenClaw

安装命令：

• npm install -g openclaw

安装完成后立刻验证：

• openclaw --version
• openclaw help

常见问题：command not found: openclaw

这通常不是安装失败，而是 PATH 没生效。

排查顺序：

1. 执行 npm bin -g，拿到全局可执行目录
2. 把该目录加入 ~/.zshrc 的 PATH
3. 执行 source ~/.zshrc
4. 再次执行 openclaw --version

---

四、网关服务管理（最关键）

OpenClaw 的 gateway 是运行核心。下面这些命令要熟练掌握：

• openclaw gateway status 查看网关状态
• openclaw gateway start 启动网关
• openclaw gateway restart 重启网关
• openclaw gateway stop 停止网关
• openclaw status 查看整体运行状态

建议习惯：

• 出问题先看 status，再决定是否 restart
• 每次改动配置后，做一次 restart 再验证

---

五、首次启动后的完整验证流程

验证 A：命令链路

• openclaw --version
• openclaw help

验证 B：服务健康度

• openclaw gateway status
• openclaw status

验证 C：功能可用性

• 进入 OpenClaw 会话发一条普通消息，确认回复正常
• 执行一次浏览器截图，确认工具链正常

完成 ABC 三步，基本可以确认环境搭建成功。

---

六、Chrome Relay 接入（网页能力必做）

1）安装并启用扩展

在 Chrome 中安装 OpenClaw Browser Relay，并确认扩展已启用。

2）连接目标标签页

• 打开你要操作的网页
• 在该 tab 点击扩展图标
• 确认状态为 ON/已连接

3）典型报错说明

如果看到提示：Chrome extension relay is running, but no tab is connected
表示：网关正常，但没有附着具体 tab。
处理：回到目标 tab，再点一次扩展图标连接即可。

---

七、高频问题排查（按优先级）

问题 1：openclaw 命令不可用

处理步骤：

1. npm bin -g
2. 检查 PATH 是否包含该目录
3. source ~/.zshrc
4. 重新验证 openclaw --version

问题 2：gateway 无法启动

处理步骤：

1. openclaw gateway status
2. openclaw gateway restart
3. openclaw status
4. 检查 Node 版本是否满足要求

问题 3：浏览器无法接管

处理步骤：

1. 扩展是否启用
2. 是否在“目标 tab”点击连接
3. 页面刷新后重连
4. 避免在浏览器内部页面测试（例如 chrome:// 页面）

问题 4：偶发可用、偶发不可用

根因通常是多 Node 环境冲突。
建议统一使用 nvm，清理重复 PATH 配置后重开终端。

---

八、升级与日常维护建议

升级命令：

• npm update -g openclaw
• openclaw --version

维护建议：

• 每周检查一次版本
• macOS 大版本升级后，重新跑一遍验证流程
• 把自己的常见报错和解决步骤记成清单，后续节省大量时间

---

九、推荐的排错闭环（实战有效）

出现任何异常时，按这个顺序走：

1. node -v / npm -v
2. openclaw --version
3. openclaw gateway status
4. openclaw gateway restart
5. openclaw status
6. 重新连接 Chrome Relay
7. 测试一次页面截图

第 7 步成功，说明整体功能链路基本恢复。

---

十、总结

OpenClaw 在 macOS 的搭建重点，不在“安装命令本身”，而在：

• Node 环境一致性
• Gateway 状态管理
• Relay 连接习惯

把这三件事固定下来后，你的使用体验会非常稳定，后续扩展功能也会轻松很多。

---

附录：命令速查（仅搭建相关）

• node -v
• npm -v
• npm install -g openclaw
• openclaw --version
• openclaw help
• openclaw gateway status
• openclaw gateway start
• openclaw gateway restart
• openclaw gateway stop
• openclaw status