周末晚上，我窝在书房里准备把 OpenClaw 装到那台 M2 MacBook Air 上，结果照着网上搜来的 Ubuntu 教程一路折腾，先是 Homebrew 装依赖卡了十几分钟，好不容易跑起来又碰上agent failed before reply: session file locked (timeout 60000ms)，一晚上净跟终端搏斗了。等我真正把它跑通才发现，网上关于 OpenClaw 的安装资料九成都是 Linux 环境的，Mac 用户能找到的那点内容不是过时就是只讲半截，连“session file locked”这个高频报错都很少有人解释清楚。

这篇文章我想完整记录在 Mac 上从零安装 OpenClaw 的过程：选哪条安装路线最省心、模型 API 怎么配、那个让不少人卡住的锁文件问题到底怎么解。OpenClaw 圈里也有人直接叫它“小龙虾”，毕竟 open 加 claw，翻译过来就是一只张着钳子的小龙虾，这名字挺形象。如果你正打算在 Mac 上部署一个能自己调用工具、处理文件、接入各种服务的开源 AI 助手，这篇文章可以直接照着走。

我会尽量把每一步背后的原因也讲清楚，而不是只丢给你一串命令。毕竟这类工具装起来不难，难的是装完之后出了问题你知道去哪里查、怎么查。

1. OpenClaw 是什么，为什么值得在 Mac 上折腾它

1.1 “小龙虾”的定位：一个跑在你本机的 AI Agent 平台

OpenClaw 本质上是一个开源的 AI Agent 平台。你可能用过 ChatGPT 网页版、Claude 网页版，那种方式是“你问一句，它答一句”，所有数据和对话上下文都在对方服务器上。OpenClaw 不一样，它更像是你放在自己机器上的一个“数字管家”：你给它配置好模型 API，它就能按照自然语言指令去调用工具、读写文件、执行命令，甚至接入 Teams、Obsidian 这类外部服务。因为核心代码完全开源，部署在自己电脑上，数据不出本机，隐私上确实省心不少。

它的几个典型能力我实测下来是这样的：

• 统一接入多家模型，OpenAI、Anthropic，以及各种兼容 OpenAI 接口的服务都能挂在同一个配置下面；
• 支持多会话并行，不同任务可以拆到不同 session 里跑，互不干扰；
• 可以配置工具集，让它执行终端命令、操作文件、请求外部接口；
• 能通过插件或集成方式接入 Teams、Obsidian 等平台，变成一个常驻助手；
• 全部本地部署，配置文件、会话数据、日志都落在你自己磁盘上。

这个定位和单纯的“命令行编程助手”不太一样。Claude Code、Codex 这类工具更多是帮你写代码、改代码，OpenClaw 则更像一个通用的 Agent 运行时，你给它接什么工具，它就能干什么活。

1.2 为什么我最终选择装在 Mac 上，而不是丢到服务器

群里有人问我，装这玩意儿为什么不直接租个云服务器，还省电。我的回答是：看你怎么用。我自己大部分时间在 Mac 上写代码、记笔记、跑自动化脚本，OpenClaw 装在本机有几个实实在在的好处。

第一，开发机上调试最方便。改完配置文件不用重新打包镜像，重启一下就生效，日志直接在终端刷，出问题能立刻看到。第二，Apple Silicon 的性能完全够用。我那台 M2 跑 OpenClaw 加本地服务，内存占用大概 1GB 出头，日常开发不受影响。第三，数据颗粒度更细。服务器上的数据始终有种“托管感”，而本机上所有 session 文件、日志、配置都清清楚楚摊在目录里，出问题可以直接翻文件。第四，Mac 的生态和 OpenClaw 很搭，后面我要讲的 Obsidian 联动、launchd 定时任务，都是 macOS 上的天然优势。

1.3 谁适合装，谁其实不太需要

