Install guide

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

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

开始安装查看官方来源

快速提示

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

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

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

你将获得

内容风格

少废话，先给结果

先告诉你该做什么、会遇到什么，再给出最短可用路径。

阅读体验

能看懂，也能照着做

重点信息会被拆成清单、步骤和提示，减少第一次上手的理解成本。

页面重点

先把关键问题讲清楚

实用优先

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