很多想折腾 OpenClaw 的朋友十有八九在第一步就被卡住了。OpenClaw 是腾讯开源的那个 Agent 智能体框架类似 Manus 的开源替代品本地部署好之后相当于给了你一个能真干活儿的 AI 助理查资料、写代码、操作文件、调用各种工具都可以试着让它来。麻烦的是它的安装文档面向的是全球用户直接照搬到国内 macOS 上来跑要么 npm 拉包慢到怀疑人生要么装完了不知道去哪配模型 Key要么在 Intel 和 Apple Silicon 芯片的 Mac 上跑出完全不一样的结果。我这篇就把 国内 苹果系统 OpenClaw 这个组合从头到尾写透覆盖两种安装方式、模型接入、启动验证、日常升级卸载以及我实际踩过的坑。适合想在 Mac 上部署 OpenClaw 的开发者也适合不熟 Node.js 但想本地跑一个 Agent 试试手的朋友。1. 出发之前先把 OpenClaw 和 macOS 环境这两件事捋清楚在真正敲命令之前我建议花三分钟搞清楚 OpenClaw 到底是什么、依赖什么、macOS 相比 Linux 到底特殊在哪。很多人装到一半失败根源就是没搞明白它这套运行逻辑遇到报错只能瞎试。1.1 OpenClaw 到底是个什么东西OpenClaw 本质上是一个本地运行的个人 AI 智能体跑腿框架。它不是一个简单的聊天机器人而是把大模型当大脑再给它接上工具集——比如读写文件、执行 Shell 命令、调用 HTTP 接口、操作浏览器——让它能根据你的指令拆解任务、规划步骤、逐步执行最后把结果反馈给你。类比一下你就懂了ChatGPT 这类产品像是你雇了一个只动嘴的顾问OpenClaw 则更像你雇了一个能动手的实习生。这个实习生平时住你电脑里你给它配好模型大脑它就能按你的要求去执行具体任务。它基于 Node.js 生态开发所以核心依赖就是 Node、npm或者 pnpm这两个东西。安装的本质说白了就是把 OpenClaw 的源码和依赖包拉到你电脑上然后用 Node 去跑起来。理解了这一点后面所有步骤都是在跟包管理和运行环境打交道思路就会清晰很多。1.2 为什么 macOS 上装它比 Linux 多出几个步骤macOS 确实比 Windows 更接近 Linux因为它本身是 Unix 内核终端环境、文件权限、Shell 命令都比较友好。但你别以为这样就万事大吉了它有几个坑是 Linux 上没有的。第一macOS 不自带包管理器。Linux 发行版基本都有 apt 或 yummacOS 你得先装 Homebrew不然连 Node.js 都不好装虽然你也可以去官网下 pkg 安装包但后续升级管理远不如 Homebrew 方便。第二芯片架构不同软件兼容性有差异。Intel 芯片是老 x86_64 架构Apple SiliconM1/M2/M3/M4是 arm64 架构。虽然 Node.js 两种架构都有官方支持但依赖原生模块编译时偶尔会出现二进制不匹配或者编译器环境问题。第三macOS 的 Gatekeeper 和权限机制比较严格。从网上下载的工具、编译产物、未签名脚本系统可能会拦截。第一次运行某些命令时可能还会弹权限授权窗口这些都是 Linux 上不会遇到的。把这些前置认知准备好再往下走你就知道每一步到底是在干什么了而不是复制粘贴命令完事。2. 安装前准备10 分钟搞定基础环境在 macOS 上装 OpenClaw 之前必须把基础环境搭好。这一步相当于盖房子打地基地基不稳后面盖再漂亮都是白搭。2.1 先确认你的 Mac 是什么芯片、什么系统版本老规矩先确认硬件信息。点击屏幕左上角苹果图标选关于本机就能看到两个关键信息一个是芯片型号比如Apple M3 Pro或者Intel Core i7另一个是 macOS 版本号比如 13.6 或 14.5。为什么要先看这两个第一芯片架构决定了你装 Homebrew 时目录会出现在哪后面配置 PATH 环境变量时会用到。Apple Silicon 的 MacHomebrew 默认装在/opt/homebrewIntel 芯片的 Mac默认装在/usr/local。这个差异很关键配置错了命令会提示找不到。第二OpenClaw 基于 Node.js 生态较老的 macOS 版本可能无法运行新版本的 Node.js。比如 macOS 10.15Catalina对最新 Node 20/22 的支持就很吃力。我的建议是至少在 macOS 12 以上再折腾如果你是 Intel 老机器且系统止步在老版本安装 Node 时选 18 系列会更稳。2.2 装 HomebrewmacOS 上最好用的包管理器如果你已经装过 Homebrew 而且平时在用它直接跳过这一步。没装过的打开终端Terminal粘贴这一行/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)这会从 GitHub 拉取 Homebrew 的安装脚本并执行。国内网络环境下这一步确实有可能很慢如果卡住可以把下载源替换为国内镜像站比如中科大或者清华的 Homebrew 镜像。具体做法很简单把上面的地址里的raw.githubusercontent.com换成对应镜像地址然后重新执行。安装完成后注意终端输出末尾的提示如果它告诉你需要把 Homebrew 加到 PATH 里就照着它给的两行命令执行。Apple Silicon 芯片的机器通常需要执行echo eval $(/opt/homebrew/bin/brew shellenv) ~/.zprofile eval $(/opt/homebrew/bin/brew shellenv)然后验证一下brew --version能输出版本号说明 Homebrew 装好了。你用 macOS 13 或更高版本大概率用的是 zsh配置要写在~/.zprofile里而不是老的~/.bash_profile。2.3 装 Node.js版本选不对后面全是坑OpenClaw 要求 Node.js 版本至少 18我实际体验下来20 和 22 的 LTS 版本最省心。别装最新的奇数版本那通常是非 LTS 的可能不稳定。用 Homebrew 装 Node.js 最省事brew install node20注意Homebrew 会把 node20 安装为 keg-only 的软件包意思是它不会被默认链接到系统 PATH 中怕跟系统自带的 node 冲突。所以装完还需要手动把它加进 PATH执行echo export PATH/opt/homebrew/opt/node20/bin:$PATH ~/.zprofile source ~/.zprofile如果你是 Intel 芯片路径里的/opt/homebrew换成/usr/local即可。装完验证两个东西node -v npm -v分别显示v20.x.x和10.x.x之类的版本号就对了。注意这一步千万别偷懒跳过我见过太多人后面 OpenClaw 装不上回头一查是 node 都没装好。2.4 给 npm 配国内镜像别把时间浪费在等待上这一步算是国内关键词里最有含金量的一个建议。npm 默认官方源在国外直接执行npx openclawlatest或者npm install有可能慢到一分钟才蹦几百 KB严重的时候直接超时中断。解决办法是换成国内镜像源比如淘宝的镜像npm config set registry https://registry.npmmirror.com设置完可以验证npm config get registry输出了https://registry.npmmirror.com就说明生效了。这个改动是全局的以后你所有 npm 项目都会从这个镜像拉包国内使用体验提升非常明显实测下来能把安装时间缩短一个数量级。还有一个坑要提醒你很多 OpenClaw 相关的依赖包会附带 postinstall 脚本这些脚本有可能要去 GitHub 下载二进制文件镜像源管不到这一层。如果遇到这类问题一般需要单独配置环境变量或者给对应工具设置代理这个我们在后面问题排查部分再说。3. 正式安装 OpenClaw两条路可以走基础环境准备好之后就开始重头戏了。OpenClaw 官方提供两种主流的安装思路一种是 npx 快速路线适合大多数用户另一种是从 GitHub main 分支直接检出的源码路线适合想追新或者要改源码的开发者。3.1 快速路线npx 一条命令直接驱动最直接的安装方式其实不需要安装——用 npx 直接运行最新版本。打开终端执行npx openclawlatest init这条命令会自动下载 OpenClaw 最新包并在当前目录生成一个项目文件夹。如果你希望项目放到指定目录可以给这个命令加上文件夹名npx openclawlatest init my-claw执行过程中它会问你几个问题包括用什么包管理器npm 还是 pnpm、要不要安装一些推荐的 skill技能包、是否初始化 Git 仓库等。这些选项没有绝对的对错新手建议直接按默认回车。等它跑完你会得到一个名为my-claw的目录里面已经有项目骨架了。进入目录cd my-claw然后启动npx openclaw start第一次启动会自动安装项目依赖并初始化一些本地资源。如果你更习惯全局安装也可以执行npm install -g openclaw之后在任何目录都能直接用openclaw start启动了不用每次敲npx。3.2 源码路线用 Git 从 main 分支检出并自行安装另一条路线是直接拉官方 GitHub 仓库的 main 分支源码。适用场景是你想参与开发、修改内部逻辑或者官方最新代码修复了一个你急需的 bug但还没发布到 npm。操作方式很常规先克隆仓库git clone https://github.com/openclaw/你的仓库地址.git cd openclaw注意OpenClaw 的实际仓库地址以官方文档标注的为准GitHub 上搜索结果可能会有很多同名仓库别认错。克隆完成后安装依赖并构建npm install npm run build构建完成之后用npm start或者node 入口文件启动。源码方式装的如果 main 分支更新了你需要手动git pull重新构建而用 npm/npx 方式装的升级时就简单很多后面我会讲。不管哪条路线装完之后目录里核心的东西是一个配置文件名字一般是openclaw.config.json或者openclaw.config.ts以及存放技能包的skills/目录。3.3 初始化后目录里到底有什么我见过不少同学项目初始化成功了但面对一堆文件一脸懵。这里简单解构一下package.jsonNode 项目的元信息文件记录了项目依赖、脚本命令等。openclaw.config.jsonOpenClaw 的核心配置文件模型的 Provider、API Key、默认参数都写在这里。skills/技能包目录。OpenClaw 支持通过安装 Skill 扩展能力就像给 AI 助理添加新的工具包比如文件处理、网页抓取、定时任务等。logs/或.openclaw/运行时产生的日志、缓存、凭据存储等不用管它但排查问题时会用到。搞清楚这些文件是干嘛的后面配模型、装技能、查日志时就知道该去哪找。4. 模型接入让 OpenClaw 有大脑能干活OpenClaw 本体只是一副骨架真正让它发挥作用的是大模型。你需要给它配置一个模型服务商和 API Key它才能完成理解指令、规划步骤、执行任务这个循环。4.1 OpenClaw 支持哪几类模型服务商OpenClaw 在模型接入层面兼容性做得比较广主要分三类。第一类是官方大模型服务比如 OpenAI 的 GPT 系列、Anthropic 的 Claude 系列配置时直接填官方 API 地址和 Key 就行。这些服务国内直连通常有难度所以我一般不太建议作为国内用户的首选。第二类是国内大模型厂商包括阿里通义千问DashScope、智谱 AI、DeepSeek 等。它们很多都提供 OpenAI 兼容接口也就是说你可以像调用 OpenAI 一样调用它们只要把 baseUrl 换掉、把模型名换成对应的型号。这个方案对国内用户最友好延迟低、支付方便、注册快捷。第三类是本地模型比如 Ollama 这类工具在本地跑开源模型再把 OpenClaw 指向本地接口。好处是数据不出本机、免费可控坏处是模型能力上限低还要看你 Mac 的显存和内存扛不扛得住。4.2 配置文件写法与 API Key 设置配置模型的核心动作就是编辑配置文件。找到openclaw.config.json如果你是用 npx 方式初始化的第一次启动 OpenClaw 时它通常会引导你进行交互式配置会把模型服务商、Key 等写进去。如果没走这个流程你也可以手动创建或修改配置文件。以阿里云百炼DashScope的通义千问为例配置文件大致长这样{ model: { provider: openai-compatible, apiKey: sk-你的API-Key, baseUrl: https://dashscope.aliyuncs.com/compatible-mode/v1, model: qwen-max, options: { temperature: 0.7 } } }再举个 DeepSeek 的例子{ model: { provider: openai-compatible, apiKey: sk-你的DeepSeek-Key, baseUrl: https://api.deepseek.com/v1, model: deepseek-chat } }如果你有 OpenAI 官方 Key配置就是 baseUrl 用默认的https://api.openai.com/v1。有些用户通过国内中转服务商获取 OpenAI 兼容能力原理一样只要把 baseUrl 换成中转服务商给你的地址就行。4.3 国内用户怎么选模型和配置接口更稳根据我这段时间的体验国内用户在配置 OpenClaw 模型时有一个清晰的优先级参考首选国产大模型的 OpenAI 兼容接口。原因很简单法律合规稳妥、网络延迟低、无需额外技术改造。比如通义千问的 qwen-max、DeepSeek 的 deepseek-chat在多数 Agent 任务上表现都够用。其次如果任务对推理能力要求比较高可以选择中转服务商提供的 OpenAI 或 Claude 兼容接口但要注意选有信誉的服务商避免 Key 泄露和接口不稳定。最后纯本地跑可以选 Ollama 加载 Qwen2.5 这类开源模型。不过要做好心理准备7B 级别的模型在复杂任务上的效果跟云端大模型差距还是很明显的适合做隐私敏感的基础任务不适合做高难度推理。这里有一个很多新手会遇到的坑修改配置文件后必须重启 OpenClaw 才能生效。如果你改了配置但没重启它照样用旧配置跑。其次配置文件里如果同时存在环境变量和 config 文件里的 Key优先级要看官方文档说明一般环境变量优先级更高。排查问题时先确认到底是谁在生效别瞎猜。5. 启动 OpenClaw 并跑通第一个任务安装和配置都完成接下来就是把服务跑起来实际验证一下它能不能正常工作。这一步也是最容易暴露问题的环节我尽量把可能出现的情况都说到。5.1 启动服务与交互入口在项目目录下执行npx openclaw start启动成功后终端会显示一些日志信息包括监听端口、加载的 Skill 数量、当前使用的模型等。通常情况下OpenClaw 会提供一个终端交互界面和本地 API 服务日志里会给出访问地址。如果你在浏览器里看到http://localhost:3000之类的地址说明有网页端界面如果只有终端交互也没关系直接在终端里输入指令就行。两种入口本质一样选自己喜欢的方式即可。5.2 三个验证安装是否正常的小测试装完别急着跑复杂任务先做三个简单测试确认环境真的正常。第一个测试纯对话。直接问它你好你是谁用一句话介绍你的能力。如果它正常回复说明模型接入和基础通信链路没问题。第二个测试让它执行一个简单命令。比如问帮我查看当前目录下的文件列表。OpenClaw 如果接入了 Shell 工具或内置了文件操作能力它应该能通过工具执行命令并返回结果。这个测试是为了验证 Agent 的工具调用链路是否正常。第三个测试让它处理一个小文件。比如在项目目录放一个test.txt内容是几句中文然后让它总结一下这个文件的内容。这能验证文件读写和上下文理解能力。这三个测试都过了说明你的 OpenClaw 基本能正常干活了。如果第二步第三步失败大概率是 Skill 没装或者工具权限没开回到配置文件检查skills和permissions相关配置。5.3 常用命令速查启动、停止、查看日志、升级日常使用中你会频繁用到下面这些命令我整理成一张速查表建议直接收藏功能命令启动服务npx openclaw start初始化项目npx openclawlatest init停止服务终端按CtrlC查看版本npx openclaw --version升级到最新版npm install -g openclawlatest全局或重跑npx openclawlatest查看技能列表openclaw skill list具体子命令以官方说明为准查看运行日志日志一般在.openclaw/logs/目录下用tail -f跟踪升级这件事要提醒一句如果用全局 npm 包方式升级命令很简单但如果你用的是项目目录方式升级要在项目目录里执行npx openclawlatest update或者删掉重新 init注意备份配置。手动改过配置文件的升级前一定先备份openclaw.config.json。6. 安装过程中最常见的 6 个问题与排查方法这一部分是我实际踩坑最多的地方也是全文含金量最高的一部分。我把常见问题整理成速查表配合解决方法你遇到问题直接对照着查就行。6.1 Node.js 版本不兼容现象安装 OpenClaw 时报语法错误、依赖模块编译失败或者启动时直接提示 You are running Node.js x.x.x。原因Node.js 版本低于 18或者装了奇数版非 LTS 版本。解决用node -v查版本如果低于 18用 Homebrew 升级brew install node20然后把 PATH 设置到新版 Node保证node -v输出的是v20.x。升级完再重新安装 OpenClaw。这个问题的隐蔽之处在于macOS 可能自带一个旧版 Node尤其是通过某些安装包装的你装了新版但 PATH 顺序不对系统还在用旧版。我的排查技巧先which node看它指向哪大概率会指向/usr/local/bin/node或/opt/homebrew/bin/node。确认自己的预期路径和实际一致。6.2 npm install 速度慢或者直接超时现象npx openclawlatest init卡在类似Downloading的状态长时间不动或者报 ETIMEDOUT、ESOCKETTIMEDOUT 之类的错误。原因npm 默认源在境外网络质量不稳定。解决先设置镜像再重试npm config set registry https://registry.npmmirror.com如果还不行可以考虑用 pnpm 代替 npm它的硬链接机制在重复安装多包时明显更快。方式是安装 pnpm 后用corepack enable pnpm启用OpenClaw init 时选择 pnpm 作为包管理器。6.3 macOS 提示无权限 / 文件无法打开现象安装过程中提示EACCES: permission denied或者启动时 macOS 弹窗提示无法打开因为无法验证开发者。原因这有两种情况。一是安装路径无写权限二是 macOS 的安全策略拦截未签名文件。解决如果是路径无权限优先用sudo执行安装命令但更推荐检查目录所有权用chown -R $(whoami) ~/.npm把 npm 全局目录归属改回当前用户。如果是安全策略拦截前往系统设置 → 隐私与安全性在允许从以下位置下载的 App里选择仍要打开或者在终端运行xattr -d com.apple.quarantine /path/to/程序手动移除隔离属性。特别提醒sudo npm install -g的用法虽然能绕开权限问题但可能引起后续文件归属混乱不建议作为首选。6.4 端口被占用导致启动失败现象启动 OpenClaw 时提示端口或地址已被占用EADDRINUSE。原因上一次运行没有完全退出或者系统上其他服务占了默认端口。解决先用lsof -i :3000换成日志里提示的端口查占用进程然后用kill -9 PID结束进程再重新启动。如果 OpenClaw 支持自定义端口也可以在配置里把端口改掉避免冲突。6.5 模型连接报错、收不到回复现象OpenClaw 能启动但你发消息后它一直转圈或者报401 Unauthorized、Connection Error。原因这类问题十有八九出在模型配置环节分别是 API Key 错误、baseUrl 填错比如把官网首页地址当成接口地址填进去了、模型名填错比如服务商实际没有这个模型。解决先回到配置文件逐一核对这些字段。如果用的是openai-compatiblebaseUrl 必须以/v1结尾——这是最容易犯的错很多人把https://dashscope.aliyuncs.com填进去就完事了漏了/compatible-mode/v1。其次是确认服务商后台的 Key 是启用状态、余额充足。我的独家技巧验证模型配置是否正确不必先启动 OpenClaw直接用 curl 测试接口就行curl https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d {model:qwen-max,messages:[{role:user,content:你好}]}如果返回正常的 JSON 回复说明模型这块没问题问题出在 OpenClaw 配置如果返回错误对照错误码去服务商后台查原因。这一步能帮你快速定位到底是 OpenClaw 问题还是模型服务问题。6.6 升级、卸载和重装怎么干净执行OpenClaw 迭代速度很快新版本经常带来新功能。升级本身不复杂但我看到过很多人在升级后遇到各种诡异问题核心原因是升级不干净。如果你是用全局 npm 包的方式安装干净升级的命令是npm uninstall -g openclaw npm install -g openclawlatest先卸载再装能避免旧文件干扰。如果你原来是用 npx 方式在项目目录里跑的升级路径是npx openclawlatest init --force这个命令会根据最新模板重建项目结构但会保留你的配置。不过保险起见执行前先备份openclaw.config.json和skills/目录。彻底卸载要做的三件事删除全局包npm uninstall -g openclaw、删除项目目录、删除隐藏在用户目录下的数据目录~/.openclaw或~/.openclawrc以实际路径为准。不删数据目录的话即使重新安装旧配置和日志仍可能干扰新版本。写在最后的一些体会我在自己的 MacBook Pro 上折腾 OpenClaw 前后花了两三天踩过最快的捷径就是先把 Node 环境和 npm 镜像搞定再谈安装。说实话OpenClaw 在 macOS 上的安装并不算复杂毕竟核心就是一个 Node.js 应用。但如果你把它当作一个普通的 npm 包来处理不关心配置、不关心模型接入、不关心权限那每一步都可能暗藏惊喜。一个小的建议是安装过程中遇到报错先别急着复制粘贴去搜索认真读一遍终端输出的报错信息往往答案就在里面。最后提一个和安装无关但很重要的点OpenClaw 装上之后就像一个刚入职的实习生它能干什么、干到什么程度完全取决于你给它装了什么 Skill、配了什么模型、给了什么权限。建议安装完成之后花点时间研究一下它的 Skill 机制把常用的能力补上。这个项目迭代速度极快保持跟进官方更新你会看到它越来越顺手。