1. 先把话说清楚OpenClaw是什么为什么值得在Mac上折腾OpenClaw 这段时间在我几个技术群里出现的频率明显高了很多人上来第一句就是“这东西在 Mac 上到底能不能装怎么装”我最初也愣了一下后来才反应过来大家口中的“龙虾”其实就是 OpenClaw——claw 这个词本身就是爪子的意思龙虾那对大钳子又格外显眼社区里叫着叫着就成了黑话。与其继续在群里零散回复不如把我在 Mac 上折腾出来的经验完整写下来给想上手的同学一条能直接照着走的路。简单说OpenClaw 是一个可以跑在本地的个人 AI 代理程序。它本身不自带大模型的“大脑”而是通过配置文件接入你选好的模型服务帮你完成写代码、读文件、调用命令行工具、定时任务这一类的事情。你可以把它理解成“给你打工的 AI 实习生”你给它一个目标它拆解任务自己调用工具跑完把结果汇报给你。和直接用 ChatGPT 网页版去聊天的感觉完全不同更像是在用一个能自主干活的数字员工。很多人把它和 Claude Code 放在一起对比确实有相似之处但 OpenClaw 最大的差别在于“渠道”这一层。它不局限于终端对话可以把同一个 agent 接到飞书、Teams、Telegram 这些地方让团队里的人通过自己习惯的工具和这个 AI 协作。这也是我最终选择在 Mac 上长期跑它的核心原因——我平时主力机就是 MacBook公司内部沟通又重度依赖飞书OpenClaw 正好把这两件事串起来了。这篇文章适合谁适合手里有一台 Mac、想尝试本地 AI 代理但不想去看英文文档的人也适合已经装过但中途失败、想换个方案再试的人。文章里我会给你两条完整路线一条走 Docker适合想快速体验、不想污染系统环境的人另一条走 Homebrew 加源码适合准备长期使用、希望启动更快更贴近系统的人。两条路我都实际跑过优缺点会放在对应章节里讲清楚你可以根据自己的情况选。整理环境、写配置、跑通第一次对话整个过程大概需要二十到三十分钟。别急着复制命令先把第二节的准备工作看了很多坑都能提前避开。2. 部署前的准备工作你的Mac还缺哪些条件2.1 硬件和系统版本的最低要求先说硬件。Apple Silicon 芯片的 MacM1、M2、M3、M4 系列是目前体验最好的平台Intel 芯片的老 Mac 也可以跑但 Docker 容器和原生编译这两条路的性能差距会明显一些。内存方面8GB 是门槛16GB 及以上会更从容。OpenClaw 本身占用的内存不算夸张但它要同时驻留 Node.js 进程、容器或本地服务再加上你日常还要开浏览器和编辑器内存太小容易触发系统 swap导致整个 agent 响应变慢。系统版本建议 macOS 13 Ventura 或更高。不是说要追最新版而是低版本系统自带的某些底层库对 Node.js 20 和 Docker 的支持不够完整后面编译依赖时容易出现莫名其妙的链接错误。确认系统版本的命令很简单sw_vers uname -msw_vers会输出 macOS 的版本号uname -m会告诉你芯片架构arm64是 Apple Siliconx86_64是 Intel。这两个信息后面配镜像和安装包时都要用到。磁盘空间不用太担心OpenClaw 本体加上依赖占用大约 1GB 到 2GBDocker 镜像再占 1GB 左右所以留出 5GB 空闲基本够用。2.2 两种部署方式的选择逻辑容器还是原生我之所以一上来就把“选哪条路”单独拎出来说是因为很多教程只会给你丢两段命令不会告诉你背后的取舍。你先想清楚自己的使用场景再决定走哪条比装到一半发现不对劲再回头更省时间。Docker 方式最大的优势是隔离和干净。运行时、依赖、配置文件全部被封装在容器里你不需要在宿主机上装 Node.js也不需要担心某个依赖和系统自带的版本冲突。镜像升级也简单拉一个新镜像、删掉旧容器、重新创建就行。缺点是每次调用本机工具或者访问挂载目录时容器和宿主机之间有一层翻译文件路径、环境变量、权限处理都比原生方式多绕一步。如果你只是想先试试 OpenClaw 到底好不好用或者只让它处理一些网络请求、代码生成类的任务Docker 非常合适。Homebrew 加源码的原生方式则适合我这种打算把 OpenClaw 当日常生产力工具长期跑的人。原生进程启动速度快没有容器那层隔离可以直接读取~/下的文件、调用任意命令行工具、访问 macOS 的钥匙串接入飞书或 Teams 时回调也更顺滑。代价是你需要自己维护 Node.js 环境和依赖升级时要留意版本变化。没有一个方案是绝对正确的只看匹配不匹配你的需求。2.3 必备工具清单两条部署路线有不同的前置条件我把需要提前装好的东西列成了一张表你照着核对就行。工具用途是否有安装检查HomebrewMac 上的软件包管理工具装依赖基本都靠它brew --versionGit拉取 OpenClaw 源码git --versionNode.js 20原生方式运行 OpenClaw 的运行时node -vDocker Desktop 或 Colima容器方式运行的引擎docker --version如果你发现 Homebrew 还没装可以直接在终端粘贴这条命令它是目前 macOS 上通用的安装方式/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)装完之后记得把 Homebrew 的路径加入 shell 环境Apple Silicon 机器通常是写到~/.zprofile里Intel 机器一般在/usr/local/bin。这一步很多人会漏导致后面brew命令提示 not found。Node.js 建议直接用 Homebrew 装不要从官网下 pkg 安装包因为通过包管理器安装的 Node.js 版本后续升级方便权限问题也少brew install node装完检查node -v输出大于等于v20即可。如果系统里已经有旧版本 Node.js建议升级到 20 以上太低版本会导致 OpenClaw 依赖的某些 API 不可用。3. 方法一用Docker拉起OpenClaw五分钟后先跑起来3.1 为什么优先推荐Docker方式如果你只是“听说 OpenClaw 不错想验证一下”我强烈建议先从 Docker 开始。原因很简单它提供了固定的运行环境你不用处理 Node.js 版本、依赖冲突、系统权限这些问题。一条docker run命令就能把一个完整可用的 OpenClaw 实例拉起来失败概率远低于原生方式。有些同学会担心“我用 Docker 装是不是就不能访问本地的文件了”其实不是。Docker 支持把宿主机的目录挂载进容器我在后文会给到你具体的挂载参数。只要路径映射正确容器里的 OpenClaw 完全可以读写 Mac 上指定文件夹的内容。3.2 完整部署步骤第一步确认 Docker 已经正常运行。打开 Docker Desktop等菜单栏的鲸鱼图标不再闪动之后再操作。如果你不想装 Docker Desktop用 Colima 也可以但下面的步骤我按 Docker Desktop 来写因为大多数人用的都是它。第二步创建一个专门存放 OpenClaw 数据的目录。这个目录会保存你的配置、会话记录、日志升级容器时数据不会丢mkdir -p ~/.openclaw第三步拉取镜像并创建容器。以目前官方镜像openclaw/openclaw:latest为例docker run -d \ --name openclaw \ --restart unless-stopped \ -p 7380:7380 \ -v ~/.openclaw:/data \ -e OPENCLAW_DATA_DIR/data \ openclaw/openclaw:latest这里几个参数我说一下含义-d表示以后台模式运行--name openclaw给容器起名字--restart unless-stopped表示重启 Docker 或开机后自动拉起容器-p 7380:7380把容器的 7380 端口映射到宿主机-v ~/.openclaw:/data是挂载数据目录。7380是 OpenClaw 默认的 API 端口如果你本机已经占用了这个端口可以把宿主机侧的端口改成别的值比如-p 7381:7380。第四步检查容器是否正常docker ps docker logs openclaw --tail 50docker ps能看到容器处于 Up 状态就算成功了一半docker logs是为了确认日志里没有报错。正常情况下日志最后几行会出现类似“OpenClaw server listening on 0.0.0.0:7380”的信息。3.3 验证容器是否正常容器起来了不代表它已经可以干活你还需要确认两个健康指标一是配置是否生效。用浏览器访问http://localhost:7380/health如果返回一段包含status和ok的 JSON说明 API 服务正常。二是模型连接是否通畅。如果还没配置模型OpenClaw 现在只能空转。建议随手写一个最简单的对话测试看它能不能调用后端模型返回内容。我在第五节会详细写模型配置方法这里先确认服务本身是活的即可。3.4 Docker方式的局限说完优点我得同等坦白 Docker 方式有哪些让你难受的地方。最典型的场景是你想让 OpenClaw 直接访问~/Projects下的项目文件或者调用git、node这类宿主机命令。容器里默认没有这些工具你得在容器里再装一遍或者想办法把宿主机的命令暴露进容器操作非常绕。我试过把整个宿主机根目录挂载进容器权限和安全上真的不推荐尤其是个人电脑风险太大。所以我的建议是容器方式适合评估和轻量使用。一旦你确认 OpenClaw 会成为日常工具需要频繁读写本地文件、调用本机命令行工具那就换成下面的原生方式。4. 方法二Homebrew加源码原生方式部署OpenClaw4.1 为什么要保留原生部署这条路线我在实际使用中越来越倾向原生方式核心原因就一个字快。容器方式每次要经过 Docker 的虚拟化层冷启动时尤其明显从执行openclaw命令到 agent 真正开始响应慢的时候能到十几秒。原生方式基本秒开而且它能直接调用 macOS 下的一切资源不需要像容器那样挂载来挂载去。还有一个很实在的理由容器方式维护成本高。在容器里改代码、调配置相当于隔着一层玻璃操作出了问题你很难判断是应用本身的问题还是容器环境的问题。原生方式下所有错误信息都直接打在终端里排查起来直观得多。4.2 从安装依赖到启动服务的完整步骤前置条件就是我们第二节准备的内容这里默认你已经有 Homebrew、Git 和 Node.js 20。第一步克隆源码仓库到本地。建议放在一个专门放开发工具的目录里比如~/devmkdir -p ~/dev cd ~/dev git clone https://github.com/openclaw/openclaw.git cd openclaw第二步安装项目依赖。我建议使用pnpm因为它比 npm 更快磁盘占用也更小。如果还没装 pnpm先用 Homebrew 装一下brew install pnpm pnpm install第三步初始化配置文件。OpenClaw 内置了一个初始化命令会自动在~/.openclaw/目录下生成config.yaml和日志目录pnpm openclaw init如果仓库里正好有这个命令这一步会引导你选择默认模型供应商、填写 API Key、设定数据目录。没有也没关系稍后手动编辑配置文件同样可行。第四步启动服务。开发调试时可以前台运行方便看日志pnpm openclaw start当终端出现启动成功的提示后另开一个新终端窗口跑一个最简命令测试pnpm openclaw run 用一句话介绍你自己第一次跑通的时候那种“本地 AI 代理真的活了”的感觉还是挺奇妙的。如果你希望像普通命令一样在任意目录下直接敲openclaw而不是每次都要cd ~/dev/openclaw可以做一个软链接ln -s ~/dev/openclaw/bin/openclaw.js /usr/local/bin/openclaw这样后续就能直接使用openclaw命令了注意这里的实际 bin 路径以 clone 下来的项目为准。4.3 更新与卸载原生方式更新非常简单因为你手里就是一个完整的 Git 仓库cd ~/dev/openclaw git pull pnpm install pnpm openclaw migratemigrate命令会处理数据结构的升级配置文件的字段有调整时最好执行一下。我吃过一次亏直接从旧版本跳到了新版本没跑迁移结果会话记录乱掉了后来规矩了。卸载也不复杂删掉源码目录再删掉配置目录和软链接rm -rf ~/dev/openclaw rm -f /usr/local/bin/openclaw rm -rf ~/.openclaw最后一步是把配置目录也删了这相当于彻底清空。如果你只是暂时不用建议保留配置目录免得下次安装时重新配一遍。5. 部署完成只是开始模型接入、Channel配置与日常使用很多新手卡在最后这一公里程序装好了但不知道怎么让它真正干活。这一节我专门讲模型接入和 Channel 选择这是 OpenClaw 能正常工作的关键。5.1 配置语言模型以Qwen为例OpenClaw 不自带模型它需要你先接入一个大模型 API。社区里很多人喜欢配 Qwen通义千问因为国内网络环境下访问方便还有免费额度拿来折腾很合适。在~/.openclaw/config.yaml里模型接入部分通常长这样model: provider: openai-compatible model: qwen-plus api_base: https://dashscope.aliyuncs.com/compatible-mode/v1 api_key: sk-your-qwen-api-key如果你用的是 Anthropic 兼容接口provider 那行就改成anthropic。配置完之后记得重启 OpenClaw 服务然后跑一句话测试openclaw run 你好检查一下模型连接是否正常如果模型配置有问题OpenClaw 会返回连接错误或超时。大多数情况下问题都出在api_base填错或者环境变量没有生效上我建议优先检查这两个。5.2 Channel是什么怎么选Channel 是 OpenClaw 接入到各个聊天平台的通道。说白了它决定了你和这个 agent 的交互入口。OpenClaw 内置了多个 Channel包括 CLI、飞书、Teams、Telegram 和 Slack。我自己的选择逻辑很简单个人使用专注开发场景默认 CLI 就足够了。命令行直接跑任务效率最高。团队协作如果公司用飞书可以接飞书 Channel把 agent 当成群里的一个机器人。跨国团队或者习惯国际工具链Teams 和 Slack 是更自然的选择。配置 Channel 之前一定要先明确一个问题你想让 agent 主动在群里干活还是等人 它才响应这个区别对应着不同的事件订阅配置OpenClaw 的文档里会用trigger_mode之类的字段来区分。我建议一开始选被动响应让 agent 只在被明确召唤时执行任务避免它在群里“多管闲事”。5.3 接入飞书和Teams的注意点接入飞书时最容易被忽略的是回调地址配置。飞书开放平台的事件订阅需要填一个公网可访问的 HTTPS 回调地址而 OpenClaw 默认跑在本地 7380 端口你在本地开发环境直接填内网地址是不通的。我的临时解决办法是用内网穿透工具把本地端口暴露成公网地址然后把那个地址填到飞书后台。需要注意有些内网穿透服务的免费额度带域名随机变化你得使用固定子域名的方案否则每次重启都要去飞书后台改地址。接入 Teams 的原理类似走的是 Teams 的机器人框架同样需要一个公网端点。区别在于 Teams 的事件响应格式更严格回调消息里必须有对应的应答结构OpenClaw 虽然封装了大部分逻辑但仍然可能出现 agent 迟迟不回复的情况。碰到这种问题先看日志里是否有“callback validation failed”之类的记录。一个比较常见的坑在飞书群里输出长文本时agent 的回复会被飞书截断。这是热词里提到的一个老问题我也遇到过。解决方法有两个层面一是调整模型输出的max_tokens让单次回复不要超过飞书的消息长度限制二是在 OpenClaw 的 Channel 配置里开启自动分段发送。两件事同时做基本能解决 99% 的截断问题。5.4 让OpenClaw开机自启如果你决定长期使用一定不想每次开机都手动去启动它。macOS 下有两个方案。如果你用的是 Docker 方式最简单因为我们在创建容器时已经加了--restart unless-stopped只要 Docker Desktop 跟着开机启动容器就会自动恢复。如果你用的是原生方式可以用 macOS 自带的 launchd 来实现常驻。在~/Library/LaunchAgents/下创建一个 plist 文件?xml version1.0 encodingUTF-8? !DOCTYPE plist PUBLIC -//Apple//DTD PLIST 1.0//EN http://www.apple.com/DTDs/PropertyList-1.0.dtd plist version1.0 dict keyLabel/key stringcom.openclaw.agent/string keyProgramArguments/key array string/Users/你的用户名/dev/openclaw/bin/openclaw.js/string stringstart/string /array keyRunAtLoad/key true/ keyKeepAlive/key true/ /dict /plist然后加载它launchctl load ~/Library/LaunchAgents/com.openclaw.agent.plist以后登录系统OpenClaw 会自动后台运行。注意 plist 里的路径和用户名要改成你自己机器上的实际值我第一次写的时候漏改了用户名前缀加载时直接报错。6. 踩坑记录从部署到使用我遇到过的7个问题6.1 Session file locked 的真相热词里出现的那句agent failed before reply: session file locked (timeout 60000ms)我第一次看到的时候也一头雾水。后来定位下来这就是会话锁问题OpenClaw 同一时间只允许一个进程操作某个会话文件当上一个进程没有正常退出锁文件没有被释放新进程只能等 60 秒超时就报这个错。常见触发场景是你一边在终端跑openclaw run一边又用飞书 Channel 给同一个 agent 发消息。两个入口同时尝试写入同一个 session 文件其中一个就会卡住。解决方式很直接先找到 OpenClaw 的会话目录默认是在数据目录下的sessions文件夹里把对应的.lock文件删掉然后重新执行。注意删之前要确认没有其他 OpenClaw 进程在跑否则会让那个进程的数据写入失败。检查进程的命令ps aux | grep openclaw6.2 端口占用与地址检查Mac 上同时跑的开发服务太多了7380 端口被其他进程占用的概率不小。如果你发现容器启动失败或者浏览器访问http://localhost:7380一直转圈先用这条命令看看端口归属lsof -i :7380如果输出里有其他进程占用可以在 Docker 启动参数里换一个宿主机端口比如-p 7390:7380。原生方式则可以在 OpenClaw 的配置里修改server.port字段。顺带说一句监听地址建议不要用0.0.0.0如果配置里默认是这个意味着局域网的任何设备都能访问你的 agent 接口。单机使用时改成127.0.0.1更安全。6.3 大模型返回超时当任务比较复杂时模型思考时间可能超过 OpenClaw 默认的请求超时时间表现就是 agent 还没有任何输出连接先断了。我在配置qwen-max这类较大模型时遇到过一次。解决办法是调大客户端的超时时间。在配置文件的model段加一个字段model: timeout: 120单位是秒默认值一般是 60。调成 120 之后大部分复杂任务都不会再中途断掉。注意这只是客户端等待时间实际的 API 调用时长还是取决于模型服务端的处理速度。6.4 飞书输出被截断的进一步排查前面在 Channel 配置里提过截断问题的常规解法如果两个常规方案都无效就要考虑是不是模型将 Markdown 表格或代码块渲染成了超长消息。飞书对单个消息的字符数有限制一旦超过即便开启分段发送代码块也会被拦腰切断。我的经验是让 agent 在群聊场景下尽量不要用代码块输出而是用纯文本加编号列表来组织内容。你可以把这条要求直接写到 system prompt 里模型一般都会遵守。这样处理之后截断问题再也没有复发过。6.5 环境变量不生效的问题原生方式下很多人喜欢把OPENCLAW_API_KEY之类的变量写进~/.zshrc然后发现重启终端或重启服务后不生效。这通常不是配置写错了而是当前 shell 没有重新加载配置。执行一下source ~/.zshrc或者干脆新开一个终端窗口。如果你用的是 zsh确认是~/.zshrc如果用 bash则是~/.bash_profile。两个文件改错一个你等再久也没用。6.6 Docker挂载目录的权限问题Docker 方式跑起来之后容器内进程默认以 root 身份运行在挂载的~/.openclaw目录下创建出来的文件宿主机上会显示拥有者是 root。这会导致你直接用文本编辑器修改配置时提示没有权限。解决办法是在docker run命令里指定当前用户docker run -d \ --user $(id -u):$(id -g) \ --name openclaw \ -v ~/.openclaw:/data \ openclaw/openclaw:latest加--user参数以后容器里创建的文件归属就是你宿主机上的当前用户。注意这里也要求数据目录本身对你的用户有读写权限之前已经生成的 root 文件可能需要先手动改一下归属sudo chown -R $(whoami) ~/.openclaw6.7 常见问题速查表最后把那些我记在小本本上的高频问题汇总成一张表你遇到的时候直接对照。现象主要原因快速处理容器启动后立刻退出端口被占用或配置语法错误查看docker logs openclaw执行命令提示Cannot find module依赖没有装全或 Node 版本过低重新执行pnpm install检查node -v模型能通但回答很慢网络链路问题或默认模型偏大换qwen-turbo或调大超时飞书群里 agent 不回复回调地址失效或事件订阅没公网端点检查后台回调地址查看日志日志输出乱码终端编码不是 UTF-8设置终端编码为 UTF-8我在 Mac 上把 OpenClaw 当成日常生产力工具用了几个月最大的感受是第一次部署的顺畅程度基本决定了你对这个工具的耐心。Docker 方式适合尝鲜原生方式适合落地两条路由你自己选。配置模型和 Channel 的时候慢一点多看日志大部分问题都不是什么大毛病就是路径、端口、权限、环境变量这几类反复出现。等你跑通了自己接的模型再把它挂到飞书群里让团队里的 AI 助手真正开始干活你会觉得前面折腾的这几个小时相当值。