最近忙里偷闲把 OpenClaw 在 macOS 上完整本地化部署了一遍版本是 2026.2.6-3。整个过程倒不算多难但踩的坑挺细碎尤其是模型配置、Control UI 起不来、接入微信飞书这几块网上资料零零散散我干脆把这一路折腾的记录整理出来给想在 mac 上跑 OpenClaw 的朋友做个参考。先交代一下背景OpenClaw 这个开源项目前身是不少人用过的 Clawdbot主打的是多智能体个人助理核心能力是让 AI 助手不光能聊天还能调用工具、访问本地模型、接入各种 IM 平台。2026.2.6-3 这个版本修复了不少控制台和模型切换的问题在 Apple Silicon 上的表现也稳定了不少。如果你手头是一台 Mac mini 或者 MacBook想搞一个真正“本地运行、数据不出门、还能随手调用的 AI 助理”这篇文章就是照着这个目标写的。接下来我不讲虚的直接按部署前的设计、环境准备、完整部署、接入微信飞书、Skill 开发和问题排查这六块来说。1. 部署前先想清楚OpenClaw 是什么我为什么选它1.1 一个能自己“干活”的 AI 助手框架先说人话OpenClaw 是一个开源的 AI 智能体框架你可以把它理解成一个“装了调度中枢的 AI 管家”。它不只是一个聊天窗口而是能对接多个大模型、读写本地文件、调用外部 API、连接微信/飞书/钉钉等平台的执行框架。比如你让它“把昨天群里提到的那份需求整理成邮件草稿”它能自己规划步骤、调用工具、生成结果而不是只能干巴巴地回复一段文字。我当初选它就是因为市面上的 AI 工具要么太重比如 Dify 本地化插件部署折腾到怀疑人生要么太封闭只能在官方云平台里玩。OpenClaw 的定位则介于两者之间它给了一套轻量的 Skill 机制和 Channel 体系你想要什么能力自己写一个 Skill 挂进去就行不需要搞一整套复杂的工作流编排。1.2 2026.2.6-3 版本选型逻辑与运行模式取舍为什么非要盯着 2026.2.6-3 这个版本因为 OpenClaw 迭代速度太快老版本在 macOS 上普遍有两个毛病一是 Node.js 运行时版本检测有问题动不动就报 oneclaw node runtime not found二是 Control UI 经常起不来浏览器打开一片白。2026.2.6-3 是我实测下来在 Intel 和 Apple Silicon 上都能稳定跑的一个版本至少不用改源码才能启动。运行模式方面OpenClaw 在 mac 上主要有三条路直接裸机跑、用 Docker 跑、用虚拟机跑。我更推荐 Apple Silicon 用户直接用裸机方式跑因为 Docker Desktop 在 mac 上耗内存不说容器内网络映射偶尔还会出幺蛾子Intel Mac 用户如果系统比较老比如还在 macOS 12 之前倒是可以考虑 Docker隔离环境更干净。至于虚拟机除非你要同时调试多个系统环境否则没必要性能和磁盘占用都不划算。2. macOS 环境准备这些坑我在装 OpenClaw 前踩过2.1 系统版本和硬件门槛部署之前先确认自己的系统版本。OpenClaw 官方推荐 macOS 13 以上但我实测在 macOS 12 Monterey 上也能跑前提是你手动把 Node.js 和 Python 都装到较新版本。如果你用的是 macOS Sequoia15.x反而要注意 Gatekeeper 和“完整安全”策略的问题——从网上下载的安装包第一次打开时系统可能直接提示“无法打开因为无法验证开发者”。如果你看到“若要打开此 App你需要从 macOS 恢复启动 Mac并将安全策略更改为完整安全”这类提示别慌这不一定是安装包有问题而是恰好触发了 macOS 的安全策略校验。解决办法是重启 Mac按住电源键进入恢复模式在“启动安全性实用工具”里确认安全策略是“完整安全”然后重新打开安装包如果还不行才需要手动右键选择“打开”绕过单次拦截。这个我在 Sequoia 15.5 上实打实遇到过装第三方工具时几乎都有一道这个门槛。2.2 装好 Python、Node.js 和 Homebrew 的真实步骤OpenClaw 的部署脚本同时依赖 Python 3.10 和 Node.js 18。macOS 系统自带的 Python 3.9 通常不够用所以我的建议顺序是先装 Homebrew再通过 Homebrew 装 Python 和 Node.js。# 安装 Homebrew如果还没有 /bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh) # 安装 Python 3.11 和 Node.js 20 LTS brew install python3.11 brew install node20 # 把路径加进 shell 配置macOS 默认可能不会自动指向 Homebrew 版本 echo export PATH/opt/homebrew/opt/python3.11/bin:$PATH ~/.zshrc echo export PATH/opt/homebrew/opt/node20/bin:$PATH ~/.zshrc source ~/.zshrc这里有个小坑如果你之前在系统里装过 JDK 或其他开发工具容易把 PATH 搞得乱七八糟。我建议在部署前先跑一遍node -v、python3 --version确认版本跟预期一致再往下走。另一个容易忽略的是 pnpm 或 yarnOpenClaw 的脚本有时候会调用包管理器我统一用 npm 全局装好了 pnpm避免部署到一半提示找不到包管理器。2.3 磁盘空间和文件系统检查OpenClaw 装上模型缓存、依赖包和控制台资源之后随随便便就能吃 5-10GB 磁盘。如果你 mac 的“系统数据”已经占了大几十个 GB那部署前记得先清理一下否则可能装到一半因为磁盘写满而中断。我自己在 mac mini 上装的时候就吃过一次“无法写入文件”的亏最后发现是磁盘剩余空间只剩 2GB 了。清理完了之后用df -h看一眼挂载点空间确保至少留出 20GB 的可用空间再动手。另外强烈建议把 OpenClaw 装在一个独立目录里比如~/openclaw不要直接放在用户根目录或者中文路径下否则后面写 Skill 和挂数据的时候经常会出现编码问题报错还特别难查。3. 完整部署流程从下载到第一次对话3.1 获取安装包与一键部署脚本从 GitHub 上把 OpenClaw 仓库拉下来之后项目根目录一般会提供一个部署脚本比如install.sh或者deploy.sh。官方推荐的一键部署方式就是执行这个脚本它会自动安装依赖、初始化配置文件、拉起后端服务。# 克隆仓库 git clone https://github.com/openclaw/openclaw.git ~/openclaw cd ~/openclaw # 切换到 2026.2.6-3 版本如果默认分支不是这个版本 git checkout 2026.2.6-3 # 一键部署 chmod x deploy.sh ./deploy.sh如果你下载的是打包好的 release 包那么解压后直接运行项目里的start.sh也可以。注意脚本执行过程中需要联网下载 npm 包和 Python 包网络状况不好的时候容易超时如果失败了也别慌重新跑一遍脚本通常会断点续传。装完之后服务默认会在本机起两个端口一个是后端 API 端口常见的是 8080另一个是 Control UI 的端口常见的是 3000。如果脚本运行到最后没有报错但 Control UI 没自动打开先手动访问一下http://localhost:3000多半能补救。3.2 初始化配置模型、知识库和本地模型部署脚本跑完~/.openclaw或者项目目录下的config目录里会生成一个配置文件OpenClaw 的所有核心设置都在这里。最关键的是模型配置。默认情况下它会写上一些云端模型参数但如果你想本地化部署就必须改成一个自己能访问的模型服务。这里我拿 DeepSeek 和 NVIDIA NIM 各举一个例子。DeepSeek 走 OpenAI 兼容接口OpenClaw 配置里指定base_url和api_key就行model: provider: openai name: deepseek-chat base_url: https://api.deepseek.com api_key: your_api_key_here如果你是要接 NVIDIA NIM 上跑的开源模型比如 Llama-3-70B配置结构也类似只是地址换成 NIM 的服务地址。NIM 的好处是模型推理在 NVIDIA 的 GPU 环境里跑mac 本身只承担客户端角色响应速度比跑本地小模型要快很多适合想用大模型但 Mac 内存又不太够的朋友。如果你在配置里写错了模型名就会出现the agent run failed before producing a reply这类报错。说白了就是模型服务不认你填的这个名字OpenClaw 把请求发出去了但上游返回了模型不存在于是一整个 agent 运行流程直接中断。排查的时候先确认配置里的name字段跟你模型服务商提供的模型标识完全一致一个字符都不能差。3.3 Control UI 无法启动的排查网上很多人卡在 OpenClaw deployment 完成后 Control UI did not start 这一步。这个问题的本质是脚本把后端服务拉起来了但额外的前端控制台进程没能正常启动。常见原因有三个一是 3000 端口被占用二是浏览器缓存了旧的页面 JS三是 pnpm 安装的前端依赖缺失。我的排查顺序是这样的先看 3000 端口有没有进程在听lsof -i :3000如果显示node进程在监听那说明服务起来了问题多半在浏览器缓存开一个无痕窗口访问http://localhost:3000试试。如果端口没有进程就跑到项目前端目录里手动重新构建cd frontend pnpm install pnpm build pnpm start等它再打印出监听地址刷新浏览器一般就好了。别一上来就重装整个项目浪费时间。接着是初始化流程。第一次打开 Control UI会让你设置管理员账号和管理员密码这个密码保存在本地配置里主要是为了控制后面接入消息平台时的权限。初始化完成之后你可以在界面里创建多个“Agent”每个 Agent 可以绑定不同的模型和不同的 Skill 集合。如果你想在手机上的 OpenClaw 客户端里直接玩那么初始化时选择生成一个配对码用它扫码或输入即可关联手机端数据仍然是走你自己的 mac不会上传到第三方云。4. 接入微信、飞书和钉钉把 OpenClaw 变成能随时调用的助理4.1 微信接入的原理和步骤把 OpenClaw 接到微信才能真正体会到“有求必应”的感觉。官方支持的接入方式是借道企业微信的 webhook 能力或者通过个人微信的开放接口方案。我更推荐先走企业微信 webhook因为它的权限模型清晰不容易触发封控风险个人微信的接口方案变数太大之前就有人因为第三方协议更新导致登录失效。企业微信接入的步骤大概是先在企业微信后台创建一个自建应用拿到corp_id、agent_id和secret然后在 OpenClaw 的配置文件里开启 wechat channelchannels: wechat: enabled: true corp_id: 你的企业ID agent_id: 你的应用AgentId secret: 你的应用Secret callback_url: 你的公网回调地址这里面容易踩的坑是回调 URL。企业微信的事件回调要求地址必须能从公网访问家里部署的话可以用内网穿透工具或者云服务器做中转。OpenClaw 启动后日志里会输出一个/wechat/callback路径你要把这个完整地址填进企业微信后台的“接收消息服务器配置”里并且把 Token 和 EncodingAESKey 也填成和配置里一致的值。4.2 飞书、钉钉接入差异飞书和钉钉的接入逻辑跟企业微信大同小异都是“创建应用 配置回调 绑定事件订阅”三步走。飞书那边用的是app_id和app_secret配置项名称略有差别钉钉则是通过client_id和client_secret来鉴权。我在飞书上实测下来OpenClaw 对飞书的支持相对完整指令和普通消息都能识别而且卡片消息也能正常回。钉钉则要注意一点如果你用的是旧版钉钉自定义机器人它与新版企业内部应用的鉴权方式完全不同OpenClaw 走的是新版应用的事件订阅所以不要在钉钉开放平台里选错应用类型。很多人的问题不在于 OpenClaw 配置错而是钉钉后台事件订阅没配好导致消息根本推不过来。4.3 多平台共存的注意事项同一套 OpenClaw 服务可以同时开微信、飞书、钉钉三个 Channel这个没问题。但要注意三个平台的回调地址不能都是同一个路径否则平台之间会互相干扰。比较稳妥的做法是各分配一个子路径比如/wechat/callback、/feishu/callback、/dingtalk/callback然后在反向代理里分别转发到 OpenClaw 的不同端口或路径。另外多平台同时开着的时候OpenClaw 的日志会变得特别多建议把日志级别调成 info 而不是 debug不然你根本找不到自己想要的那一条。这些小细节文档里不会主动写实操过才知道有多烦。5. Skill 开发入门让 OpenClaw 学会调用你的 API5.1 Skill 的结构和触发机制OpenClaw 真正强大的地方是 Skill 扩展机制。你可以把 Skill 理解成一个“技能包”里面写清楚这个技能的描述、触发条件、以及实际执行脚本。当 AI 判断用户的任务可以用某个 Skill 完成时它会自动加载这个技能包并执行里面的逻辑。一个标准的 Skill 目录大概长这样skills/ └── weather/ ├── SKILL.md └── run.pySKILL.md是给大模型看的说明文件里面要写清楚这个技能是干什么的、什么时候触发、需要哪些参数run.py是实际的执行脚本。OpenClaw 的 agent 会先读SKILL.md然后决定要不要调用run.py。所以SKILL.md写得好不好直接决定了触发率。5.2 手写一个“调用天气 API”的 Skill我拿一个最简单的“查天气”来演示。假设要用一个公开天气 API输入城市名返回温度。那么SKILL.md这样写--- name: weather description: 查询指定城市的实时天气。当用户询问天气、温度、下雨与否时使用。 arguments: - name: city type: string description: 城市名例如 北京 required: true ---执行脚本run.py就把城市名拼接进 API 地址发起请求返回 JSONimport sys import urllib.request import json if __name__ __main__: city sys.argv[1] if len(sys.argv) 1 else 北京 url fhttps://api.example.com/weather?city{city} with urllib.request.urlopen(url) as resp: data json.loads(resp.read()) print(f{city}当前气温{data[temp]}摄氏度天气{data[condition]})把这个目录放到 OpenClaw 的 skills 目录下然后重启服务你就能在对话里直接问“北京天气怎么样”它会自动匹配到这个 Skill 并调用脚本。以后想接任何 API——查快递、发邮件、生成报价单——都是同一个套路。5.3 用 Skill 实现“写小说”的场景有人问过我网上流传的“OpenClaw 写小说”是怎么实现的。其实秘密就在 Skill 里。写小说不是单一脚本而是一套流程先用规划 Prompt 生成章节大纲再逐章调用大模型生成正文最后把结果保存到本地文件。OpenClaw 可以在一个 Skill 里编排多个步骤或者建多个 Skill 完成不同角色分工。我自己的做法是建了一个novel_writer目录SKILL.md里描述“使用多步骤方法撰写小说”run.py里先读取用户给的主题接着调用大模型的文本生成能力按“大纲—分章—润色”三步输出并把每章写入 Markdown 文件里。这样你说一句“写一个悬疑小说开头”它就能输出一整块完整内容而不是只回你一句“好的我来写”。这个用途在本地化部署下尤其合适因为小说稿件里可能有不想被云端记录的创作想法全部留在本地更放心。6. 高频报错与排查实录6.1 “unknown model: deepseek”这类模型错误unknown model 是 Zero Token 或者极端精简配置下最容易出现的问题。表面现象是安装完什么都正常但一对话就报the agent run failed before producing a reply日志里写着unknown model: deepseek。原因基本都是模型名写错了。OpenClaw 配置里的name字段必须和模型服务商接口文档里的“模型标识”完全一致比如 DeepSeek 有deepseek-chat和deepseek-reasoner两个标识不是写“deepseek”就行的。排查建议先把模型配置简化到只留一个不用多模型循环然后看日志里实际发出请求的 URL 和 body。如果请求正常发出去但返回 404 或 400那就是模型名不对如果根本没发出去就检查api_key是否为空或者配置项是否拼错。6.2 “oneclaw node runtime not found”运行时错误你在 Windows 甚至 mac 上部署时可能遇到oneclaw node runtime not found这个报错但是是“oneclaw”而 OpenClaw 写的是 openclaw——这是拼写检查都没有发现的雷区。OpenClaw 的启动器会去系统里找指定版本的 Node.js 运行时找不到就直接退出。这个问题在 mac 上常见的原因是你虽然通过 Homebrew 装了 Node.js但系统默认的node命令指向的是/usr/bin/node这个旧版本启动器又只认/usr/local/bin里的。解决的办法是把 Homebrew 的 Node.js 路径放到最前面或者用nvm安装一个固定版本然后让启动器在 PATH 里找到正确的node。如果你用的是 zsh检查一下~/.zshrc里有没有残留的旧 PATH 配置把它们清掉再跑一次。6.3 界面起不来、磁盘占用大等系统杂症Control UI 起不来的问题我在第三章已经详细讲了这里补充一个容易忽略的macOS 的防火墙可能会拦截 Node.js 的本地监听导致你在另一台设备上访问不到 3000 端口。如果要让手机或平板能用同一个局域网访问 OpenClaw 控制台记得在系统设置里给 Node.js 放行或者手动开放 3000 和 8080 端口。至于 mac 系统数据占用过大的问题OpenClaw 部署后Docker 容器镜像和模型缓存是最占空间的。如果你用 Docker 方式部署openclaw的镜像加上依赖镜像轻松超过 10GB。建议定期用docker system prune -a清理悬空镜像只在本地留当前版本的容器。要是裸机部署就重点看~/.openclaw/models和前端构建缓存模型文件可以手动删除不常用的大模型要用的时候再重新下载。还有一个不算 bug 但很常见的现象是安装 OpenClaw 之后Mac 风扇狂转。这通常是模型推理时 CPU 或 GPU 跑满导致的尤其是用 Ollama 跑本地模型时llama.cpp进程会无条件占用所有可用核心。你可以在配置里给 OpenClaw 指定模型并发数或者直接限制本地模型的线程数从四线程改成两线程温度和噪音都会明显下降而且在 M 系列芯片上响应速度几乎没差别。我在部署 OpenClaw 2026.2.6-3 的时候最深的体会是“本地化部署”这四个字听着高大上做起来其实全是一个个细碎的环境问题。模型接口配好了Node 版本不对Node 调好了Control UI 又起不来界面终于能打开了微信接入时的回调地址又让你折腾半宿。但把这些都跑通之后你会发现一个跑在你自己 mac 上的 AI 助理确实比在网页里打开对话窗口踏实得多——数据是自己的模型可以随便换想加什么能力直接写个 Skill 丢进去就行。如果你也打算在 macOS 上试一遍记住我最后一句话别图省事跳过环境检查把 Python 和 Node.js 版本提前确认好这一趟能少走一半弯路。