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 Silicon），Intel 芯片的设备是传统的 x86_64 架构。架构不同，意味着所有和二进制包、编译工具、容器镜像相关的步骤都会产生分支。
举个例子：Homebrew 官方安装脚本会自动根据芯片决定安装路径，M 芯片默认装到/opt/homebrew，Intel 芯片默认装到/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 M2，Intel 芯片会输出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/homebrew，Intel 芯片统一前缀/usr/local。这带来的直接问题是搜索脚本时经常混。我见过有人把 M 芯片机器的.zshrc写成/usr/local/bin，结果 brew 命令时好时坏，就是因为 PATH 指错了地方。
第三个差异是容器镜像平台。Docker 镜像分linux/arm64和linux/amd64两种平台，拉镜像时不指定，Docker 会尝试拉当前机器架构对应的镜像。如果某镜像只有 amd64 版本，在 M 芯片上直接运行会报exec format error。反过来 Intel Mac 上强行跑 arm64 镜像也没戏，除非用模拟器层面去兼容。
表格看得更直观：
| 维度 | M 芯片（arm64） | Intel 芯片（x86_64） |
|---|---|---|
| Homebrew 前缀 | /opt/homebrew | /usr/local |
| 原生二进制 | arm64 | x86_64 |
| Docker 默认平台 | linux/arm64 | linux/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 命令行工具与 Homebrew
OpenClaw 虽然本体不强依赖编译，但它的依赖链里有不少 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/homebrew，Intel 芯片装到/usr/local。装完以后，按芯片类型把对应 bin 目录加进 PATH。
M 芯片用户编辑~/.zshrc：
export PATH="/opt/homebrew/bin:$PATH"Intel 芯片用户则是：
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_KEY=sk-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_KEY=sk-你的密钥建议把这一行写进~/.zshrc，免得每次开终端都要重新输入。配置文件里指定provider为 dashscope，兼容端点就填上面 JSON 里的baseURL。
模型选型方面，千问系列针对不同场景有不同型号。日常对话和任务编排用 Qwen-Turbo 完全够，追求推理深度再上 Qwen-Max。验证配置是否成功，进入 CLI 模式：
openclaw chat能正常回复就说明模型链路通了。这一步如果卡住，先别怀疑 OpenClaw，用 curl 直接打一次兼容接口，确认 Key 和网络都没问题，再回头找配置原因。
4.3 Channel 选择：CLI、HTTP 与 Microsoft Teams
Channel 是 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-gyp
M 芯片用户最容易踩的坑是这个：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_modules |
| Docker exec format error | 镜像平台与机器不匹配 | 查看镜像架构，加 --platform 或弃用 Docker |
| 无法删除被锁定的文档 | 文件锁或系统占用 | 退出占用程序，重启用 shift 解锁再删 |
6. 一点点实操体会
两台机器完整部署下来，我的体会是：M 芯片 Mac 虽然偶发原生模块编译问题，但胜在性能足、资源调度好，适合把 OpenClaw 常驻跑起来，配合 HTTP 接口做本地 agent 服务；Intel 老 Mac 如果内存不大，跑 Docker 容器的整体负载偏高，更建议原生方式安装，跑 CLI 完全没压力。
最后再分享一个小技巧：每次升级 OpenClaw 或者大批量改配置之前，先备份~/.openclaw整个目录。我吃过一次亏，升级版本后会话文件格式变了，旧会话全部打不开。虽然技术上讲可以重新初始化，但那种憋屈感没必要。一个cp -r ~/.openclaw ~/.openclaw.bak的事，换来的是随时可以回退的安全感。
部署过程中哪一步卡住了，建议按“芯片架构 → 安装方式 → 配置文件 → 模型链路”逐个排查。90% 的报错都能在这一条链路里定位。
