Install guide

macOS 安装 OpenClaw：官方推荐路径完整教程

这篇教程面向 macOS 新手，严格按官方推荐链路组织：先确认 Node 运行时，再安装 CLI，接着用 onboard 安装 daemon，最后通过 Dashboard、gateway status 和 doctor 完成验收。

开始安装查看官方来源

Implementation notes

官方当前推荐 Node 24；如果你在用 Node 22，也要至少达到 22.16+。

第一次安装不建议并行折腾多套包管理器与多个 shell 配置文件。

macOS 上更重要的不是命令多少，而是 PATH、全局 npm 和 daemon 是否真正就绪。

Signal board

Runtime

Static export

Optimized for predictable Cloudflare Pages deploys.

Content model

Shared data layer

One set of structures will power homepage, lists, and showcase proof.

Editorial tone

Safer, quieter, sharper

Trust-led

Article brief

这篇文章适合谁，以及今天先解决什么

想在 macOS 上快速、稳定完成 OpenClaw 首次部署的用户。

预计耗时

15 到 30 分钟

验证日期

2026-03-13

Image plan

图文并茂版本建议至少补这 4 张图

图 1：Terminal 中 `node -v`、`npm -v` 输出。

图 2：`npm install -g openclaw@latest` 安装成功。

图 3：`openclaw onboard --install-daemon` 进入 onboarding。

图 4：Dashboard 页面与 `openclaw doctor` 输出。

Before you start

安装前准备

先把环境、网络和运行时准备好，再敲第一条安装命令。

准备 1

macOS 终端可正常工作，能执行基础 shell 命令。

准备 2

如果你用 Homebrew，确认 `brew doctor` 没有明显阻断问题。

准备 3

准备好后续模型接入方式，但本篇先聚焦安装与首轮验证。

Hard stops

这篇教程里的停手点

以下情况先停下来排错，不要继续堆命令。

停手点 1

不要在 PATH 没确认之前反复卸载重装 CLI。

停手点 2

不要因为第一次启动慢就重复执行 daemon 安装命令。

停手点 3

如果你用了多个 shell（zsh、bash、fish），只先保证你常用的那个可用。

Step by step

按官方顺序安装，别把第一天的目标搞成“大而全”。

每一步都带目的说明和可直接复制的命令。先让安装成功率稳定，再谈配置、Skills 和复杂工作流。

Step 1

步骤 1：确认 Node.js 与 npm 全局目录都正常

macOS 上安装失败的常见原因不是 OpenClaw 本身，而是 Node 版本和 PATH 没理顺。先把基础运行时确认好。

如果你还没装 Node，最省事的方式是 Homebrew。

先看 `node -v`、`npm -v` 和 `npm config get prefix`。

如果全局安装目录不在 PATH 中，先修 PATH，再继续装 CLI。

Copy-ready command

复制下面这组命令

建议整段复制；如果你要分步执行，先看每一步预期输出。

brew install node
node -v
npm -v
npm config get prefix

Step 2

步骤 2：安装 OpenClaw CLI，并验证命令是否可用

CLI 能否直接调用，是后续 onboard、dashboard 和 doctor 能否顺畅执行的前提。

优先用 npm 全局安装。

安装后立刻跑 `openclaw --help`，确认 shell 已经能找到它。

如果找不到命令，不要跳过；先修 PATH。

Copy-ready command

复制下面这组命令

建议整段复制；如果你要分步执行，先看每一步预期输出。

npm install -g openclaw@latest
openclaw --help

Step 3

步骤 3：执行 onboard，完成 daemon 安装和首轮引导

官方 Getting Started 把 onboard 作为第一轮安装与引导入口。先让它把 daemon 装好，再打开 Dashboard。

第一次安装以默认安全路径为主，不要急着加高权限配置。

如果系统弹出权限提示，按提示完成，不要跳过。

完成后立即打开 Dashboard，确认你已经进入官方 onboarding 流程。

Copy-ready command

复制下面这组命令

建议整段复制；如果你要分步执行，先看每一步预期输出。

openclaw onboard --install-daemon
openclaw dashboard

Step 4

步骤 4：用状态命令做验收，确认可以进入首次配置

只有在 daemon 状态和 doctor 健康检查都通过后，才值得继续写模型配置或装第三方能力。

先看 gateway 在线状态。

再跑 doctor，必要时追加外部服务验证。

如果这里失败，先修健康检查，不要继续叠功能。

Copy-ready command

复制下面这组命令

建议整段复制；如果你要分步执行，先看每一步预期输出。

openclaw gateway status
openclaw doctor
openclaw doctor --verify-external-services

Verification

完成安装后，至少核对这 5 项

只有这些检查都通过，才算真的完成了第一次系统安装。

检查 1

`node -v` 输出推荐版本。

检查 2

`npm config get prefix` 对应目录在 PATH 中。

检查 3

CLI 全局安装完成且 `openclaw --help` 可运行。

检查 4

`openclaw gateway status` 返回运行中。

检查 5

`openclaw doctor` 没有阻断项。

Copy-ready command

安装完成后的统一验收命令

这组命令适合放在文末，方便用户复制做最终确认。

openclaw dashboard
openclaw gateway status
openclaw doctor

Official sources

本文只优先采信 OpenClaw 官方文档可交叉验证的信息。

涉及脚本安装、Node 版本、onboard、Dashboard、gateway 状态与健康检查的内容，都以官方文档为第一来源。

官方文档 · Installer Scripts

用于核对 `install.sh`、`install-cli.sh`、`install.ps1` 的官方安装方式与推荐场景。

https://docs.openclaw.ai/zh-CN/install/installer

官方文档 · Node.js 安装与排错

用于核对 Node.js 22.16+ / 24、PATH 与全局安装排错建议。

https://docs.openclaw.ai/zh-CN/install/node

官方文档 · Getting Started

用于核对 `openclaw onboard --install-daemon`、Dashboard、gateway 状态与最短验证链路。

https://docs.openclaw.ai/zh-CN/start/getting-started

官方文档 · Doctor & Health Check

用于核对 `openclaw doctor` 与外部服务检查方式。

https://docs.openclaw.ai/zh-CN/config/doctor-and-health-check