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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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