OpenClaw macOS 环境搭建与安装指南

解决方案：

1. 检查网络连接
2. 或等待网络恢复后重试

⚠️ 常见错误 3：安装过程卡住

如果出现 Press RETURN/ENTER to continue or any other key to abort:，按 回车键 继续安装。

2.2 手动配置 PATH

安装完成后，需要将 Homebrew 添加到系统 PATH，并且终端已经给我们提示了如下图所示：

在终端执行以下命令：

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile eval "$( /opt/homebrew/bin/brew shellenv)"

2.3 验证安装结果

验证：在终端输入 brew --version，

brew --version 

看到版本号 Homebrew 5.0.16 即表示成功，如下图所示：

三、安装 Node.js（环境核心）

Node.js 是运行 OpenClaw 的引擎。版本低于 22 将直接导致程序崩溃或无法编译。

3.1 检查当前环境

首先确认你的 Mac 是否已经安装了 Node.js 以及具体的版本号：

node -v 

• 版本 ＞ 22：恭喜你，可以直接跳到第四步。
• 版本 < 22 或显示 command not found：请继续执行以下步骤进行安装或升级。

3.2 方案一：使用 Homebrew 快速安装（推荐）

如果你希望简单快捷，直接使用 brew 安装最新稳定版：

# 安装最新版 Node.js 
brew install node 

如下图所示：

❝

💡 注意：

执行完 brew install node 后，如果 node -v 依然显示旧版本，通常是因为旧版本的路径优先级更高。你可以尝试运行 brew link --overwrite node 来强制刷新软链接。

3.3 验证安装结果

安装完成后，务必再次确认版本：

node -v # 预期输出类似：v22.x.x 或 v23.x.x 

同时检查 Node 的包管理器 npm 是否正常：

npm -v 

输入两次命令后，正确安装如下图所示：

⚠️ 注意事项：

• M 系列芯片原生支持：通过 brew 安装的 Node.js 是原生支持 Apple Silicon 的，性能极佳。
• 编译权限：如果在安装过程中遇到 Permission denied 报错，请检查是否在命令前误加了 sudo（通常 brew 不需要 sudo，npm 全局安装时可能需要）。

四、安装 Git（代码克隆工具）

4.1 执行安装命令

在终端中输入以下指令并回车：

brew install git 

4.2 验证安装是否成功

安装完成后，输入以下命令检查 Git 是否已就绪：

git --version 

预期输出：

如果你看到类似 git version 2.4x.x 的字样，说明 Git 已经成功入驻你的 Mac。

⚠️ 常见问题排查

• 下载速度极慢：Git 的安装包托管在 GitHub 上，如果进度条长时间不动，请确保你的网络已通畅。
• 报错 "xcrun: error"：这通常是因为 Xcode 路径损坏。尝试运行 xcode-select --install 重新修复开发工具环境。

五、安装 OpenClaw

在准备好 Git 和 Node.js 22+ 之后，我们终于可以开始正式获取 OpenClaw 的源代码了。这一步不仅是将代码'下载'下来，更是建立本地运行环境的起点。

5.1 克隆项目：将代码下载至本地

'克隆'（Clone）是 Git 的术语，意为在你的电脑上创建一个远程仓库的完整拷贝。输入以下命令从 GitHub 拉取代码：

git clone https://github.com/openclaw/openclaw.git 

• 命令解析：git clone 是下载指令，后面的 URL 是 OpenClaw 的官方仓库地址。
• 成功标志：终端显示 Receiving objects: 100% ... done. 且没有报错。

进入项目目录

下载完成后，你需要'走进'这个文件夹才能进行后续操作：

cd openclaw 

❝

💡 小贴士：

这一步非常重要！如果你不执行 cd openclaw，后续的 npm install 命令会因为找不到配置文件而报错。

5.2 安装依赖包

在 openclaw 目录下执行：

npm install

5.3 全局安装 OpenClaw

这一步会将 openclaw 注册为系统命令，方便你在任何地方调用，我们在终端输入如下命令：

npm install -g .

5.4 初始化与运行

运行设置向导

openclaw setup 

系统会自动初始化配置文件并确认工作区状态。

输出：

🦞 OpenClaw 2026.3.2 (132794f) — Automation with claws: minimal fuss, maximal pinch. Wrote ~/.openclaw/openclaw.json Workspace OK: ~/.openclaw/workspace Sessions OK: ~/.openclaw/agents/main/sessions 

启动网关 (Gateway)，继续在终端输入下面的命令：

openclaw gateway 

输出：

🦞 OpenClaw 2026.3.2 (132794f) — Your messages, your servers, your control. 

重要：如果是第一次启动，UI 构建需要几分钟时间。如果此时访问网页提示 ERR_CONNECTION_REFUSED，请稍等片刻再重新运行。

安装成功后显示：

⚠️ 常见错误 ：command not found

zsh: command not found: openclaw 

解决方案：执行 npm install -g . 即可解决。

5.5 打开控制面板 (Dashboard)

保持网关窗口开启，新开一个终端窗口输入：

openclaw dashboard 

浏览器会自动打开 http://127.0.0.1:18789。

到这里我已经成功安装了 openclaw。但这个 openclaw 还是没有思想的，我们需要给 openclaw 配置大模型。

5.6 给 OpenClaw 大模型 (终端版)

除了在 Web UI 界面配置外，你也可以直接在终端完成配置。我们就以在终端为例。

我们在终端输入命令

openclaw agents add main

在图片所示的界面中，系统提示 Agent "main" already exists. Update it?：，使用键盘方向键选择 Yes 并回车。

接下来我们继续点击回车键，选择该工作目录。

使用键盘方向键选择 Yes 并回车，来配置模型。

接下来的终端界面会列出多个模型提供商。

我这里使用的是 MiniMax 这个大模型，使用方向键找到 MiniMax。按下回车键确认选择带（cn）。大家可以选择其他的模型。

接下是需要黏贴 API key，如下图所示：

5.7 输入 API Key 与配置

系统会依次弹出输入提示，输入你在 MiniMax 开放平台申请的 API Key。

接下来我们不选择配置聊天工具，选择 no，

5.8 验证配置

配置完成后，重新运行网关以激活配置：

openclaw gateway

打开浏览器进入 Dashboard (http://127.0.0.1:18789)，我们在对话框中问他是哪个模型？

我们看到图中回复我是 minimax2.5 模型，说明配置已成功生效。

这样我们就配置好了 OpenClaw 小龙虾。