OpenClaw 安装教程(mac 优先)

OpenClaw 安装教程（mac 优先）：一份实操参考（含网络排查）

这篇文章整理了一套相对稳妥的安装路径。

它不保证适用于所有环境，但希望在常见场景下，给你一个清晰的起点和排查方向。

一、写在前面

不同人的设备环境差异很大：系统版本、网络条件、终端习惯、权限策略都可能影响安装过程。

如果中途遇到问题，不必着急，先按步骤排查，通常都能逐步定位原因。

二、为什么建议优先使用 mac

这里说“优先”，不是“唯一”。

从实践经验看，mac 在终端工具链和环境一致性方面通常更稳定一些，排查路径也相对清晰。

三、安装前准备

1）确认终端可用

- mac：Terminal

- Windows：PowerShell（可考虑 WSL2）

- Linux：Shell

2）确认 Node 与 npm 可用

在终端执行：

node -v

npm -v

若无版本输出，先安装 Node.js（建议 LTS）。

3）确认网络条件

如果依赖下载不稳定，安装过程可能反复中断。

建议先准备可用网络环境，再进入安装流程（必要时考虑科学上网）。

四、mac 安装路径（推荐）

第一步：安装 OpenClaw

npm install -g openclaw@latest

第二步：验证安装

openclaw --version

openclaw status

第三步：完成基础配置

openclaw configure

第四步：检查网关状态

openclaw gateway status

如状态异常，可尝试：

openclaw gateway restart

openclaw status

五、Windows / Linux 参考路径

Windows（补充建议）

如果本机环境较复杂，可考虑先在 WSL2 环境中安装：

npm install -g openclaw@latest

openclaw --version

openclaw status

Linux（Ubuntu / Debian 示例）

sudo apt update

sudo apt install -y nodejs npm

npm install -g openclaw@latest

openclaw --version

openclaw status

六、补充路径：在 Windows 通过 Ubuntu 虚拟机安装 OpenClaw

有些朋友会选择在 Windows 中使用 Ubuntu 虚拟机来运行 OpenClaw。

这种方式的优势是环境更统一，很多 Linux 命令与排查方式也更直观。

1）准备 Ubuntu 虚拟机（VMware / VirtualBox 等）

安装系统后先执行：

sudo apt update

sudo apt upgrade -y

2）安装 Node.js 与 npm

sudo apt install -y nodejs npm

node -v

npm -v

3）安装 OpenClaw

npm install -g openclaw@latest

4）验证与初始化

openclaw --version

openclaw configure

openclaw status

openclaw gateway status

5）常见注意点（虚拟机场景）

- 优先保证虚拟机网络稳定（NAT/桥接按环境选择）

- 如网关启动异常，先看 openclaw gateway status

- 宿主机休眠后，虚拟机网络可能需要重连

七、网络相关问题（较常见）

情况 A：可访问但速度不稳定

可先重试安装命令；若反复失败，建议更换更稳定网络后继续。

情况 B：持续超时或依赖下载失败

通常与网络访问能力有关。

与其反复重试，不如先处理网络条件，再继续安装。

情况 C：受限网络环境（公司/校园）

可以先在可用网络里完成安装与初始化，再回到目标环境做后续使用。

八、常见报错与排查方向

1）openclaw: command not found

可能是 PATH 或 npm 全局路径未生效，建议重开终端并检查环境变量。

2）安装后运行异常

可能与 Node 版本或本地环境冲突有关，可先切换到 Node LTS 再重装。

3）gateway 启动异常

建议先看状态再处理：

openclaw gateway status

openclaw gateway restart

4）Browser Relay 连接不上

优先检查：

- Port（常见 18792）

- token 是否正确

- 是否显示 Connected to tab

九、阶段性完成标准（可参考）

如果你已经做到以下几点，说明安装阶段已有进展：

1）openclaw --version 能正常返回

2）openclaw status 能输出有效状态

3）openclaw gateway status 能看到网关运行信息

这不代表所有功能都已完全就绪，但可以进入下一步使用与优化。

十、结语

安装过程本身也是环境磨合的一部分。

不追求一步到位，按顺序完成检查和排查，通常更容易稳定下来。

如果这篇内容能帮你减少一点试错成本，它就有价值。

下一篇将继续整理：OpenClaw 的基础使用路径（从“能运行”到“能实际使用”）。