说实话，OpenClaw 不算一个“开箱即用”的工具，它的门槛是明摆着的：你得会用终端，能看懂报错，愿意花时间去调配置。如果你是那种只想打开网页就能用 AI 的人，那确实没必要折腾。但如果你满足下面任意一条，我建议你认真试试：

• 日常有大量重复性文件操作、文本整理、批量处理需求；
• 希望有一个能自己跑定时任务的本地 AI 助手；
• 对数据隐私敏感，不想所有对话都经过第三方平台；
• 愿意折腾，喜欢把工具链打磨成适合自己的样子。

也有人拿它和 WorkBuddy 对比。我的理解是，WorkBuddy 更偏商业团队的协作场景，有现成的团队工作流；OpenClaw 更开放，适合个人深度定制和二次开发。没有绝对的好坏，关键看你想要现成方案还是可控方案。

2. 装之前先把 Mac 环境理一遍，能省后半夜的觉

2.1 系统版本、芯片和内存的硬门槛

先说结论：macOS 13 及以上基本都能跑，Apple Silicon 建议 16GB 内存，Intel 芯片也能装但多任务会吃力一些。我自己用的 M2 MacBook Air，8GB 内存版本，OpenClaw 本体加一个前端服务跑起来问题不大，但如果同时开浏览器、IDE、Docker，内存压力就比较明显了。你要是手头是 16GB 的机器，完全不用担心。

磁盘方面，建议用默认的 APFS 文件系统就行，千万别为了“兼容性”去格式化大小写敏感的卷。OpenClaw 在大小写敏感的文件系统上跑没试过，但很多 Node.js 生态的项目在这种环境下容易出现奇怪的模块找不到问题，没必要冒这个险。

另外，终端我建议直接用 macOS 自带的 Terminal，或者装一个 iTerm2。两者都行，关键是 shell 要保持在 zsh，不要切到 sh。现在 macOS 默认就是 zsh，你只要别手滑改掉默认 shell 就没事。

2.2 Homebrew：Mac 上绕不过去的包管理器

OpenClaw 的安装过程会用到不少系统级依赖，Homebrew 基本上是 macOS 上绕不过去的一环。先检查一下你有没有装过：

brew --version

如果提示command not found，那就先装 Homebrew。安装命令官方就一行，但我建议你直接去 Homebrew 官网复制最新命令，不要用我文章里的（命令会变）。装完之后建议立刻做一件事：检查你的源是不是国内镜像。Homebrew 默认源在 GitHub，国内网络环境下经常慢到怀疑人生，甚至直接失败。

我当时的处理方式很简单，换成清华或者中科大的镜像源，然后在执行安装类命令的时候加上环境变量：

export HOMEBREW_NO_AUTO_UPDATE=1

这个变量的作用是让 brew 在安装包的时候不去自动更新自己，能省掉一大半等待时间。还有一个小技巧：如果你经常用 brew 装东西，可以把HOMEBREW_NO_AUTO_UPDATE=1直接写进~/.zshrc，一劳永逸。

注意：这里的“镜像源”指的就是把 Homebrew 的下载地址换成国内的公共镜像，完全合规，千万别去碰那些来路不明的第三方加速脚本。

2.3 Node.js 和 Git：两个绕不开的直接依赖

OpenClaw 的主程序是 Node.js 生态的，所以 Node.js 和 Git 是必须的。检查一下：

node -v git --version

如果node -v提示找不到，我建议先用 nvm 安装，而不是直接去官网下 pkg 包。原因很简单，nvm 可以随时切换 Node 版本，后面你如果遇到某些依赖编译报错，很可能就是 Node 版本不对，这时候用 nvm 切一个版本就能解决。

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重开终端后 nvm install 20 nvm use 20

我自己用的是 Node 20 LTS，OpenClaw 跑得很稳。Git 一般 macOS 上自带，如果没有，brew install git一行搞定。

2.4 先把终端和环境变量搞定

OpenClaw 装完以后，配置目录默认会在~/.openclaw或者~/.config/openclaw下面（不同版本位置可能不一样，以你装的版本为准）。我建议你在安装之前就想好一个问题：要不要把配置目录放到 iCloud 同步盘里。

