我最初决定在 Mac 上部署 OpenClaw是被一个很现实的问题逼的对话记录、文件读取、自动操作脚本全都丢给云端 API 太不踏实。OpenClaw 这类个人智能体框架默认接云模型跑起来很顺但“本地部署”意味着模型推理、配置、日志、技能脚本都留在你自己机器上数据不再经过第三方。这篇文章就是我在 M1 MacBook 上从零折腾 OpenClaw 的全过程包括环境准备、本地模型接入、macOS 权限弹窗和跨设备协同。如果你是第一次搞本地大模型智能体照着走能少踩很多坑。1. 部署前先把 OpenClaw 的运行架构在脑子里画出来1.1 别把它当成一个普通 App很多人一开始会问OpenClaw 到底是个软件还是个大模型其实都不是。OpenClaw 本质上是一个“个人 AI 代理框架”你部署它实际上是搭了一套把“大脑”和“手脚”分开的系统大脑由大语言模型承担负责理解指令、拆解任务、决定下一步调哪个工具。手脚由各种执行器和工具承担负责真正操作电脑——打开浏览器、点击按钮、读写文件、执行命令、调用 API。本地部署的核心就是让这套东西的所有组件都在你自己的机器上运行而不是依赖某个云端服务。在 Mac 上部署时通常涉及到的组件有下面这几个组件作用部署位置模型提供者Ollama / llama.cpp / LM Studio把大模型跑起来对外提供接口本机监听 11434 端口OpenClaw 主程序智能体核心负责任务编排、工具调用本机命令行启动Companion图形化前端 / 系统托盘辅助组件本机或另一台设备Skill 技能包预定义的能力扩展存成目录和脚本本机指定目录理解这个结构太重要了。我见过不少人在第一步就搞混以为把 OpenClaw 装上就等于有了模型结果启动后发现界面黑屏、没有任何回复才反应过来模型那层根本没跑。所以部署之前先把这张图在脑子里记清楚。1.2 为什么选本地部署隐私、成本、可控先说结论本地部署不是所有场景的最优解但它有几个云 API 永远给不了的好处。第一是隐私。我自己的诉求很直接不想让浏览器操作记录、本地文件内容、长文本素材全都上传到第三方接口。本地模型推理时数据不需要离开机器哪怕断网也能用。第二是成本。云模型的 token 计费在频繁实验时特别肉疼。你让智能体反复操作网页一次会话就可能消耗几十万 token而本地模型基本只有电费成本。第三是可控。你可以自由换模型、调采样参数、改系统提示词甚至可以改代码。接口抽风、服务下线、限流策略调整这种事在本地完全不存在。当然也要接受代价本地模型的智商和指令跟随能力短期内还是比头部云模型弱推理速度受制于 Mac 的内存带宽和 GPU 规模配置成本也高不少。所以我的态度很明确本地部署适合“自己折腾自己用”如果你要的是稳定强大的生产级智能体那还是乖乖接 API 更省心。1.3 纯本地部署与“半本地”混合模式在动手之前先想清楚一件事你到底要彻底离线还是“本地 API 备胎”的混合模式纯本地部署就是所有推理都走 Ollama 或 llama.cpp模型文件自己下载离线可用。热词里大量出现“ollama部署openclaw”“本地部署deepseek”走的就是这条路。另一种是混合模式默认用云模型保证能力同时挂一个本地模型作为进口备胎。好处是断网或 API 出问题时还能继续干活坏处是配置更复杂而且数据隐私的好处打了折扣。我个人建议第一次部署先走纯本地把流程跑通再说。因为混合模式一旦出现“模型时不时没反应”的问题你根本不知道是云接口慢还是本地服务挂了排查成本直接翻倍。先用一个本地小模型把整套链路打通后面再加 API 才心里有数。2. Mac 三件套准备Homebrew、Node.js、Git 的安装与翻车修正2.1 Homebrew 安装失败的常见原因与镜像方案在 Mac 上部署任何开源项目第一步几乎都是装 Homebrew。热词里“mac安装homebrew失败”频繁出现说明这是个大众痛点。我踩过的失败大概有三类第一类网络问题导致安装脚本拉不下来。Homebrew 默认源在 GitHub国内网络环境经常连不上。解决办法是使用国内镜像源。以清华 TUNA 为例在终端执行安装脚本前先设置环境变量export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles然后再跑官方安装脚本。中科大的镜像也差不多选一个用就行。注意安装完建议把这三行写进~/.zshrc因为后续 brew update 同样需要走镜像。第二类安装到一半中断留下半成品。Apple Silicon 的 Mac 上Homebrew 默认装在/opt/homebrewIntel 的 Mac 装在/usr/local/Homebrew。如果你装了一半失败直接把这些目录删掉再清理~/.zprofile里的残留 PATH 配置然后重新装不要试图在原基础上修复。第三类Xcode Command Line Tools 没装好。Homebrew 依赖这个工具链安装时如果卡在 “Waiting for another installer to finish” 或者一直下载不动可以手动执行xcode-select --install装好后跑一下xcode-select -p能输出路径说明成功了。2.2 Node.js 版本选 LTS别用最新版OpenClaw 这类框架基于 Node.js 生态但我不建议直接去官网下载最新版本。很多依赖包对新版本支持不及时装完编译报错你很难判断是项目问题还是 Node 版本问题。我习惯用 nvm 管理 Node 版本brew install nvm然后在~/.zshrc里加上 nvm 的加载配置重启终端后nvm install --lts nvm use --lts node -v看到 v20 或 v22 的 LTS 版本就很稳。一个小坑如果你在装 Homebrew 之前先装了 nvm然后又重装了 HomebrewPATH 顺序可能会乱导致nvm命令找不到这时候重开一个终端基本能解决不用重装。2.3 Git 和终端环境变量的坑Git 一般会随 Command Line Tools 装上但还是建议确认一下git --version如果提示没有安装执行xcode-select --install就会带上 Git。另外Apple Silicon 的 Mac 上Homebrew 的二进制路径是/opt/homebrew/bin很多时候提示命令找不到就是因为这个路径没进 PATH。在~/.zshrc里加一行export PATH/opt/homebrew/bin:$PATH装完三件套之后别急着去装 OpenClaw先开一个新终端逐一执行brew doctor、node -v、git --version确认全部正常。这一步能过滤掉至少一半后面可能出现的“莫名奇妙”报错。3. 本地模型接入用 Ollama 把大模型跑在 Mac 上再让 OpenClaw 调用它3.1 为什么推荐 Ollama 而不是别的Mac 上跑本地模型有几种选择LM Studio 有图形界面llama.cpp 纯粹但需要自己编译Ollama 则最贴合命令行和自动化场景。我选 Ollama 有三个原因一是命令足够简单ollama pull一条命令就能下模型不用手动处理量化格式、safetensors、GGUF 这些底层文件。二是它自带 OpenAI 兼容接口http://localhost:11434/v1可以直接对接。OpenClaw 这类智能体框架基本都有 OpenAI 兼容的接入方式配置起来省事。三是 macOS 的性能表现好。Ollama 在 macOS 上默认走 Metal能调用 Apple Silicon 的 GPU 和统一内存实测推理速度明显好过纯 CPU 跑。安装也简单官网下载安装包或者用 Homebrewbrew install ollama装完先跑ollama serve启动服务再开一个终端去拉模型。注意如果你用的是 M 系列芯片确保 Ollama 装的是 arm64 版本而不是被 Rosetta 转译的 x86 版本否则性能打骨折。3.2 选模型要看“工具调用能力”别只看参数大小热词里“deepseek本地部署”“qwen2.5-3b 关联到 openclaw”都指向同一个问题OpenClaw 到底该配什么本地模型这里有一个很关键的认知OpenClaw 的核心任务不是陪你聊天而是调用工具操作电脑。所以选模型时第一优先级是“函数调用 / 结构化输出”能力其次才是普通问答质量。如果模型工具调用不稳定它就会经常给出错误的 JSON或者干脆不触发任何工具整个智能体就废了。我自己试过的几个模型做个粗浅的参考模型量化后约占用内存要求工具调用表现适用场景qwen2.5:3b2-3 GB8 GB 可跑一般偶尔指令跑偏轻量命令、快速响应qwen2.5:7b5-6 GB16 GB 推荐较好格式相对稳定日常自动化首选deepseek-r1:7b5-6 GB16 GB 推荐推理强但输出格式偶发飘需要思考链的复杂任务llama3.2:3b2-3 GB8 GB 可跑一般低配置 Mac 备用我的个人结论是如果你只有一台 8 GB 内存的 Mac先跑 qwen2.5:3b 把链路打通如果内存 16 GB 以上直接上 qwen2.5:7b日常体验明显更稳。有人把大模型部署到 jetson orin 那种嵌入式设备上说明这类模型对硬件的要求其实弹性很大关键是别选超出自己内存能力的模型。3.3 内存占用实测到底需要多大内存Mac 是统一内存架构模型权重、KV Cache、上下文窗口全都挤同一块内存里。我的 M1 16GB 跑 qwen2.5:7b 时Activity Monitor 里内存占用大概 7 GB同时再开浏览器和编辑器就有点紧张了。所以给个参考计算方式一个 7B 参数的模型int4 量化后权重约 4.5-5 GB运行时要加上上下文缓存实际占用在 6-8 GB 之间。OpenClaw 这种智能体框架还有个容易忽略的点系统提示词和工具定义会非常长。每次调用模型时几十个工具的描述都会被塞进上下文这意味着模型窗口至少要有 8K有条件直接上 16K 或 32K。上下文窗口越长KV Cache 占用越大实际内存需求就继续上浮。同样逻辑不要以为 8 GB 内存的 Mac 能流畅跑 7b 模型即便能加载一旦上下文涨长就会用 swap速度会变得几乎不可用。3.4 Ollama 对接 OpenClaw 的配置思路Ollama 装好、模型拉好之后先用下面命令验证服务curl http://localhost:11434/v1/models能返回 JSON 列表说明 OpenAI 兼容接口已经就绪。然后到 OpenClaw 的配置文件里指定模型提供者。不同版本的 OpenClaw 配置字段可能有差异但思路都是把 base_url 指到本地。我的配置文件大概是这样的结构llm: provider: ollama base_url: http://localhost:11434/v1 model: qwen2.5:7b options: temperature: 0.3 num_ctx: 16384这里温度建议调低一点工具调用场景下 0.2-0.4 之间比较稳太高了模型容易自由发挥输出不规范的 JSON。跑智能体不是写诗越“听话”越好。4. 主程序安装与 macOS 权限问题从“无法验证”到鼠标控制修复4.1 安装 OpenClaw 主程序以官方文档为准OpenClaw 的官方安装方式一般是拉取仓库、安装依赖、构建 CLI。整个过程等价于把核心代码放到本地然后把openclaw命令链接进 PATH。热词里“openclaw安装教程”“openclaw中文版”都很热门这里我要多说一句一律优先看官方仓库的 README不要下载来路不明的所谓“中文版”“一键版”这种包很可能被人改过跑起来你在本地执行命令、读取文件安全风险不是开玩笑的。安装完成后先确认版本号openclaw --version能正常显示版本说明主程序没问题。下一步再初始化配置目录把数据目录放到你指定的位置方便后期备份。4.2 Gatekeeper 和“无法安全验证”的根源与修复跑 macOS 的朋友对“无法安全验证”这个弹窗应该不陌生。这是 macOS 的 Gatekeeper 机制在拦截未经 App Store 验证的应用。OpenClaw 因为是开源项目签名链不完整很容易触发。Heat词“openclaw无法安全验证”指的就是这个问题。处理方式有几种最简单的在“系统设置 - 隐私与安全性”里找到被拦截的条目点“仍要打开”。如果是命令行工具被拦可以显式移除隔离属性xattr -dr com.apple.quarantine /path/to/openclaw-d是删除属性-r是递归处理目录。看到很多人直接建议关掉 Gatekeepersudo spctl --master-disable我个人不建议这么干。关掉之后整个系统对所有未签名程序都不设防相当于把大门敞开日常使用风险太高。对单个文件去隔离属性就够了。另一个隐藏坑M 系列芯片下载工具时如果不小心下了 x86 版本跑起来会提示“已损坏无法打开”。这种不是真损坏是架构不匹配重新下 arm64 版本就行。4.3 mac mouse fix鼠标、键盘权限从哪修OpenClaw 要实际控制你的电脑就绕不开 macOS 的辅助功能权限。“mac mouse fix”这个词我猜就是从“鼠标控制不了”的搜索演变来的太真实了。正常流程是在“系统设置 - 隐私与安全性 - 辅助功能”里把运行 OpenClaw 的终端程序勾上。如果需要截图能力还要在“屏幕录制”里加同一项。改完后必须完全退出再重新打开终端权限才会生效很多人卡在这一步以为加了白名单就行其实没重启应用根本不加载。还有一个隐蔽问题你是通过终端启动 OpenClaw 的所以被授权的应该是“终端”这个 App而不是 OpenClaw 本身。有时候你给终端开了辅助功能权限但终端是通过某个父进程比如 iTerm 的某些插件启动的权限又会被吞。最省事的办法直接把 Terminal、iTerm2、VS Code 这种主宿主全部加入辅助功能。4.4 第一次启动先做一件不危险的事第一次启动 OpenClaw 时别急着让它执行“删除文件”“自动化操作网页”这类任务先让它做一个只读操作比如列目录、读一个文本文件。目的有两个一是验证模型链路通没通二是验证工具调用格式对不对。本地模型的加载有一个特点第一次调用时要等模型从磁盘加载到内存可能几十秒到几分钟屏幕没有任何输出很容易被误判为死机。我的经验是盯着终端看 CPU 占用和内存占用如果 Ollama 进程在涨内存那就是在加载耐心等如果啥变化没有再看 OLLAMA 日志。启动后如果看到 “connection refused”基本就是 Ollama 没启动或者端口不对先排除模型服务再排查主程序。5. 跑起来之后更折腾的Windows Companion、WSL 状态与跨设备协作5.1 Companion 到底解决什么问题OpenClaw 的 Companion 可以理解成一个跨平台的前端 / 系统托盘组件负责提供图形界面、状态展示、快捷操作入口。很多人的实际场景是Mac 上跑模型和核心Windows 电脑专门跑 Companion当作遥控面板。热词里“openclaw windows companion 怎么配置”够高频说明跨设备协同是刚需。但到了 Windows 上坑就变多了。最大的坑是 WSL 状态不对。在 PowerShell 里执行wsl --status如果输出说 WSL 版本是 1或者提示未安装先执行wsl --update把它更新到 WSL 2。Companion 在 Windows 上依赖 WSL 2 的虚拟化网络和文件系统版本不对会直接连不上。5.2 Mac 连 Windows防火墙、IP、路径映射两台机器协同最容易翻车的三个点第一Windows 防火墙。Node 进程在 Windows 上启动后默认可能被防火墙拦死外面来的连接。需要在“Windows Defender 防火墙 - 允许应用通过防火墙”里把 Node.js 和 Companion 相关进程都加上放行否则 Mac 这边永远连不进去。第二别用 localhost。Mac 和 Windows 是两台机器所有访问都必须走局域网 IP。在 Windows 上跑ipconfig查 IPv4 地址然后在 Mac 的配置里把地址填成那个 IP。注意 Windows 如果开了多个网卡IPv4 会输出好几个选跟 Mac 在同一网段那个。第三路径映射。Companion 里的文件路径和 Mac 上的路径不是一回事。如果你在 Windows 侧指定了某个文件位置给 Mac 上的 OpenClaw 用两边路径规则对不上系统会直接拒绝执行。这种问题日志里只会有模糊的 “file not found”排查起来很费劲最好从一开始就在配置文件里把跨设备路径问题标注清楚。5.3 日志与排错方法论跨设备场景下排查顺序不能乱。我的习惯是严格按链路走先确认模型层在 Mac 本机执行curl http://localhost:11434/v1/models通了说明模型服务正常。再确认核心层看 OpenClaw 主程序的日志有没有报 “cannot connect to model”“permission denied” 之类。如果主程序本身正常最后才去查 Windows 上的 Companion。第三个才是客户端层检查防火墙、IP、WSL 网络模式。为了快速定位问题我把常遇到的问题和排查思路列成了表症状可能原因排查动作OpenClaw 无法验证 / 打不开Gatekeeper 隔离属性xattr -dr com.apple.quarantine鼠标不动、点击无效辅助功能权限未生效授权终端并重启终端模型响应慢或空白模型太小 / 上下文过长换模型或调低请求长度Companion 连不上核心WSL 版本 / 防火墙 / IPwsl --status放行端口Connection refusedOllama 未启动启动ollama serve并重测接口这套排查链路帮我省了无数时间。本地部署项目差不多都这样越接近底层的问题越要先看从模型层到核心层再到客户端层从下往上捋永远是最快的。6. 进阶调教Skill 扩展、多模型切换和我个人的最小配置6.1 Skill 机制描述写得好比脚本写得好更重要OpenClaw 真正让人上头的地方是 Skill 扩展机制。所谓 Skill就是给智能体预定义的一组能力包类似插件的概念一般由一个描述文件加若干执行脚本组成。热词“openclaw skill”被这么高频搜索说明大家都在试图自己加技能。一个 Skill 目录大概是这样的结构skills/ my-tool/ manifest.yaml run.shmanifest.yaml里写清楚这个技能叫什么、什么情况下应该调用、需要什么参数。这里有一个我在实践中发现的关键点模型不是靠读你的代码决定要不要调用 Skill 的它靠的是 manifest 里的自然语言描述。你把描述写得越贴近真实任务场景模型调用得越精准描述写得模棱两可它就会在错误的时机频繁误触发比如让它查天气它反而调用文件搜索。我自己的经验是描述里至少包含三部分技能的核心功能一句话说清。调用条件写明“当用户要求……并且……时调用”。反例写上“以下情况不要调用本技能”。反例看起来啰嗦但实际效果立竿见影能大幅降低误触发率。6.2 多模型配置与动态切换跑通一套模型之后很多人会开始琢磨同一个任务能不能让不同模型干不同的事答案是当然可以。因为本地部署没有供应商锁定你可以同时装 qwen2.5、deepseek-r1、llama3.2然后给不同任务配不同模型。我的用法是分两档任务类型推荐模型体验说明日常简单指令、文件操作qwen2.5:7b响应够快、工具调用稳复杂推理、代码生成qwen2.5:3b 或 deepseek-r1 蒸馏版质量高但速度慢资源紧缺时的后备llama3.2:3b都能跑但别指望太聪明在 OpenClaw 配置里一般可以按 profile 的方式定义多套模型参数然后通过环境变量或 CLI 参数切换。不过我的建议是第一次玩的人不要同时配三四个模型你还没摸清一个模型的脾气就堆配置出问题根本不知道谁的锅。先一个主力模型跑上一周摸清了再加备胎。6.3 我个人从零部署的最小配置清单最后分享一套我目前觉得最舒服的最小配置适合大多数第一次在 Mac 上部署 OpenClaw 的人硬件底线M1 芯片、16 GB 统一内存这是 7b 级别模型流畅运行的门槛。8 GB 机器先跑 3b别硬上。软件环境Homebrew Node LTS Ollama三件套齐全。Git 随 Command Line Tools 安装。模型选择顺手第一推荐 qwen2.5:7b工具调用格式相对稳定日常自动化足够。系统提示词里把任务范围和边界写清楚能明显减少模型胡来的概率。Skill 范围刚开始只装官方内置的 Skill不要一口气装几十个。每装一个 Skill都会把额外的描述塞进系统提示词工具越多模型越容易选错响应也越慢。日志习惯把 OpenClaw 的日志级别调到 debug跑上一整天把它的行为模式摸透后面出问题能少走一大半弯路。权限设置给终端开好辅助功能和屏幕录制权限并把 Gatekeeper 对下载包的处理搞清楚这两件事看着小实际能卡住你好几天。这套配置不追求性能最大化架构清晰排查方便更适合让人先跑起来再去慢慢折腾那些高阶玩法。我在实际部署中体会最深的一点是本地部署的难度不在“装”而在“配”。模型、权限、路径、网络任何一个环节出问题装得再顺畅也白搭。所以我现在每次重装环境都会把这套步骤固化成自己的 checklist从 Homebrew 到 Ollama 到权限授权按顺序过一遍基本半小时就能跑通。如果你也要在 Mac 上部署 OpenClaw别急着一步到位搞复杂配置先把最小链路跑通然后一个坑一个坑填这比任何教程都管用。