Mac 安装 OpenClaw 的详细步骤

一、先确认安装方式

OpenClaw 官方当前最推荐的方式，是直接运行安装脚本。这个脚本会自动识别系统、自动处理 Node 依赖，并启动 onboarding。官方要求 Node 24 推荐，或 Node 22.14+ 也可；安装完成后可以用 openclaw --version、openclaw doctor、openclaw gateway status 做检查。

二、Mac 上最简单的安装步骤

1）打开终端

Mac 上打开：

• Launchpad → Terminal

• 或 Spotlight 搜索 Terminal

2）执行官方安装命令

直接运行：

curl -fsSL https://openclaw.ai/install.sh | bash

这是官方推荐命令。它会自动安装所需环境，并启动 OpenClaw 的引导配置。

3）如果你只想安装，不想立刻进入引导

可以用：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

这个会安装 OpenClaw，但不立即跑 onboarding。

⸻

三、如果你已经自己装好了 Node

bash 复制代码

你也可以手动安装 OpenClaw CLI：

npm install -g openclaw@latest
openclaw onboard --install-daemon

如果你用的是 pnpm，则官方给出的方式是：

pnpm add -g openclaw@latest
pnpm approve-builds -g
openclaw onboard --install-daemon

其中 pnpm 需要额外执行 pnpm approve-builds -g。

⸻

四、安装完成后怎么验证

bash 复制代码

安装后建议依次执行：

openclaw --version
openclaw doctor
openclaw gateway status

含义分别是：
	•	openclaw --version：确认 CLI 已经装好
	•	openclaw doctor：检查配置问题
	•	openclaw gateway status：检查 Gateway 是否正常运行  

如果 Gateway 已经正常启动，你还可以打开本地控制面板：

openclaw dashboard

默认本地地址是：

http://127.0.0.1:18789/

官方文档把这个作为本地 Dashboard 默认入口。

⸻

五、第一次配置时你需要准备什么

官方文档说明，除了 Node 版本以外，你通常还需要准备一个你要接入的模型提供方 API Key，然后通过 onboarding 去完成配置。OpenClaw 的 Gateway 是核心进程，后续聊天通道、控制台、macOS app 都围绕它工作。

通常你会在 onboarding 里配置：

• 模型提供商

• API Key

• 默认 agent

• 本地/远程控制方式

• 聊天通道接入方式（如 Telegram、Discord 等）

⸻

六、Mac 上常见问题

bash 复制代码

1）openclaw: command not found

官方文档给出的排查方式是：

node -v
npm prefix -g
echo "$PATH"

如果全局 npm 的 bin 目录没进 PATH，就把它加到 ~/.zshrc 或 ~/.bashrc：

export PATH="$(npm prefix -g)/bin:$PATH"

保存后重新开一个终端窗口。 

2）npm 安装时报 sharp 相关错误

官方文档给了一个处理方式：

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

这通常用于 sharp 因全局 libvips 冲突导致的安装失败。 

3）不要用 root 用户安装

GitHub 上近期 issue 提到，macOS 上用 root 安装可能引发问题，重新换普通用户安装会更稳。这个不是主文档里的硬性要求，但算是比较新的踩坑反馈。

⸻

七、如果你还想装 macOS 桌面 App

OpenClaw 现在还有 macOS companion app。官方开发文档说明，这个 App 依赖全局安装的 openclaw CLI 来管理后台任务；在 App 里也可以到 General 设置页点击 Install CLI。

如果你是开发者，要从源码构建 macOS app，官方步骤是：

安装 Xcode 26.2+
安装 Node 24 和 pnpm
pnpm install
./scripts/package-mac-app.sh 打包
再安装全局 CLI。

另外有两个近期社区反馈你要留意：

• 有 issue 提到桌面 App 目前看起来偏向 Apple Silicon 支持，Intel Mac 兼容性存在用户反馈。

• 还有 issue 提到某些桌面版本要求 macOS 15+。这更像版本现状，不是安装 CLI 的硬限制，但如果你装桌面 App 启不来，要先检查系统版本。

⸻

八、我建议你在 Mac 上这样装

最稳妥的顺序是：

bash 复制代码

# 1. 直接官方脚本安装
curl -fsSL https://openclaw.ai/install.sh | bash

# 2. 检查版本
openclaw --version

# 3. 自检
openclaw doctor

# 4. 看 Gateway 状态
openclaw gateway status

# 5. 打开控制台
openclaw dashboard

这样最省事，也最接近官方推荐流程。