这里提前打个预防针：不要放。后面第 5 节我会详细讲，OpenClaw 的 session 文件包含文件锁，放在 iCloud Drive 这种同步盘里，极容易引发session file locked报错。你现在就记住结论，把配置目录留在本地默认位置就好。

环境变量方面，你后面接模型 API 的时候会用到 key，建议不要把 key 直接写进配置文件，而是放在~/.zshrc里 export。比如：

export OPENAI_API_KEY="sk-xxxx"

这样配置文件里引用环境变量，既不担心 key 泄露，换 key 的时候也不用改配置重启服务。

3. 三条安装路线实测：脚本、源码、Docker，各有各的坑

3.1 路线一：官方一键脚本，最快但也最容易“没装上”

打开 OpenClaw 的项目仓库，README 首页一般都会给一键安装脚本。格式类似这样：

# 以仓库 README 提供的安装脚本为准，通常长这样 curl -fsSL https://raw.githubusercontent.com/<owner>/<repo>/main/install.sh | bash

我一开始走的就是这条路线。优点是快，脚本会帮你自动检测依赖、下载主程序、初始化配置。但有两个坑我不得不说。

第一个坑是网络问题。脚本要从 GitHub 拉文件，国内网络环境下经常拉到一半断掉，或者速度只有几 KB。这种时候没什么好办法，换个网络环境是效果最明显的。第二个坑是装完之后终端里执行openclaw还是提示找不到命令。原因通常是脚本把可执行文件放到了某个不在 PATH 里的目录，你需要重开终端，或者手动source ~/.zshrc。如果重开终端还不行，检查一下脚本输出的安装路径，把那个目录加进 PATH：

export PATH="$HOME/.openclaw/bin:$PATH"

装完验证：

openclaw --version

能输出版本号，说明主程序已经就位了。

3.2 路线二：源码编译，控制欲强的开发者首选

如果你和我一样，喜欢把代码抓在手里，随时能改，那源码安装更合适。步骤也不复杂：

git clone <仓库地址> openclaw cd openclaw pnpm install # 或者 npm install，看项目用的什么包管理器 npm run build # 编译主程序 npm link # 把可执行文件链接到全局 PATH

源码安装最怕的坑是 Node 版本不对。我一开始用 Node 18 装依赖，某个原生模块编译报了一堆错，后来切到 Node 20 一次通过。所以如果你看到node-gyp相关的报错，不要急着到处搜解决方案，先用 nvm 切个 Node 20 试试。

源码安装还有个隐藏好处：你可以直接跑开发模式。改完代码后不用重新 build，程序自动热重载，对想二开的人来说非常方便。缺点就是第一次装依赖确实慢，pnpm install跑了好几分钟，中间一度像卡死了一样，其实是在下载包，耐心等就好。

3.3 路线三：Docker 部署，环境隔离但性能打折

如果你是 Docker 老手，也可以直接用容器跑。前提是你已经装好了 Docker Desktop。Docker Desktop 在 Mac 上装起来本身又是一堆坑，这里不展开，就说 OpenClaw 这边的用法。

项目仓库一般会提供docker-compose.yml，典型的配置长这样：

services: openclaw: image: <镜像名> ports: - "8080:8080" volumes: - ./openclaw_data:/root/.openclaw

启动：

docker compose up -d

Docker 方案的优点很明显：环境完全隔离，不污染本机，卸载也干净。缺点也同样清楚：性能损耗、文件挂载偶尔有权限问题，而且在 Apple Silicon 上偶尔会遇到镜像的 aarch64 版本没跟上导致跑不起来。我个人的建议是，除非你本来就在用 Docker 管理一堆服务，否则没必要为了 OpenClaw 单独引入 Docker 这一层。

3.4 三条路线怎么选，我的真实建议

我把三条路线整理成一个表，你按自己的情况对号入座：

