OpenClaw 2.0 发布之后我身边好几个用 Mac 的朋友都来问安装的事情。这个工具简单说就是一个开源的终端自动化任务编排工具用 YAML 定义任务把批量文件处理、定时脚本、嵌套命令这些重复劳动压成一条命令2.0 版本重写了任务引擎和依赖管理逻辑安装方式也跟 1.x 时代完全不一样。最让我头疼的不是工具本身的配置而是 macOS 生态现在被硬生生分成了两个阵营Apple Silicon 的 M 系列芯片和老的 Intel 芯片两者在安装路径、包管理工具、二进制格式上全都有差异网上教程又常常只讲其中一种照着做必翻车。这篇笔记就是我在 M 芯片和 Intel 芯片两台机器上反复安装、反复修坑之后的完整记录新手可以直接照着走老手也建议重点看看后面排查部分。1. 安装前先搞懂M芯片和Intel芯片的区别1.1 为什么一个安装教程要分成两个版本很多 Mac 用户对 Intel 芯片和 M 芯片的印象还停留在“跑得快不快”上但 2020 年之后苹果把 Mac 的底层 CPU 架构从 x86_64 切换到了 arm64这不仅仅是性能变化而是整个软件分发逻辑都变了。Intel 芯片的 Mac 走的是 x86_64 指令集而 M 系列芯片M1、M2、M3、M4用的是 arm64 精简指令集两种架构的机器码互不兼容。OpenClaw 2.0 官方提供的是预编译二进制包所以它必须针对两个架构分别发布 macOS 版本不可能像某些脚本类工具那样“一个包走天下”。这就直接带来了安装流程上的连锁反应Homebrew 在两种芯片上的默认安装目录不同OpenClaw 依赖的 Python 3、Git、OpenSSL 等工具链在两种架构上的安装行为不同就连最终生成的二进制文件在系统安全组件眼里都不是同一样东西。我在一台 2019 年的 Intel MacBook Pro 和一台 M2 MacBook Air 上做同样一套配置命令行看起来差不多但实际执行时遇到的路径问题、权限问题、报错信息几乎全都不一样。如果你直接用别人的安装笔记而不问一句“他是什么芯片”大概率会在中间某个步骤卡死。1.2 看一眼就知道芯片型号的三种方法确认芯片是安装前必须做的第一步不要凭购买年份猜因为苹果在 2020 年到 2023 年之间有一个过渡期市面上确实存在同年份但芯片不同的机器。最直观的方法是点击屏幕左上角苹果图标选择“关于本机”在“芯片”或“处理器”一栏直接能看到 M1、M3 或者 Intel Core i7 这样的字样。更推荐在终端里用命令确认因为后面安装过程本来就要用终端顺便也能帮你判断终端本身是不是跑在正确架构下。打开终端后输入uname -m如果输出是arm64说明当前终端进程运行在 Apple Silicon 原生的 arm64 环境下如果输出是x86_64那要么是真 Intel 芯片要么是在 M 芯片上用 Rosetta 2 方式运行 Intel 版终端。想进一步确认物理芯片型号用这条命令sysctl -n machdep.cpu.brand_string确认方法命令或操作典型返回结果适用场景关于本机苹果图标 - 关于本机芯片显示 Apple M2 或处理器显示 Intel Core最快适合新手uname -m终端执行arm64 或 x86_64确认当前终端架构sysctl 查品牌sysctl -n machdep.cpu.brand_stringApple M2 / Intel(R) Core(TM) i7判断真假芯片识别 Rosetta 终端顺带说一句如果后面 OpenClaw 配置里需要绑定设备 MAC 地址做授权终端里执行ifconfig en0 | grep ether就能直接看到不用去系统设置里翻来翻去。1.3 从芯片到软件包差异是怎么一步步传导的芯片差异传导到安装环节第一个层面就是二进制格式。开发者编译 C、Rust、Go 这类语言写的程序时编译产物是针对特定 CPU 指令集的arm64 版本和 x86_64 版本是独立的两个文件。OpenClaw 2.0 的发布页里通常能同时看到openclaw-2.0.0-macos-arm64.tar.gz和openclaw-2.0.0-macos-x86_64.tar.gz两个包下载哪个完全取决于前面确认的芯片架构。第二个层面是依赖工具链。OpenClaw 2.0 运行时依赖 Python 3 和 Git而这两个东西在两种芯片上的安装路径和配置方式也不同。Homebrew 在 Intel Mac 上会把工具装进/usr/local在 Apple Silicon 上则装进/opt/homebrewPython 的第三方包很多是以预编译 wheel 形式分发的同样区分架构你在 M 芯片上用 pip 安装的包和 Intel 芯片上安装的包很多情况下是不能互相拷贝使用的。第三个层面是系统安全策略。macOS 对从网上下载的二进制有 Gatekeeper 隔离检查M 芯片的 Mac 因为引入了更严格的签名要求和系统卷加密处理未签名或未公证程序时的表现会比 Intel 机型更敏感这也是很多人在 M 芯片上安装开源工具时频繁遇到“无法打开”提示的根源。搞清楚这三层之后再去执行具体的安装命令整个流程会顺畅很多。2. 环境准备先解决Homebrew这条依赖链2.1 Homebrew是绕不开的前置条件OpenClaw 2.0 虽然官方提供的是二进制发布包但它在首次初始化和运行部分插件时需要调用系统中的 Python 3、Git、curl、tar等基础工具这些工具在 macOS 上并不是开箱即用且版本统一的。系统自带的 Git 版本普遍偏老Python 更是只带了一个仅供系统使用的框架版直接用会有各种权限和版本问题。所以我的建议是无论如何先把 Homebrew 装好它是 macOS 上事实上的软件包管理标准OpenClaw 缺的依赖都要靠它补齐。在 M 芯片和 Intel 芯片上安装 Homebrew 的入口命令是一样的/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)但装完之后的情况就完全不同了。Intel Mac 上 Homebrew 会安装在/usr/local这个目录归系统管理员所有很多时候需要sudo权限操作Apple Silicon 上 Homebrew 默认装在/opt/homebrew这是普通用户可读写的目录不需要sudo。这个差异影响深远后面安装 OpenClaw 依赖时很多Permission denied报错就是从这里冒出来的。装完如果终端提示Warning: /opt/homebrew/bin is not in your PATH记得执行eval $(/opt/homebrew/bin/brew shellenv)然后把这句话写进~/.zshrc否则brew命令根本调不到。2.2 brew装不动的时候别硬扛Homebrew 安装失败是 Mac 安装教程里面出现频率最高的问题尤其是网络环境不稳定的情况下curl下载脚本可能只下了一半或者 Git 在克隆 Homebrew 仓库时中途断掉。很多人遇到这种问题会反复重跑安装命令这是最无效的做法因为失败残留的临时文件会在下次运行时继续捣乱。正确的处理逻辑是先把现状摸清楚。执行brew config看能否正常输出版本信息如果命令找不到就是 PATH 没配上如果卡在Updating Homebrew...阶段超时多半是访问官方源不稳定此时直接退出去配镜像比等待更实际。我平常用的是清华镜像源的配置方案在终端里预先设置两个环境变量再重跑安装脚本export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git export HOMEBREW_API_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles /bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)镜像源只影响 Homebrew 自身的下载地址和预编译 bottle 的获取地址不影响安装效果装完后正常用就行。还有一个容易被忽略的点安装 Homebrew 前需要确保 Xcode Command Line Tools 已经存在否则安装脚本虽然会自动触发安装但那个图形化弹窗有时会卡住导致后续步骤一直等不到回应。2.3 补齐基础依赖Command Line Tools和GitHomebrew 安装脚本一般会自动帮你装 Command Line Tools但有些精简过的系统或者之前卸载过开发环境的机器不会触发这个流程。最好自己手动执行一次xcode-select --install这条命令会弹出图形安装窗口装的是编译器和 Git 等命令行工具的集合不搭 Xcode 本体体积小很多但是 OpenClaw 2.0 依赖链里的clang、make、git都在这里面。装完验证一下git --version clang --version如果你的 Git 版本低于 2.30建议再用 Homebrew 装一个新版brew install git系统自带的/usr/bin/git和 Homebrew 的/opt/homebrew/bin/git可以共存注意让~/.zshrc里的 PATH 优先指向 Homebrew 目录就行。除了 GitOpenClaw 运行还需要一个可用的 Python 3 解释器。别直接用系统自带 Python那两个版本在 macOS 上都有坑规范做法是执行brew install python3.11装完用python3.11来跑 OpenClaw 的启动脚本这样能避开“mac 有两个 python”的经典陷阱。2.4 终端与系统权限细节在正式开始安装之前还有两个系统层面的设置值得先处理不然配到一半会被各种权限弹窗打断。第一个是终端的完全磁盘访问权限。OpenClaw 2.0 在初始化时会在~/.config/openclaw下写配置在运行批量文件任务时会读取指定目录如果终端 App 没有访问某些受保护目录的权限任务会静默失败。建议到“系统设置 - 隐私与安全性 - 完全磁盘访问权限”中把终端、iTerm2 这类工具勾选上。这一步不是必须的但能让后面少很多莫名其妙的错误。第二个是终端自身的架构。在 M 芯片机器上如果你之前为了某些老工具把终端设置成了 Rosetta 方式打开那么终端里的uname -m会返回x86_64此时你按 Intel 流程走Homebrew 会被装到/usr/localOpenClaw 也会去下载 x86_64 版本的包整个环境就乱了。检查方法是右键点击“访达”中的终端应用选择“显示简介”在“使用 Rosetta 打开”那里看是否勾选。正常情况应保持不勾选。另外在“访达”里进入某个磁盘目录后可以在目录空白处右键选择“新建位于文件夹位置的终端窗口”直接打开指定路径的终端省去cd的麻烦这个小技巧在解压 OpenClaw 包时特别方便。3. OpenClaw 2.0安装实操M芯片与Intel芯片分开走3.1 M芯片安装流程arm64版在 M 芯片的 Mac 上安装 OpenClaw 2.0整体走的是“原生 arm64 环境 Homebrew 依赖 官方 arm64 包”这条路。下面这套流程我在 M1 和 M2 机器上各跑过一遍步骤顺序不要随意调整尤其是解压和 PATH 配置的顺序倒过来容易出现命令找不到但文件其实已经存在的情况。第一步终端里执行uname -m确认输出为arm64。如果输出不是先解决上一节说的 Rosetta 问题再继续。第二步确认 Homebrew 可用执行brew --version。如果是刚装完的 Homebrew先执行一次eval $(/opt/homebrew/bin/brew shellenv)把环境变量加载进来再执行brew update把索引刷新到最新。第三步安装依赖brew install python3.11 git这里建议明确到 3.11 而不是装默认的 Python 3.12因为 OpenClaw 2.0 当前发布版的依赖锁在 3.11等官方公告支持更高版本再升级不迟。第四步到发布页下载openclaw-2.0.0-macos-arm64.tar.gz保存到~/Downloads。下载后用shasum -a 256校验文件哈希和发布页上的 SHA256 值比对这一步能防止下到损坏文件。第五步解压并移动到目标目录cd ~/Downloads tar -xzf openclaw-2.0.0-macos-arm64.tar.gz mkdir -p ~/opt mv openclaw-2.0.0-macos-arm64 ~/opt/openclaw我习惯放在~/opt/openclaw这个位置既在用户权限范围内又方便后续升级时整目录替换。不建议直接放进/usr/local有权限坑。第六步把可执行文件所在目录加入 PATH。在~/.zshrc末尾追加一行export PATH$HOME/opt/openclaw/bin:$PATH然后执行source ~/.zshrc。第七步验证openclaw --version如果看到OpenClaw 2.0.0 (arm64)类似的输出说明安装成功且运行的是原生 arm64 版本。看到版本号但没显示架构也不代表出问题用file $(which openclaw)命令能看到真实的可执行文件架构。3.2 Intel芯片安装流程x86_64版Intel 芯片的安装流程大体相同但有几个关键差异必须注意。首先是 Homebrew 的安装位置在/usr/local而这个目录在干净系统上归root所有如果你以管理员账号执行brew install python3.11 git偶尔会遇到目录权限不足的问题。处理办法是执行下面这条命令把/usr/local的所有权交给当前用户sudo chown -R $(whoami) /usr/local这会让你免去后续频繁使用sudo的麻烦但要注意这一步只针对 Intel 芯片机器M 芯片机器的/opt/homebrew默认就是用户可写的不需要也不需要执行这条命令。接下来同样执行brew install python3.11 git然后下载openclaw-2.0.0-macos-x86_64.tar.gz解压后移动到目标目录。Intel 版和 M 版的可执行文件名和目录结构一样PATH 配置方法也一样export PATH$HOME/opt/openclaw/bin:$PATH还要特别提醒一下Intel 芯片的 Mac 上也可以安装 M 芯片版本吗答案是否定的arm64 二进制在 Intel CPU 上根本跑不起来系统会直接报Bad CPU type错误。反过来M 芯片的 Mac 在安装 Rosetta 2 之后倒是可以跑 Intel 版本的 OpenClaw但性能和稳定性都不如原生版本这块我在第五部分详细写。3.3 首次配置与功能验证装好二进制只是完成了一半OpenClaw 2.0 首次运行需要初始化配置。执行openclaw init这条命令会自动在~/.config/openclaw/下生成config.yaml里面有几个核心参数需要理解work_dir是任务执行时的工作目录default_concurrency控制并发运行的子任务数量log_level决定日志输出详细程度。默认配置可以直接用但建议把log_level从info改成warning避免跑批量任务时终端被刷屏。为了确认整个链路真的通了我建议写一个最小的任务来测试。新建一个test.yaml内容如下tasks: - name: hello_openclaw shell: echo openclaw ok然后执行openclaw run test.yaml如果能看到任务状态SUCCESS以及输出内容说明 Python 运行时、配置文件、任务引擎全部正常工作。这时候再去配置复杂任务才比较踏实否则等你在几十行 YAML 里发现跑不动的时候根本分不清是语法问题还是环境问题。3.4 为什么不能拿一个包通吃两种芯片有人会问为什么不学某些软件那样做一个 universal 二进制把两种架构的代码塞在同一个文件里让系统自动选技术上确实可行Xcode 的 lipo 工具就能合并出 universal 版本但 OpenClaw 2.0 没有这么做原因也很实际universal 二进制的体积接近两份二进制之和对以命令行工具定位的软件来说安装包体积翻倍不划算而且 OpenClaw 的插件机制里部分插件需要调用本机单独安装的扩展工具这些工具不存在 universal 版本所以最后还是得区分架构。如果你下载的发布包没有匹配你的芯片还有一个不是办法的办法从源码编译。源码包通常是以.tar.gz形式提供的解压后执行构建脚本理论上能在任意芯片上编译出对应的可执行文件。但这需要完整的编译工具链依赖版本也得对得上对一般用户来说成本很高。我的建议是优先使用官方匹配架构的预编译包只有官方确实没提供对应版本时才考虑源码编译毕竟用工具是为了省事不是给自己找编译的罪受。4. 安装过程中的高频报错与排查实录4.1 brew安装失败的三种典型场景第一个场景是curl: (7) Failed to connect to raw.githubusercontent.com port 443: Connection refused。这是下载 Homebrew 安装脚本时网络连接失败别反复重跑换成镜像源或者把脚本下载到本地再执行是更务实的做法。第二个场景是xcode-select: error: command line tools are already installed, use Software Update to install updates。这个报错看着像是已经装好了但实际经常是 Command Line Tools 的安装记录损坏或不完整。解决办法是执行sudo rm -rf /Library/Developer/CommandLineTools后重新执行xcode-select --install让它从零开始装。第三个场景是卡在Updating Homebrew...超过十分钟没反应。这是访问 GitHub 官方仓库速度太慢导致的按下CtrlC中断后按 2.2 节的方法把 brew 源换成镜像然后执行export HOMEBREW_NO_AUTO_UPDATE1跳过自动更新再跑安装命令。记住一个原则Homebrew 安装失败时处理顺序永远是“检查网络中间层 - 换源 - 清理缓存 - 重跑”而不是无脑重试。4.2 提示“无法打开”“已损坏”的真相在 M 芯片的 Mac 上第一次运行 OpenClaw最常见的弹窗是“无法打开因为 Apple 无法检查其是否包含恶意软件”或者“已损坏无法打开”。很多人看到“损坏”两个字就以为文件真的坏了其实大部分情况是 macOS 的 Gatekeeper 机制在起作用。所有通过浏览器下载的文件都会被系统标记为“来自互联网”带有com.apple.quarantine扩展属性M 芯片机器对这个标记尤其严格。解决办法不是去关闭 Gatekeeper而是只解除这个标记xattr -d com.apple.quarantine ~/opt/openclaw/bin/openclaw执行完再打开就正常了。如果文件在解压之前就被标记也可以对解压后的整个目录执行上面的命令。还有一种土办法但同样安全合理在“访达”中右键点击程序文件选择“打开”系统会弹出确认框点“打开”也能运行一次。这比跑xattr更直观但如果你需要频繁调用命令行版本建议还是用xattr一次性解除。4.3 command not found和多Python并存zsh: command not found: openclaw是另一个高频报错十有八九是 PATH 配置没生效。先在终端里执行echo $PATH看里面有没有$HOME/opt/openclaw/bin这个路径。如果没有说明~/.zshrc的追加行写错了位置或者没执行source ~/.zshrc。还有一个隐蔽情况如果你用的是系统默认的bash而不是zsh那改~/.zshrc根本不生效需要改~/.bash_profile或者在.zshrc顶部加一行判断。另一个跟 Python 相关的问题比较麻烦。OpenClaw 启动脚本默认会找一个叫python3的可执行文件而系统自带的和 Homebrew 装的可能共存加上有些机器装了 Anacondapython3指向的可能是完全不同的环境。结果是 OpenClaw 启动时报ModuleNotFoundError或者ImportError: cannot import name很可能是 Python 版本不对。用which -a python3能看到所有候选路径然后手动指定 OpenClaw 的 Python 解释器通常在它的启动脚本顶部会有一段PYTHON${PYTHON:-python3}可以改成PYTHON/opt/homebrew/bin/python3.11这样能准确锁定到 Homebrew 的 Python 3.11。4.4 解压、权限与签名验证解压过程的报错主要分两类。一类是tar: Error opening archive: Failed to open原因基本是下载不完整文件不是合法 gzip 包。先到发布页核对 SHA256不一致就重新下载。另一类是解压出来的二进制没有执行权限终端执行时报Permission denied处理方式很简单chmod x ~/opt/openclaw/bin/openclaw在安装完成后我还建议做一个签名验证确保你从发布页拿到的文件确实来自官方。执行codesign --verify --verbose ~/opt/openclaw/bin/openclaw正常会输出valid on disk和satisfies its Designated Requirement这两句话。如果提示code object is not signed at all说明这个发布包可能被改动过或者官方发布的就是未签名版本后者在开源工具里并不少见但如果同时伴随其他异常就要谨慎了。4.5 快速定位问题速查表现象错误关键字最常见原因解决方向brew 安装/更新卡住Updating Homebrew / Connection refused网络访问官方源不稳定换镜像源、设置 HOMEBREW_NO_AUTO_UPDATE1打开 OpenClaw 弹“已损坏”cannot be opened / damagedquarantine 隔离属性xattr -d com.apple.quarantine 文件路径命令找不到command not foundPATH 配置缺失或 shell 配置文件错了检查 echo $PATH、写对 .zshrc/.bash_profile 并 source启动报 Python 模块错误ModuleNotFoundError / ImportError多个 Python 并存且选错了解释器which -a python3 查候选在启动脚本里固定 python3.11执行权限报错Permission denied解压后未赋予执行权限chmod x ~/opt/openclaw/bin/openclaw架构不匹配Bad CPU type / Exec format error下载了与芯片不匹配的包uname -m 确认架构换对应发布包这张表基本涵盖了我遇到的 90% 问题。剩下 10% 属于环境太特殊比如系统版本太老导致 TLS 握手失败或者磁盘格式不支持某些符号链接这些只能具体问题具体分析但从出现概率来看把表里这几项先排查一遍通常已经能定位到根因了。5. M芯片上的兼容与性能实录5.1 Rosetta 2是什么Rosetta 2 是苹果提供的一个翻译层让 M 芯片的 Mac 可以运行 Intel 架构的应用程序。它不是一个模拟器而是把 x86_64 指令动态翻译成 arm64 指令对大部分程序来说速度损失可控但也不是完全没有代价。之所以在这一节提它是因为 OpenClaw 2.0 的 Intel 版在 M 芯片机器上是可以运行的前提是你安装了 Rosetta 2。安装方式非常简单softwareupdate --install-rosetta --agree-to-license如果你双击运行一个 Intel 版程序而 Rosetta 还没装系统也会弹窗引导安装。不过要留个心眼在 M 芯片机器上装了 Rosetta 之后终端里的uname -m仍然返回arm64但如果你从一个 Rosetta 方式启动的终端里执行命令返回就会变成x86_64。这种“终端里的架构”和“物理芯片的架构”不一致的情况是很多人误判下载包的主要原因。5.2 我的实测Intel包在M芯片上的表现我在 M2 MacBook Air 上专门做过一组对比把 Intel 版 OpenClaw 和原生 arm64 版装在同一台机器上用同一个批量文件重命名任务跑了一遍。结果是原生版本启动速度大概快了 1.5 倍纯 CPU 密集型的任务比如大量文本正则匹配耗时大约相差 20% 到 30%内存占用方面 Intel 版也明显高一些。但 OpenClaw 这类工具主要处理的事情是 IO 密集型的读文件、写文件、调外部命令这些场景受磁盘速度和系统调用的影响比 CPU 架构更大所以 Intel 版在 M 芯片上实际体验并没有想象中那么差。如果你只是因为某些原因只能拿到 x86_64 的发布包短期顶着用没问题但如果是正式环境且发布方同时提供了 arm64 版我强烈建议优先用原生版。毕竟翻译层再高效也要额外消耗资源没必要主动给自己增加不确定性。5.3 关于后续版本维护和安装扩展的建议安装完成不是终点OpenClaw 2.0 还需要持续维护。每次在发布页看到新版本我会先把openclaw --version的输出存一下然后下载对应芯片的新包解压后直接替换~/opt/openclaw整个目录配置文件在~/.config/openclaw/不会受影响。这种“二进制放独立目录、配置放固定位置”的结构让升级变得非常干净比用安装包覆盖要稳妥。另外如果你需要在多台 Mac 之间同步配置可以只同步~/.config/openclaw/config.yaml和任务文件目录不需要把整个安装目录拷过去因为不同机器的芯片架构可能导致二进制不通用。Debian 系用户喜欢用的那种“包管理器全局管理”思路在 macOS 上不彻底适用Homebrew 虽然可以安装部分桌面软件但 OpenClaw 这类快速迭代的开源工具组件自己管理目录上手反而更快。我自己折腾下来最深刻的体会是输入uname -m这个动作一定要养成肌肉记忆每次下载安装包之前先确认一下当前终端架构能避免掉一半以上的坑升级前把当前版本号记在 release note 旁边回头排查问题能少走很多弯路macOS 系统大版本升级之后第一时间检查/opt/homebrew是否仍然是 Homebrew 的主路径如果是刚迁移过来的老机器这些目录经常会有变动。工具链这东西稳定压倒一切而稳定的第一步就是让芯片架构、工具目录、运行环境三者保持一致。