最近本地AI Agent框架真的太火了，而OpenClaw绝对是其中的“热门选手”——很多人想安装它，核心就是看中它能在本地运行AI代理，不用依赖云端，不管是开发者用来自动化AI工作流，还是普通用户想实现脚本自动化、文件批量处理、快速生成代码，它都能搞定。

但问题来了，很多人兴致勃勃去装OpenClaw，却频频翻车：要么Node环境不兼容，安装到一半报错；要么Gateway服务启动失败，死活打不开；要么CLI显示安装成功，输入命令却提示“不存在”；最气的是，全程没报错，最后却打不开Web管理界面，白忙活一场。

↓

今天这篇教程，就从零基础开始，一步步教你在macOS上安装OpenClaw，把大家常踩的坑全避开，不管你是新手还是刚接触终端的小白，跟着做，一次就能安装成功，轻松用上本地AI自动化工具！

先跟大家简单说下OpenClaw的优势：它能在本地运行，不用上传数据到云端，隐私性拉满，而且支持CLI命令行和Web界面两种操作方式，自动化脚本、文件处理、代码生成这些需求，都能轻松满足，这也是为什么越来越多人想安装它的原因。

一、安装前准备（重中之重，避开80%的坑）

很多人安装失败，不是步骤错了，而是前期准备没做好。在装OpenClaw之前，一定要先把运行环境准备到位，不然后续肯定报错，大家跟着下面的步骤来，一步都别省。

1. 确认macOS系统版本

OpenClaw对macOS系统有一定要求，老系统容易出现兼容性问题，建议大家确认一下自己的系统版本：

推荐系统：macOS 12 Monterey 及以上版本

支持芯片：Apple Silicon（M1/M2/M3）和Intel芯片都可以，没有限制

这里提醒一句：越新的系统，对Node环境和本地网络权限的支持越好，安装成功率也越高，如果你的系统版本太低，建议先升级系统，再进行后续操作。

2. 安装Node.js环境（核心依赖，必须装）

OpenClaw的CLI工具是基于Node.js运行的，没有Node环境，根本装不了，这是最基础也是最容易出错的一步。

推荐Node版本：Node 18 或 Node 20（亲测这两个版本最稳定，不会出现兼容性问题）

先检查一下你的电脑有没有装Node，打开终端（Launchpad里搜“终端”就能找到），输入下面这行命令，按回车：

node -v

如果终端显示类似“v18.17.0”或“v20.9.0”的版本号，说明已经装了Node，直接跳过安装步骤，确认版本是18或20即可；如果显示“command not found”，说明没装，继续往下走。

最方便的安装方式是用Homebrew（Mac自带的包管理器，没有的话先装Homebrew，网上搜“Mac安装Homebrew”，一步就能搞定），输入命令：

brew install node

安装完成后，再输入下面两个命令，确认安装成功：

node -v
npm -v

只要两个命令都能显示版本号，就说明Node环境装好了。

3. 推荐安装Node版本管理器（避免版本冲突）

这一步不是必须的，但非常推荐！很多人电脑里可能装了多个Node版本，容易和OpenClaw需要的版本冲突，导致安装失败或运行报错。

推荐用这两个版本管理器，二选一即可：nvm 或 nodenv，这里以nvm为例，教大家安装（新手也能轻松操作）：

第一步：安装nvm，终端输入命令：

brew install nvm

第二步：安装Node 20（最稳定版本），输入命令：

nvm install 20

第三步：切换到Node 20版本，输入命令：

nvm use 20

这样一来，后续运行OpenClaw就不会出现Node版本冲突的问题，大大降低报错概率。

二、安装OpenClaw CLI（核心步骤，一键搞定）

环境准备好后，就可以正式安装OpenClaw了，官方提供了一键安装脚本，不用手动操作复杂步骤，新手也能轻松上手。

打开终端，直接复制粘贴下面这行命令，按回车即可（建议直接复制，避免手动输入出错）：

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

执行命令后，系统会自动开始安装，不用管它，等待几分钟就好。这个脚本会自动完成以下操作，不用你手动干预：

• 安装OpenClaw CLI核心工具

• 自动创建用户配置目录

• 初始化Gateway后台服务

• 写入shell自动补全（后续输入命令更方便）

当终端显示“OpenClaw installed successfully”（OpenClaw安装成功），就说明CLI已经装好了，下一步就是验证安装是否成功。

三、验证安装是否成功（必做，避免白忙活）

安装完成后，别着急启动服务，先验证一下CLI是否能正常使用，避免后续启动失败又要回头排查。

终端输入下面这行命令，检查版本号：

openclaw --version

如果终端返回类似“OpenClaw CLI v1.x.x”的版本号，说明安装成功了；如果提示“command not found”，别慌，后面会讲解决方法。

另外，也可以查看OpenClaw的帮助文档，熟悉一下基本命令，输入：

openclaw help

终端会显示所有可用的命令，不用记，后续用到再查就好。

四、启动OpenClaw Gateway服务（后台核心，必须启动）

OpenClaw在Mac上是通过Gateway服务运行后台AI Agent的，CLI装好了只是第一步，必须启动Gateway服务，才能正常使用所有功能。

终端输入启动命令：

openclaw gateway start

这个命令会自动完成3件事，不用手动操作：

• 启动本地API服务（OpenClaw运行的核心）

• 初始化agent runtime（AI代理运行环境）

• 创建macOS后台服务（保证服务能稳定运行）

如果启动成功，终端通常会显示“Gateway started at http://localhost:3333”，说明Gateway服务已经正常启动了，下一步就是访问Web管理界面。

五、访问Web管理界面（可视化操作，新手友好）