我自己的选择是：第一次先用一键脚本跑通，确认功能没问题之后，再 clone 源码本地开发。这样既能快速验证，又不影响后面深度使用。

4. 把模型接入 OpenClaw：配置文件和 Key 的那些坑

4.1 先搞清楚它能接哪些模型

OpenClaw 的模型接入方式，概括起来就三类：

• 官方 SDK 直连，比如 Anthropic 的 Claude、OpenAI 的 GPT 系列；
• 兼容 OpenAI 接口的第三方服务，比如 Qwen（通义千问）、Moonshot 这些，它们的接口格式跟 OpenAI 基本一致，只是base_url不同；
• 本地模型，比如通过 Ollama 跑的量化模型。

OpenClaw 在这块设计得很聪明，它本质上是个模型网关，你只要在配置里声明用哪个 provider、哪个模型、填什么 key，它就能往对应的服务发请求。

4.2 配置文件的常见字段和逻辑

以一份典型的 YAML 配置为例：

model: provider: openai-compatible model: qwen-plus api_key_env: QWEN_API_KEY base_url: https://dashscope.aliyuncs.com/compatible-mode/v1

几个字段我解释一下：

• provider：模型服务商的类型。如果你用的是 OpenAI 官方，就填openai；用 Qwen 这类兼容接口，填openai-compatible；
• model：具体模型名，比如qwen-plus或者gpt-4o-mini；
• api_key_env：环境变量的名字，而不是直接填 key 本身。这样配置文件和密钥分离，安全也灵活；
• base_url：接口地址。这是最容易出错的地方，很多兼容服务商并不是直接给你 OpenAI 的地址，你得去对应平台的文档里找“兼容模式”的 base_url，填错就是 404 或者 401。

我强烈建议你把 api_key 通过环境变量注入，而不是直接写进配置文件。原因很简单：配置文件可能被同步、被分享，环境变量只存在于当前 shell 会话，泄露风险小得多。

4.3 实测：先用 Qwen key 跑通，再换 Claude key

我第一次接入用的是 Qwen 的 key，因为申请方便，国内网络访问也稳定。把 key 写进~/.zshrc之后：

export QWEN_API_KEY="sk-xxx"

然后在 OpenClaw 里发起一个最简单的任务：让它写一句自我介绍。这一步看着简单，实际上是把整条链路打通——配置文件读取、模型网关转发、响应解析、会话落盘。链路通了，后面加工具、加集成才有意义。

第一次跑就报了 401，检查下来是环境变量没加载，重开终端解决。第二次报 404，换成兼容模式的 base_url 就好了。这里有个排查经验：401 基本是 key 的问题，404 基本是接口地址或者模型名的问题，400 则大概率是请求参数或模型名不匹配。按这个思路排查，大部分模型接入问题都能定位。

后来我又换成了 Claude 的 key，只需要把provider改成anthropic，model改成对应型号，重新指定 key 的环境变量名，重启服务就切过去了。整个切换过程不到两分钟，多模型切换确实是这类 Agent 平台很方便的一点。

4.4 Session 文件与对话管理：装好后第一件事不是聊天，是看会话

OpenClaw 的每个对话任务都会落一个 session 文件，里面存着上下文、执行记录、状态信息。你可以理解成每个任务一个“档案袋”，这个设计在执行长任务时非常有用——中途断了，恢复 session 就能接着跑，而不是重新开始。

常用操作：

# 列出所有会话 openclaw session list # 查看当前会话状态 openclaw session status # 清理历史会话 openclaw session clean

session 文件默认存放在配置目录下的sessions/文件夹里，每个会话一个子目录。这个目录也是第 5 节那个锁文件报错的“案发现场”，你先记住它的位置，后面排查会用上。

5. 高频报错排查实录：尤其是 session file locked

5.1 完整复盘：agent failed before reply: session file locked

这个报错是搜索热词里排在最前面的，也是我实际踩过的。先把完整报错贴出来：

agent failed before reply: session file locked (timeout 60000ms)

