OpenClaw 2.0 在 Mac 上安装很多人一上来就照着命令敲结果要么 Homebrew 找不到、要么 Docker 起不来、要么跑到一半突然报agent failed before reply: session file locked (timeout 60000ms)。这些问题的根源高度集中在一个点上你的 Mac 到底是 M 芯片还是 Intel 芯片。这个区别决定了 Homebrew 装到哪个目录、该下载哪个版本的 Docker Desktop、拉镜像时要不要指定平台连会话锁报错的处理思路都不一样。最近我把手头两台 Mac一台 M 芯片、一台 Intel 芯片各自完整部署了一遍踩坑记录和完整步骤整理在下面两类机器分开写照着走基本能一次过。这篇东西适合三类人第一次接触 OpenClaw、想在本机跑起来的新手已经在用但经常遇到会话锁、镜像拉错、模型 Key 不通的功能型用户想在 Mac 上完成 agent 本地化部署之后再考虑迁移到 Linux 服务器的朋友。我会尽量把每个步骤背后的“为什么”也讲清楚不只是给一串命令而是让你知道自己到底在做什么。1. OpenClaw 2.0 到底解决什么问题1.1 它并不是一个简单的命令行工具OpenClaw 2.0 本质上是一个可以自托管的 agent 编排平台。你可以把它理解成“AI 助手的中枢系统”它负责把大模型能力接到不同的入口上既能在终端交互也能提供 HTTP 接口还能接进 Microsoft Teams 这类办公工具。也就是说你不需要为每一个场景单独写一套接入代码统一配置一次OpenClaw 自己会根据你选的 channel 去完成消息收发和工具调用。从我这段时间的实测看2.0 版本相比早期版本最大的变化是配置收敛。早期版本经常要改很多分散的参数而 2.0 把模型提供方、会话存储、渠道启停都归拢到核心配置里。对普通用户来说这意味着“改一处就生效”的体验更好对想折腾的人而言也意味着遇到问题时要排查的范围更集中。还有一个容易忽略的点OpenClaw 是开源可自托管的。这一点在选型时很关键因为你的对话记录、会话文件、模型 Key 都掌握在自己手里而不是被某个第三方托管平台绑定。你要是习惯用 WorkBuddy 这类服务会发现在自由度上两者完全不是一个路子我后面会单独说。1.2 为什么 Mac 安装教程要单独讲芯片这个问题听起来很基础但它恰恰是 Mac 上部署 OpenClaw 时踩坑率最高的环节。M 芯片的设备是 ARM 架构苹果叫 Apple SiliconIntel 芯片的设备是传统的 x86_64 架构。架构不同意味着所有和二进制包、编译工具、容器镜像相关的步骤都会产生分支。举个例子Homebrew 官方安装脚本会自动根据芯片决定安装路径M 芯片默认装到/opt/homebrewIntel 芯片默认装到/usr/local。如果你在网上看到一篇教程说“vim ~/.zshrc 加 /usr/local/bin 到 PATH”而你的机器是 M 芯片那这个 PATH 配置就是错的。类似的坑在 Docker、Node.js、Python 虚拟环境里都会出现。更麻烦的是很多安装失败并不是“立刻报错”而是装完之后运行时才暴露。比如 Intel Mac 上跑npm install装某个原生模块没问题同样的命令在 M 芯片上可能直接编译失败报一堆gyp ERR!。所以安装教程如果不区分芯片等于让用户猜谜。1.3 OpenClaw 2.0 与 WorkBuddy 的选型思路很多人会拿 OpenClaw 和 WorkBuddy 做对比其实从安装和运维角度两者的核心差异一句话就能说清OpenClaw 走的是“自己掌控一切”的路线WorkBuddy 更偏向开箱即用的托管服务。如果你选 OpenClaw就要接受自己处理 Homebrew、Docker、node-gyp、会话文件锁这一整套东西。但换来的是模型可以随便换千问、OpenAI、本地模型都能接数据可以完全留在本机channel 可以按自己的需求定制。如果你只是想要一个快速可用的 agent 助手不想管配置那托管服务确实省心。我的观点是只要你愿意花一个下午把 Mac 环境理顺OpenClaw 这种自托管方案长期来看更划算因为它不会因为服务商策略调整而被迫改接口。这篇教程后面所有内容都默认你已经决定了走 OpenClaw 这条路。2. M 芯片和 Intel 芯片安装前必须搞懂的差异2.1 30 秒判断自己的 Mac 是哪种芯片动手之前先确认你的芯片类型。最直接的方法点左上角苹果菜单选“关于本机”看“芯片”或“处理器”那一行。Apple M1/M2/M3/M4 都是 M 芯片Intel Core 开头就是 Intel 芯片。命令行判断更偏向技术流打开终端输入uname -m输出arm64说明是 M 芯片输出x86_64说明是 Intel 芯片。这个方法在登录远程服务器、检查 Docker 容器架构时同样好用。如果uname -m显示的是x86_64但你的电脑其实是 M 芯片那就说明当前终端跑在 Rosetta 转译模式里。确认确切型号可以用sysctl -n machdep.cpu.brand_stringM 芯片会输出类似Apple M2Intel 芯片会输出Intel(R) Core(TM) i7-xxxx。这一步看起来多余但后面所有架构判断都以这里为准。2.2 三大硬差异架构、Homebrew 路径、容器镜像把 M 芯片和 Intel 芯片在部署 OpenClaw 时的影响归纳成三个维度记牢了基本上就不会挑错方案。第一个差异是二进制兼容性。M 芯片原生执行的是 arm64 程序Intel 芯片执行的是 x86_64 程序。从官网下载 pkg、dmg、tar.gz 时一定要选对架构包不然要么无法安装要么装上后通过 Rosetta 转译运行性能和稳定性都会打折。第二个差异是 Homebrew 的安装路径。Homebrew 在设计上就是按架构分目录的M 芯片统一前缀/opt/homebrewIntel 芯片统一前缀/usr/local。这带来的直接问题是搜索脚本时经常混。我见过有人把 M 芯片机器的.zshrc写成/usr/local/bin结果 brew 命令时好时坏就是因为 PATH 指错了地方。第三个差异是容器镜像平台。Docker 镜像分linux/arm64和linux/amd64两种平台拉镜像时不指定Docker 会尝试拉当前机器架构对应的镜像。如果某镜像只有 amd64 版本在 M 芯片上直接运行会报exec format error。反过来 Intel Mac 上强行跑 arm64 镜像也没戏除非用模拟器层面去兼容。表格看得更直观维度M 芯片arm64Intel 芯片x86_64Homebrew 前缀/opt/homebrew/usr/local原生二进制arm64x86_64Docker 默认平台linux/arm64linux/amd64转译工具Rosetta 2无需额外转译常见问题原生模块编译失败、镜像平台不匹配依赖库版本过老、编译工具链缺失2.3 Rosetta 2 与架构转译的取舍M 芯片要运行 Intel 芯片版本的软件时需要 Rosetta 2 转译层。uname -m返回x86_64但实机是 M 芯片就是终端处于转译状态。安装 Rosetta 2 的命令softwareupdate --install-rosetta安装后可以强制让某个终端会话以 Intel 模式运行arch -x86_64 zsh在这个终端里执行的node、npm、python3都会选择 x86_64 版本。什么时候需要这么做某些原生依赖只有 x86_64 预编译版本时转译是唯一的救急手段。但我不建议把 OpenClaw 这类后台常驻服务放在转译环境里跑因为长期运行的内存占用和响应速度都受影响。这里有个两难场景M 芯片上通过 Rosetta 安装的 Homebrew 会和原生 Homebrew 并存。如果你在 Intel 终端里执行brew install包会装到/usr/local下在原生终端执行则装到/opt/homebrew。混用时环境变量容易乱。我的建议是统一用原生终端只保留 M 芯片的 Homebrew除非某个依赖死活找不到 arm64 版本再开 Rosetta。2.4 芯片差异直接影响的安装清单把芯片差异映射到 OpenClaw 安装链路上你的检查清单应该是这样的Node.js 运行时M 芯片选 arm64 版Intel 选 x86_64 版可以用node -p process.arch复核。Docker Desktop下载页面明确区分 Apple Silicon 和 Intel Chip选错了连启动都可能失败。Homebrew 包本身brew 会自动按当前终端架构解析关键是确认 PATH。Python 虚拟环境python3 -m venv venv会继承当前解释器架构venv 里装的依赖也会按架构区分。原生模块像better-sqlite3、sharp、grpc这类安装时会下载对应平台的预编译二进制拉不到匹配版本就会现场编译依赖 Xcode 命令行工具。这五个点每一个我都踩过。现在再回看标题里“M 芯片和 Intel 芯片区别”真不是标题党而是实实在在决定成败的分水岭。3. OpenClaw 2.0 Mac 版安装实操3.1 安装前必备Xcode 命令行工具与 HomebrewOpenClaw 虽然本体不强依赖编译但它的依赖链里有不少 npm 原生模块所以 Xcode 命令行工具Command Line Tools必须装上。检查一下xcode-select -p如果返回/Library/Developer/CommandLineTools说明已经有了如果提示找不到执行xcode-select --install弹窗确认后等它装完。这一步在两类芯片上过程完全一样是少数不用区分架构的环节。接下来是 Homebrew。打开终端执行官方安装脚本是一条路但网络环境不好的时候脚本可能卡很久。我平时更稳的做法是先设定两个环境变量再跑脚本export HOMEBREW_BREW_GIT_REMOTE你的镜像仓库地址 export HOMEBREW_CORE_GIT_REMOTE你的镜像仓库地址 curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh | bash把仓库地址替换成你本地可达的 Homebrew 镜像即可。脚本会自动识别芯片架构M 芯片装到/opt/homebrewIntel 芯片装到/usr/local。装完以后按芯片类型把对应 bin 目录加进 PATH。M 芯片用户编辑~/.zshrcexport PATH/opt/homebrew/bin:$PATHIntel 芯片用户则是export PATH/usr/local/bin:$PATH保存后source ~/.zshrc执行brew --version验证。这里有一个很重要的判断点which brew输出路径和上面 PATH 一致说明环境正常如果指向了另一个目录说明终端里有其他配置覆盖了 PATH后续所有 brew 安装都会迷路。3.2 用 Homebrew 安装 OpenClaw 2.0如果 OpenClaw 官方提供了 Homebrew tap安装路径是最干净的。先把 tap 加进来brew tap openclaw/openclaw brew install openclaw不管 M 芯片还是 Intel 芯片只要 Homebrew 环境正常这个命令会自动拉对应架构的预编译包。装完跑一下openclaw --version不过要提醒一句Homebrew 方式能否直接用取决于官方有没有维护对应的 formula。如果brew install openclaw报formula not found说明还没有上 tap这时优先走 npm 方式或源码方式不要硬刚。npm 方式是另一条常见路径。前提是 Node.js 已经装好版本建议 18 以上。Node 官网下载时注意选对架构包或者用 nvm 管理npm install -g openclaw安装后同样验证openclaw --version。npm 方式的好处是不依赖 Homebrew tap 的更新节奏官方发版后很快就能同步。3.3 用 Docker 方式部署 OpenClaw 2.0如果你不想把 Node 环境搞得乱七八糟Docker 部署是更隔离的选择。第一步是下载正确的 Docker Desktop官网下载页明确分成 Apple Silicon 版和 Intel Chip 版M 芯片机器选前者Intel 机器选后者。这一步选错镜像拉下来往往跑不起来或者跑起来性能差得离谱。装好以后先验证 Docker 平台docker version然后拉镜像。镜像名以官方仓库为准常见启动方式大概是mkdir -p ~/.openclaw docker run -d --name openclaw \ -v ~/.openclaw:/data \ -e DASHSCOPE_API_KEYsk-xxx \ -p 127.0.0.1:8080:3000 \ openclaw/openclaw:2.0这段命令的含义把宿主机~/.openclaw目录映射到容器/data让会话文件持久化模型 Key 通过环境变量传进去避免写死在代码里端口 8080 对应容器内 3000。启动后docker logs openclaw能看到日志。关于 Docker 架构拉完镜像后建议确认一下docker image inspect openclaw/openclaw:2.0 --format {{.Architecture}}M 芯片机器上输出arm64是原生顺畅的如果输出amd64说明兼容层在跑能用但不舒服。反过来Intel 机器上应该输出amd64。这里能用--platform linux/arm64或--platform linux/amd64强制指定平台但要确保该平台镜像真实存在。3.4 源码方式与一键部署脚本想紧跟最新功能或者需要改内部逻辑就 clone 源码自己装git clone 官方仓库地址 openclaw cd openclaw npm install npm run build源码方式在 M 芯片上最容易遇到原生模块编译问题也就是后面第 5 节要处理的 node-gyp。在这个环节M 芯片用户要特别注意npm install过程中如果报错先不要重试信息里往往会明确点名某个依赖包和架构。有时候删除node_modules后重新安装加上npm config set python python3能解决大部分编译找不到解释器的问题。一键部署脚本通常是官方仓库里的scripts/install.sh。我的建议是不管脚本来源先下载到本地用编辑器打开看一眼再执行curl -fsSL 官方脚本地址 -o install.sh code install.sh bash install.sh站在工程习惯的角度curl | bash这种方式虽然快但完全不透明。OpenClaw 这种会操作你本机会话文件的程序更值得先检查再运行。4. 配置核心模型接入与 Channel 选择4.1 配置文件结构与初始化安装完成后先初始化配置文件openclaw init这会在用户目录下生成.openclaw配置目录里面包含主配置文件和会话存储目录。2.0 的配置中心化程度高模型提供方、channel、会话存储都在同一个文件里管理。配置文件的常见结构大致是{ model: { provider: dashscope, baseURL: https://dashscope.aliyuncs.com/compatible-mode/v1, apiKeyEnv: DASHSCOPE_API_KEY }, channels: [cli, http], storage: { dir: /Users/yourname/.openclaw/sessions } }channels字段就是标题热词“怎么选择 channel”的答案这里写哪个OpenClaw 就启用哪个入口。初次配置建议只开cli等跑通基本对话再逐步加上 HTTP、Teams。4.2 接入千问 Qwen 模型OpenClaw 2.0 接模型走的是 OpenAI 兼容协议所以千问 Qwen 也能顺利接入。先在终端里设置环境变量export DASHSCOPE_API_KEYsk-你的密钥建议把这一行写进~/.zshrc免得每次开终端都要重新输入。配置文件里指定provider为 dashscope兼容端点就填上面 JSON 里的baseURL。模型选型方面千问系列针对不同场景有不同型号。日常对话和任务编排用 Qwen-Turbo 完全够追求推理深度再上 Qwen-Max。验证配置是否成功进入 CLI 模式openclaw chat能正常回复就说明模型链路通了。这一步如果卡住先别怀疑 OpenClaw用 curl 直接打一次兼容接口确认 Key 和网络都没问题再回头找配置原因。4.3 Channel 选择CLI、HTTP 与 Microsoft TeamsChannel 是 OpenClaw 术语通俗理解就是“入口”。选 Entry 不是越多越好我的实操体会是分三个阶段逐步加。第一优先级是 CLI。CLI 模式下你能直接看到原始输出和错误信息排查问题最方便。几乎所有配置变更我都会先在 CLI 里验证确认无报错再去接其他入口。第二优先级是 HTTP。本地起一个服务端口其他程序通过 API 调用。这个适合你打算把 OpenClaw 能力集成到自己的脚本或有前端界面时使用。记得监听地址只绑127.0.0.1不要直接暴露到局域网。第三优先级才是 Microsoft Teams。这个适合团队共享一个 agent 的场景配置走 Teams 的 webhook 或 Bot 集成把 Teams 的消息转发到 OpenClaw 再回传。我实测下来Teams 接入的难点不在 OpenClaw 这边而是 Teams 应用注册和权限配置。建议先单独在 Teams 侧建个测试应用确认能收发消息再让 OpenClaw 接管处理。4.4 与 Obsidian 联动让 agent 读你的笔记Obsidian 本质是本地 Markdown 文件库OpenClaw 要联动不需要装什么神秘插件直接给 agent 指向你的 vault 目录即可。在配置文件的storage下加一个notesDir这样的字段notesDir: /Users/yourname/Documents/ObsidianVault设置好以后你可以让 agent 基于笔记内容做总结、找任务、生成新笔记。比如我会把每周计划写成 Markdown 文件然后让 OpenClaw 结合 Qwen 帮我拆解执行步骤。这其实是把私人知识库变成 agent 上下文的一种轻量做法。但有两点要注意一是不要把整个 vault 目录无差别地暴露建议单独划一个agents子目录放给 agent 看的笔记二是 markdown 文件里不要写密钥、口令这类敏感信息OpenClaw 会把这些文件内容作为上下文发给模型等于变相泄露。5. 常见问题与排查技巧实录5.1 agent failed before reply: session file locked 处理这个报错可以说是 OpenClaw 日常使用中出现频率最高的一个agent failed before reply: session file locked (timeout 60000ms)。我第一次遇到的时候整个人是懵的以为是网络或者模型问题后来才定位到是会话文件锁。解释一下原理OpenClaw 的会话存储是文件级持久化每次交互要读写会话文件。如果两个进程同时访问同一个 session 文件后进来的进程会拿不到锁等待 60 秒超时后直接报错。最常见的触发场景是你开了多个终端窗口都在用同一个会话或者上次进程没有正常退出锁文件残留在磁盘上。排查和解决步骤我整理成了一套固定流程ps aux | grep openclaw把所有 OpenClaw 进程列出来确认是不是多开。pkill -f openclaw结束残留进程。如果pkill不行就kill -9加具体 PID。然后进入会话目录ls -la ~/.openclaw/sessions找到.lock后缀文件或对应的会话数据库文件确认进程已经没了之后备份再删除锁文件。删除前务必确认没有正运行的服务在写这个文件否则删锁后数据会损坏。关于预防我的经验是多个终端窗口尽量用不同 session 名比如openclaw chat --session daily和openclaw chat --session dev后台常驻服务用独立的 session不要直接关终端窗口先按exit或/exit正常退出。如果确实需要更大的并发容忍度可以尝试把锁超时从 60000ms 调大到 120000ms但这是治标不治本锁冲突的根源不解决延长超时只是把报错推迟。5.2 Homebrew 安装 OpenClaw 失败Homebrew 装 OpenClaw 最常见的报错是formula not found。先确认是不是没有执行brew tap或者该 formula 尚未发布。这种情况我会直接切 npm 方式不耗时间等。另一个高频问题是权限。Homebrew 安装过程中如果做了部分目录的写操作可能因为权限不对中断。处理方式是把 brew 目录所有权交还给当前用户sudo chown -R $(whoami) $(brew --prefix)顺手再brew doctor检查一下环境它会提醒路径冲突和残留引用这两类问题在 M 芯片和 Intel 芯片混用时尤其常见。还有网络导致的失败常见于官方脚本卡在下载阶段。这时候不要反复重试同一命令先设好镜像环境变量再跑安装脚本。重试前检查~/.zshrc里的HOMEBREW_*环境变量确认没被干扰。5.3 原生模块编译失败与 node-gypM 芯片用户最容易踩的坑是这个npm install过程中某个依赖需要编译原生模块报gyp ERR!一长串。原因通常是 Xcode 命令行工具版本不对或者编译目标架构与当前 Node 不匹配。修复步骤按顺序来xcode-select --install sudo xcodebuild -license accept npm config set python python3 npm rebuild重新npm install。如果还失败看一下报错里有没有arm64字样有时候是依赖从 npm 拉下来的包只带 x86_64 预编译二进制。这种情况在 M 芯片上可能要等依赖方发布 arm64 版本或者临时用 Rosetta 终端装一遍。Intel 芯片上这个报错少很多常见的是 Node 版本太老导致 npm 拉不到匹配版本的预编译包。升级 Node 到 LTS 版本后重试即可。5.4 Docker 镜像拉取与平台不匹配Docker 方式下最经典的报错是容器启动后立刻退出日志里写着exec: sh: executable file not found in $PATH或者exec format error。基本可以断定是镜像平台和机器不匹配。先用命令查看镜像实际架构docker image inspect openclaw/openclaw:2.0 --format {{.Os}} {{.Architecture}}M 芯片机器如果是linux amd64要么找 arm64 版本的镜像要么在启动时显式加平台参数docker run --platform linux/amd64 ...但 amd64 镜像在 M 芯片上走模拟会慢不是长久之计。Intel Mac 上拉镜像时 Docker 默认会拉 amd64如果只有 arm64 镜像存在建议直接放弃 Docker 方式改用 Homebrew 或 npm 原生安装。5.5 常见问题速查表问题可能原因快速处理agent failed before reply: session file locked多进程共用会话或不正常退出留锁结束残留进程删除会话锁文件Homebrew formula not found没 tap 或官方尚未上架用 npm 方式替代安装npm install 编译失败原生模块缺工具链或架构不匹配重装 Xcode CLT重建 node_modulesDocker exec format error镜像平台与机器不匹配查看镜像架构加 --platform 或弃用 Docker无法删除被锁定的文档文件锁或系统占用退出占用程序重启用 shift 解锁再删6. 一点点实操体会两台机器完整部署下来我的体会是M 芯片 Mac 虽然偶发原生模块编译问题但胜在性能足、资源调度好适合把 OpenClaw 常驻跑起来配合 HTTP 接口做本地 agent 服务Intel 老 Mac 如果内存不大跑 Docker 容器的整体负载偏高更建议原生方式安装跑 CLI 完全没压力。最后再分享一个小技巧每次升级 OpenClaw 或者大批量改配置之前先备份~/.openclaw整个目录。我吃过一次亏升级版本后会话文件格式变了旧会话全部打不开。虽然技术上讲可以重新初始化但那种憋屈感没必要。一个cp -r ~/.openclaw ~/.openclaw.bak的事换来的是随时可以回退的安全感。部署过程中哪一步卡住了建议按“芯片架构 → 安装方式 → 配置文件 → 模型链路”逐个排查。90% 的报错都能在这一条链路里定位。