OpenClaw默认会启动一个本地Web控制台，不用记复杂的命令，通过浏览器就能操作，非常适合新手。

打开你电脑上的任意浏览器（Safari、Chrome都可以），在地址栏输入下面的地址，按回车：

http://localhost:3333

进入Web控制台后，你就可以轻松操作这些功能了：

• 创建属于自己的AI Agent（根据需求设置自动化任务）

• 执行自动化任务（比如批量处理文件、生成代码）

• 管理workspace（存放任务数据、日志）

• 查看运行日志（遇到问题可以在这里排查）

如果打开页面显示“无法访问”，别慌，先检查Gateway服务是否在运行，输入命令：

openclaw gateway status

如果显示“running”，说明服务在运行，刷新浏览器即可；如果显示“stopped”，重新输入启动命令即可。

六、OpenClaw默认目录结构（了解即可，方便后续维护）

安装完成后，OpenClaw会在你的用户目录下自动创建一个配置目录，了解这些目录的作用，后续遇到问题（比如日志排查、配置修改）会更方便。

主要目录：~/.openclaw（这个目录藏在用户目录下，按“command+shift+.”可以显示隐藏文件）

这个目录里面包含4个核心文件夹，作用给大家整理清楚了，一看就懂：

不用特意去修改这些目录，了解它们的作用，后续维护时能快速找到对应文件就好。

七、将Gateway设置为开机启动（可选，懒人福音）

如果经常用OpenClaw，每次开机都要手动启动Gateway服务，会比较麻烦，建议把它设置为开机自动启动，这样每次登录Mac，Gateway就会自动运行，不用再手动操作。

终端输入下面这行命令，启用开机自启动：

openclaw gateway install

启用成功后，系统会自动创建一个plist文件（自启动配置文件），路径是：~/Library/LaunchAgents/ai.openclaw.gateway.plist

这样一来，每次你登录Mac，Gateway服务就会自动启动，打开浏览器输入http://localhost:3333，就能直接使用OpenClaw了，非常方便。

八、创建第一个Agent（实操演示，快速上手）

安装、启动都完成后，我们来实操一下，创建第一个AI Agent，感受一下OpenClaw的自动化功能，新手也能轻松操作。

方法一：直接运行一个简单任务，终端输入：

openclaw run "summarize this folder"

这个命令会让AI Agent自动总结当前文件夹的内容，执行完成后，终端会显示总结结果。

方法二：进入交互模式，和AI Agent对话，输入：

openclaw chat

进入交互模式后，你可以输入任意任务，比如“Analyze files in workspace”（分析工作空间里的文件），OpenClaw会自动执行对应的流程，完成后给你反馈。

大家可以多尝试几个命令，熟悉一下操作，很快就能上手。

九、常见安装问题（踩坑必看，快速解决）

就算跟着步骤来，也可能会遇到一些小问题，这里整理了4个最常见的报错，给出具体的解决方法，不用再到处查教程，省时又省心。

1. 报错：openclaw 命令不存在

最常见的问题，原因通常是安装完成后，PATH环境变量没有刷新，终端识别不到openclaw命令。

解决方法：终端输入下面这行命令，刷新PATH：

source ~/.zshrc

如果你的终端用的是bash，就输入：source ~/.bashrc，刷新后，再输入openclaw --version，就能识别到了；如果还是不行，重新打开终端即可。

2. 报错：Gateway 无法启动

大概率是默认端口3333被其他程序占用了，导致Gateway启动失败。

解决方法：第一步，检查3333端口是否被占用，输入命令：

lsof -i :3333

如果显示有程序占用，要么关闭占用端口的程序，要么修改OpenClaw的端口，修改方法：打开~/.openclaw/config文件，修改端口号即可。

3. 报错：Node 版本不兼容

如果你的Node版本不是18或20，就可能出现CLI运行报错、Gateway启动失败的问题。

解决方法：如果安装了nvm，输入命令切换到Node 20版本：

nvm use 20

切换完成后，重新启动Gateway服务，就能正常运行了。

4. 报错：macOS 安全权限问题

如果Gateway无法访问电脑里的文件，比如无法分析文件夹、生成文件失败，大概率是终端没有磁盘访问权限。

解决方法：打开Mac的“系统设置” → 找到“隐私与安全” → 点击“完全磁盘访问” → 点击左下角的“+”，添加“终端”，勾选终端的访问权限，重新启动Gateway服务即可。

十、升级 OpenClaw（后续更新，简单操作）

OpenClaw会不断更新新功能、修复bug，后续如果想升级到最新版本，有两种简单方法，二选一即可。

方法一：通过npm升级，终端输入：

npm update -g openclaw

方法二：重新运行官方安装脚本，自动更新到最新版本，输入：

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

两种方法都很简单，升级完成后，输入openclaw --version，就能看到最新的版本号了。

---

总结（重点划重点，记不住就看这里）

其实在macOS上安装OpenClaw，一点都不复杂，核心就是5个步骤，抓好这5步，就能一次安装成功，避开所有坑：

1. 准备环境：安装Node 18/20，推荐装nvm避免版本冲突；

2. 安装CLI：运行官方一键安装脚本，等待安装成功；

3. 启动服务：输入命令启动Gateway后台服务；

4. 访问Web：浏览器打开http://localhost:3333，进入控制台；

5. 实操上手：创建第一个AI Agent，体验自动化功能。

只要跟着上面的步骤来，不管你是新手还是小白，都能轻松在Mac上安装并使用OpenClaw，再也不用为安装报错、启动失败而烦恼。

如果操作过程中遇到其他问题，评论区留言，我会及时回复大家，帮大家顺利搞定安装！