初次看到这个报错，很多人会懵，包括我。拆开看其实就一句话：OpenClaw 尝试对某个 session 文件加锁，等了 60 秒没等到，于是放弃响应。它的工作机制是，为了保证同一个会话不会被两个进程同时写，OpenClaw 在操作 session 前会创建一个.lock锁文件，操作完再释放。如果锁一直不被释放，程序就卡住，直到超时报错。

触发原因，常见就这三种：

1. 上一次进程没有正常退出。比如终端直接关闭、电脑休眠、进程被强制 kill，锁文件残留了；
2. 同时开了两个终端或两个进程操作同一个 session；
3. session 目录放在 iCloud Drive、Dropbox 这类同步盘里，文件锁机制在同步环境下失灵。

我的排查链路如下，你可以一步步跟着走。

第一步，先看有没有 OpenClaw 进程还活着：

ps aux | grep openclaw

如果有残留进程，先正常结束它，结束不了就 kill：

kill <进程ID>

第二步，定位锁文件。session 目录下一般会有.lock后缀的文件：

find ~/.openclaw/sessions -name "*.lock"

第三步，确认没有其他进程在用之后，直接删掉锁文件：

rm -rf <锁文件路径>

第四步，检查 session 目录是否在同步盘上。如果路径里有iCloud或者Library/Mobile Documents，那就把整个配置目录挪回本地磁盘，比如~/.openclaw，并关闭这个目录的 iCloud 同步。

第五步，检查目录权限：

ls -l ~/.openclaw/sessions

如果属主不是你当前用户，执行：

sudo chown -R $(whoami) ~/.openclaw

这一套走完，再启动 OpenClaw 就正常了。这个报错的根因十有八九是锁文件残留，不用怀疑是程序 bug。

提示：如果反复出现锁残留，建议把session clean加到你常用的清理脚本里，定时清掉不再使用的会话。

5.2 端口被占用了怎么办

OpenClaw 启动时会起一个本地服务，默认端口通常是 8080 或者 3000。如果你发现启动报EADDRINUSE，说明端口被别的进程占了。排查方式：

lsof -i :8080

它会列出占用这个端口的进程。确认是你不需要的进程，kill 掉；如果是系统服务或者你不想动的进程，那就改 OpenClaw 的配置端口，在配置文件里把端口改成 8081 或者 9000 这种不常用端口，重启即可。

5.3 模型请求超时，换个模型就好了一半

另一个高频现象是：任务发出去之后一直没有响应，日志里出现timeout或者request timed out。这种情况很多时候不是 OpenClaw 的问题，而是模型服务那边响应太慢或者限流。

我的经验是分两步处理。先调整超时和重试参数。OpenClaw 配置里一般有timeout和max_retries这类字段，把超时时间从默认值调大一些，比如 120 秒，重试次数设成 2 次。再就是换一个更快的模型。有些大模型推理慢，尤其在高峰期，换成-mini或者-lite版本的模型，响应速度会明显提升。

还有一个小技巧：别把特别复杂的任务一次性丢给它。把任务拆成几步，每一步单独跑，既方便定位问题，也不容易触发超时。

5.4 日志和 Debug：报错不可怕，可怕的是不知道去哪看

排查 OpenClaw 问题，最重要的一件事就是看日志。启动时先开 debug 模式：

export OPENCLAW_LOG_LEVEL=debug openclaw start

日志文件一般在配置目录下的logs/文件夹里，按天滚动。出问题时，先看日志的最后几十行，里面通常有具体的错误堆栈，比终端里的报错信息详细得多。我处理那个锁文件问题的时候，就是在日志里看到了“lock file already exists, waiting...”的字样，才确认是锁残留的问题。

tail -n 100 ~/.openclaw/logs/$(date +%Y-%m-%d).log

养成一个习惯：任何报错，先去日志里找完整堆栈，再判断是配置问题、网络问题还是程序问题。别急着重启，重启一百次也解决不了根因。

6. 装好只是开始：Teams、Obsidian 和定时任务玩法

6.1 把 OpenClaw 接进 Microsoft Teams，给团队加个 AI 助手

如果你所在团队用 Microsoft Teams，把 OpenClaw 接进去之后，它就变成了团队里的一个机器人成员。大家可以直接 @ 它提问、让它整理会议纪要、查询项目状态。

接入步骤大致是这样的：

1. 在 Azure 门户里创建一个 Bot 应用，拿到 App ID 和 Client Secret；
2. 给 Bot 配置 Teams 通道；
3. 设置消息回调地址，指向你的 OpenClaw 服务；
4. 在 OpenClaw 配置里填上 Teams 的 Bot 凭据，重启服务。

这里最麻烦的是第三步。Teams 机器人需要一个公网能访问到的回调地址，本地开发环境没法直接满足。我一般用内网穿透工具（比如 ngrok 这类开发辅助工具）把本机端口暴露成临时公网地址，填到 Teams 配置里。注意这只是开发调试的临时方案，正式用的话，还是建议部署到一台有固定公网地址的机器上。

6.2 和 Obsidian 联动，让 AI 帮你整理本地笔记

Obsidian 我是重度用户，所有笔记都是本地 Markdown 文件。OpenClaw 装上之后，我第一个想到的就是让它直接操作我的笔记库——毕竟对 Agent 来说，读写本地文件本来就是基础能力。

实测下来很好用的场景是批量整理。比如我有几百个散落在各个文件夹的 MD 文件，命名混乱、标签缺失。我只需要给 OpenClaw 一个指令：

扫描 /Users/me/Documents/Obsidian/Inbox 目录下的所有 Markdown 文件， 提取每个文件的前 20 个字生成标题，检查现有标签，如果没有标签就在 frontmatter 里补一个“未分类”， 然后把文件移动到 /Archive 对应的月份子目录下。

它就能按步骤批量执行，中间遇到重名文件会自动跳过并且报告。这一套手动操作几个小时的工作量，交给它几分钟就完成了。

6.3 用 macOS 自带 launchd 做定时任务

OpenClaw 有一个别人可能忽略的优势：它可以被外部定时任务驱动。macOS 自带的 launchd 比 cron 更适合做这件事，因为 launchd 能感知系统状态，休眠唤醒后可以补跑错过的任务。

一个典型的例子：每天早上九点，让 OpenClaw 汇总昨天的待办和笔记，生成一份日报。写一个 plist 文件放到~/Library/LaunchAgents/下面：

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>Label</key> <string>com.example.openclaw.daily</string> <key>ProgramArguments</key> <array> <string>/usr/bin/bash</string> <string>-c</string> <string>openclaw run "生成今日日报，整理昨天的待办事项"</string> </array> <key>StartCalendarInterval</key> <dict> <key>Hour</key> <integer>9</integer> <key>Minute</key> <integer>0</integer> </dict> <key>RunAtLoad</key> <false/> </dict> </plist>

然后加载它：

launchctl load ~/Library/LaunchAgents/com.example.openclaw.daily.plist

注意路径和环境变量的问题。launchd 启动的进程不会加载你的~/.zshrc，所以如果 OpenClaw 的可执行文件路径不在系统默认 PATH 里，你需要在 ProgramArguments 里写全绝对路径，或者在 plist 里加上EnvironmentVariables，把PATH和模型 key 的环境变量都补上。这一步我踩过坑，当时定时任务一直没跑，日志里全是因为找不到命令而失败，补上环境变量之后就正常了。

最后再分享一点个人体会。我在 Mac 上把 OpenClaw 跑起来之后，最大的感受是这类工具真正值钱的地方不在于“能聊天”，而在于你愿意花时间把它的工具链、会话、定时任务都配好。别想着一步到位，先让它帮你干一件小事——整理一个笔记文件夹、每天生成一份待办日报——顺畅了再逐步加需求。如果遇到 session 锁的问题，按第 5 节的链路查一遍基本都能解决。祝顺利。