如果你打开过 OpenClaw 的 GitHub 主页大概率会和我第一次看到时一样先是一喜终于有个能自己动手干活的 AI Agent 框架了然后一皱眉文档里大量命令都是 Linux 视角的真要在一台 macOS 上从头配还是有不少小坑在前面等着。这篇文章是把 OpenClaw 部署到 macOS 全过程的完整记录从最基础的环境检查讲起一路到模型接入、Skills 安装、Chrome 控制、CAU Computer 设置最后再聊聊升级和日志排查。适合这几类人看主力机是 MacBook、系统版本还停留在比较旧的 macOS、之前没怎么折腾过 Agent 框架、想接大模型 API 或者本地 Ollama 做自动化任务。不会涉及云平台绑定的方案以纯本地方案为主。1. 为什么选 macOS 跑 OpenClaw优势和坑分别在哪里1.1 OpenClaw 到底是什么简单说OpenClaw 是一个开源的 AI 智能体Agent框架它把我们平时用到的对话式 AI往前推了一步。普通聊天机器人是你问一句它答一句而 OpenClaw 是你把一个目标丢给它它自己去拆解任务、调用工具、操作浏览器、读取文件、运行代码最后把结果整理好交给你。它内部有几个核心模块在配合模型网关Gateway负责统一接入各种大模型Skills 体系让它可以按需调用各种能力消息渠道模块让它能接入 IM 平台而 CAU Computer 这类功能又让它能直接操作电脑。用户和它交互可以走终端命令也可以走 GUI 或消息机器人。适合谁来用两类人我觉得最合适。一类是日常重复劳动多的人比如整理文件、批量抓网页信息、定时汇总数据另一类是开发者想研究 Agent 的架构设计或者想给自己写一套私有自动化助手。1.2 macOS 上部署的直观感受和 Windows 相比macOS 部署 OpenClaw 有很明显的优势。首先是环境底子好系统自带 Python3 和 Git命令行生态是 Unix 那套很多依赖在 macOS 上可以直接编译不像 Windows 那样经常弹出 DLL 缺失或者编译环境不完整的问题。其次Apple SiliconM1 到 M4跑本地模型有天然优势。统一内存架构让 7B、14B 甚至更大参数量的量化模型都能在一台 MacBook 上跑起来配合 Ollama 直接把模型放在本机调用延迟很低也不用担心数据离开自己电脑。但坑也很真实。第一个坑是 macOS 对系统目录和权限管得特别严系统自带 Python 和 Homebrew Python 混用容易出现各种奇怪问题第二个坑是 TCC 权限机制终端想做屏幕截图、控制 Chrome、模拟鼠标键盘每一项都要去系统设置里单独授权漏一个功能就静默失败第三个坑是后台常驻服务和自启动macOS 想做到像 Linux systemd 那样方便得靠着 LaunchAgent 来配不熟悉的话能折腾一阵子。所以在 macOS 上部署 OpenClaw 完全可行但我建议你预留一个完整的下午别指望 10 分钟跑通。2. 开工前基础环境检查与依赖准备2.1 系统版本、Xcode 命令工具和包管理器无论是什么安装方式第一件事先把基础环境理清。我整理了一个快速检查顺序照着敲一遍就知道缺什么# 查看 macOS 版本 sw_vers # 查看是否已安装 Command Line Tools xcode-select -p # 查看 Python / Git / Node 版本 python3 --version git --version node -v # 查看是否已安装 Homebrew brew --version系统版本方面建议 macOS 12 及以上太老的系统有些 Python 新版本和依赖库已经不支持了。xcode-select --install如果没装 Command Line Tools会弹窗让你安装这个是很多编译型依赖的底层前提装不上后面 pip 装某些包会直接报错。Homebrew 是 macOS 生态里绕不开的包管理器虽然 OpenClaw 核心不依赖它但后面装 Python、装 Node、装 Ollama 都要用它来省事。没装的话去 brew.sh 按官方命令装就行。2.2 Python 版本选择不建议直接用系统自带 PythonmacOS 自带的 Python 在/usr/bin/python3这个版本是 Apple 自己编译的受系统保护直接用 pip 往里面装包会碰到externally-managed-environment这类限制权限和依赖都绑得很死。更麻烦的是它和命令行工具版本绑定一旦你为了某个库升级系统包很容易把系统环境搞乱。我的建议是用 Homebrew 单独装一个用户级的 Python干净隔离brew install python3.11装完以后python3 --version大概率指向的还是系统版本需要用which python3和brew info python3.11确认路径。很多踩坑帖最后都发现pip 装的包和运行时的 Python 根本不是一个环境。另外建议在安装 OpenClaw 之前就规划好虚拟环境OpenClaw 安装脚本一般会自己创建 venv但如果是用 git 源码方式启动手动建一个 venv 更稳。Node 和 npm 也建议装上因为部分面板和 Skills 依赖前端的构建brew install node一条命令就解决。2.3 模型服务准备在线 API 或本地 OllamaOpenClaw 本身不包含大模型所有对话、任务规划、工具调用都依赖外部大模型返回结果。所以安装之前要想清楚用哪条模型路线避免部署完以后卡在选择模型这一步。如果你偏好在线 OpenAI 兼容服务国内比较容易上手的是硅基流动这类平台。注册后拿到 API Key把对应的 Base URL 和模型名记录下来。选它主要因为它的接口格式和 OpenAI 一致OpenClaw 对接最顺畅而且有一些免费模型额度拿来调试 Agent 足够用了。如果你更看重隐私或者不想产生 API 费用就走本地 Ollama 路线brew install ollama ollama serve ollama pull qwen2.5:7bollama pull之后模型就存在本地了默认监听的地址是http://localhost:11434OpenClaw 配置好这个基础地址就能直接调用。我的个人建议是先用本地小模型把整个链路跑通不要一上来就接最强云端模型。Agent 调试是个反复试错的过程每试一次都要消耗 token本地模型虽然笨一点但免费等流程完全通了再切换高性能模型不迟。2.4 目录规划为什么放在用户目录而不是系统目录OpenClaw 运行时会写配置、日志、Skills、会话数据还会临时下载模型和浏览器组件这些都需要写入权限。如果安装在/opt或者/usr/local下的系统级目录经常要跟 sudo 打交道而用 sudo 跑 Agent 很容易把文件权限搞乱后面排查起来很痛苦。我这边用的是mkdir -p ~/openclaw # 存放项目源码 # 运行时的配置和数据默认在 ~/.openclaw放在~目录下当前用户天然有完整读写权限备份也方便直接把~/.openclaw打个包就行。如果机器上有多块硬盘想放到数据盘可以后面用软链接把~/.openclaw指过去不必一开始就纠结。3. 安装过程详解官方脚本、指定 git 方式安装、常见报错3.1 官方安装脚本的常规逻辑OpenClaw 官方 README 里通常会给一条curl ... | bash样式的命令安装脚本做的事情大致是检查系统 Python 版本、创建虚拟环境、安装 Python 依赖、生成默认配置、把可执行文件软链到某个 bin 目录。我的习惯是遇到这种管道执行远程脚本的安装方式先把脚本下载下来看一眼再执行尤其是第一次装不熟悉的东西总得知道脚本在你机器上到底做了什么# 先用 curl 保存脚本审查后再执行 curl -fsSL -o install-openclaw.sh https://example.com/install-openclaw.sh # 不要直接 bash先用编辑器打开看一遍 less install-openclaw.sh # 确认没问题再执行 bash install-openclaw.sh上面地址只是示例实际地址以官方仓库 README 为准。安装过程会输出很多日志看到Successfully installed这类输出基本就够了。3.2 指定 git 安装方式从 main 分支检出源码社区里经常有人提到OpenClaw 可通过安装脚本指定 git 安装方式从 GitHub 的 main 分支检出源码。为什么要用它因为这个项目迭代速度太快了打 tag 发布的 release 版本往往比 main 分支落后不少很多新能力只在 main 分支里。如果你希望第一时间用上新功能或者想自己改源码就要用 git 方式。具体操作上我当时的流程是cd ~/openclaw # 仓库地址以你看到的官方文档为准 git clone https://github.com/openclaw/openclaw.git . # 然后执行安装脚本并指定 git 安装方式 ./install.sh --git不同版本的安装脚本参数可能有差异最准确的做法是./install.sh --help看支持哪些参数。有些版本支持--branch main或者是通过环境变量控制不要死记硬背某一条命令。用 git 方式安装之后后续升级就变成cd ~/openclaw git pull origin main source .venv/bin/activate pip install -r requirements.txt这个方式对我来说最方便的是改代码不受限比如某个 Skill 的行为不符合预期直接在源码里搜关键词、改逻辑重启服务就生效。3.3 安装和首次启动时的三个典型报错先说 PATH 问题。装完之后如果你在终端输入openclaw提示command not found但安装日志明明显示成功大概率是安装脚本把可执行文件放进了~/.openclaw/bin而你的 shell 没把它加进 PATH。macOS 现在默认 zsh需要改~/.zshrcecho export PATH$HOME/.openclaw/bin:$PATH ~/.zshrc source ~/.zshrc然后是 Python 版本不满足要求。安装脚本对 Python 版本通常有硬性要求比如 3.10。系统自带 Python 版本太旧的时候最省事的就是brew install python3.12然后重新跑安装脚本让脚本直接基于新版本创建虚拟环境。不要尝试去升级系统 Python那是给自己挖坑。另一个容易出问题的点是首次启动时提示没有权限。遇到这类Permission denied先确认两点第一步检查~/.openclaw属主是不是当前用户如果之前用 sudo 安装过很可能属主变成了 rootchown -R $(whoami) ~/.openclaw能修复第二步检查 macOS 特有的 TCC 权限这个在后面的 Chrome 控制和 CAU Computer 部分会详细展开。4. 模型接入与 Gateway为什么需要统一网关4.1 Gateway 在 OpenClaw 里的位置OpenClaw 的架构里有一个模型网关层英文叫 Gateway所有对模型服务的请求都从这一层经过。它的职责用一个比喻很好理解如果 OpenClaw 是一个公司各业务线Skills、消息渠道、自动化任务就是不同部门公司不会让每个部门分别去对接供应商而是统一由一个采购部去谈采购这个采购部就是 Gateway。统一网关带来的好处是换模型不用改每个业务代码只改 Gateway 配置里的模型供应商和模型名就行。社区里常听到的gateway 改用模型、ccswitch 切换模型本质上都是在这个层面做文章。4.2 接入 OpenAI 兼容服务以硅基流动为例我接的第一个供应商就是硅基流动原因前面说过国内直连方便、接口格式标准。配置一般在~/.openclaw下可能是 JSON 或 YAML 格式以你当前版本生成的模板为准。这里给一个 YAML 结构示意model: gateway: providers: - id: siliconflow base_url: https://api.siliconflow.cn/v1 api_key: ${SILICONFLOW_API_KEY} models: - Qwen/Qwen2.5-7B-Instruct注意 API Key 不要直接硬编码在配置文件里用环境变量引用更安全。我的习惯是把密钥写进~/.zshrcexport 一个SILICONFLOW_API_KEYOpenClaw 读取配置时自动展开。配好之后可以通过类似openclaw gateway ping --provider siliconflow的命令验证连通性看到模型返回正常就说明接入成功。4.3 接入本地 Ollama 的注意点本地 Ollama 的配置和在线服务大同小异Base URL 就是http://localhost:11434/v1API Key 可以随便填一个占位符本地不走鉴权providers: - id: ollama base_url: http://localhost:11434/v1 api_key: ollama models: - qwen2.5:7b第一次跑的时候要给模型留足加载时间。如果你用的是 7B 模型macOS 上首次推理可能要等几十秒别一看到没响应就以为卡死了。有一个非常重要的经验要分享本地小模型做 Agent 的场景和做纯聊天场景完全不是一回事。Agent 需要模型输出严格的 JSON 来调用 Skills很多开源模型聊天很流畅但到了工具调用格式上就经常出错。测试下来7B 级别模型里指令微调做得好的那几款勉强能跑通但如果你想体验真正的 Agent 能力最终还是要切回在线大模型。4.4 多供应商回退、缓存与限流Gateway 还承担了稳定性的职责。我现在的配置里放了两个供应商主供应商是云端大模型备选是本地 Ollama当云端限流或超时的时候自动回退。配置里通常有fallback字段指向备用 provider 列表。缓存也值得单独说。开启响应缓存之后相同参数的请求会直接命中缓存不再重复调用模型这在我做批量网页总结的时候尤其明显。第一次跑 100 个 URL 花了 15 分钟第二次同样的 URL 列表因为缓存命中3 分钟就出结果了费用几乎为零。限流非常重要尤其是接了按量计费的线上模型以后。OpenClaw 内部的循环任务一旦写得不严谨可能在几秒内发出去几十个请求账单会很吓人。Gateway 的rate_limit配置里设置每分钟最大请求数宁可慢一点不要失控。5. Skills 技能体系从安装到编写自己的第一个 Skill5.1 Skill 的文件结构和加载原理OpenClaw 预置的只是个空壳真正让它干活的是 Skills。Skill 本质上是一组带描述脚本的集合文件结构大概是这样skill-name/ ├── SKILL.md ├── script.py └── requirements.txt核心是SKILL.md它告诉 OpenClaw 这个技能在什么场景下使用、需要哪些参数、怎么调用脚本。OpenClaw 在处理任务时会做语义匹配从所有已安装的 Skill 里挑出最相关的那几个加载。这不是把所有技能都塞给模型因为上下文窗口有限全塞进去既浪费 token 又降低准确性。5.2 安装现成 Skill 的正确姿势安装现成 Skill 有两种方式一种是用命令行openclaw skills search 网页截图 openclaw skills install skill名称另一种是手动把整个 Skill 目录丢到~/.openclaw/skills/下然后执行openclaw skills scan让系统重新扫描。如果你是刚开始用先装这几个基础 Skill 不会出错网页搜索与抓取、浏览器截图、定时提醒、文件批量重命名、JSON 格式化。这些技能覆盖了日常使用最频的场景而且社区维护得比较勤不容易出兼容问题。在本地 Ollama 环境下安装 Skill有个特殊注意点语义匹配依赖描述文本和用户意图之间的相似度本地模型的匹配能力不如云端强它会看到Skill 却不知道调用。解决方法是把 SKILL.md 的 description 写得非常直白把触发词直接放进去比如当用户要求 提取网页标题 时使用比获取 Web 页面的 Meta 信息要好用得多。5.3 手动编写第一个 Skill网页标题批量抓取这里以我写的一个最简单 Skill 举例目的是让你理解整个调用链路。创建~/.openclaw/skills/web-title/目录先写SKILL.md--- name: web-title description: 当用户需要获取一个或多个网页的标题时使用。可以从 URL 列表批量提取标题。 arguments: - name: urls type: list description: 网页地址列表例如 [https://example.com] --- 批量获取网页标题并返回 JSON 数组。然后是script.pyimport sys import json import requests from bs4 import BeautifulSoup def get_title(url: str) - str: resp requests.get(url, timeout10) resp.raise_for_status() soup BeautifulSoup(resp.text, html.parser) return soup.title.string.strip() if soup.title else if __name__ __main__: urls json.loads(sys.argv[1]) result [{url: u, title: get_title(u)} for u in urls] print(json.dumps(result, ensure_asciiFalse))把requests和beautifulsoup4写进requirements.txt安装的时候让系统自动补齐依赖这样一个 Skill 就算完成了。调试时直接用命令行跑任务来验证openclaw run 帮我获取这几个网页的标题https://example.com看输出是不是一个合法的 JSON如果是说明整个链路通畅如果模型返回了描述性文字而不是调用结果优先检查 Skill 描述写得够不够明确。6. macOS 专属实战Chrome 控制、CAU Computer 与消息渠道接入6.1 让 OpenClaw 控制本机 Chrome浏览器自动化是 Agent 最常用的能力之一社区里聊得最多的话题也是openclaw 容器 控制 chrome。控制 Chrome 通常有两条路一条是用 Playwright 等方式启动一个全新的浏览器实例另一条是通过 Chrome DevTools Protocol 连接你当前正在运行的 Chrome让它复用你的登录态和用户数据。如果你不介意用一个干净的浏览器环境Playwright 方案最简单pip install playwright playwright install chromium但很多场景下你希望它用你登录过的网页比如自动查询后台数据这时候用 CDP 方案更实际。先关掉所有 Chrome 窗口然后用调试模式启动/Applications/Google Chrome.app/Contents/MacOS/Google Chrome --remote-debugging-port9222然后在 OpenClaw 的浏览器配置里把 CDP 地址填成http://localhost:9222这样它就能连接到这个 Chrome 实例执行打开网页、点击、截图等操作。macOS 在这个环节最容易栽跟头的就是权限。终端在没有自动化权限的时候去控制 Chrome 会被系统直接拦截而且 OpenClaw 可能只提示一个笼统的错误。解决办法是到系统设置 - 隐私与安全性 - 自动化找到你的终端或 IDE把控制 Chrome 的开关打开。如果涉及页面截图还需要给终端开屏幕录制权限。6.2 CAU Computer 模块让 Agent 直接操作整台电脑CAU Computer 可以理解为 OpenClaw 的电脑操控员功能它让 Agent 不止能控制浏览器还能看屏幕、移动鼠标、点击按钮、输入文字、执行本地命令。一开始听到这个能力很兴奋但用了几次之后我意识到它也是一把双刃剑。打开这个功能之前建议先把这几个设置项捋清楚是否启用在配置中找到computer_use相关开关置为 trueTCC 权限在隐私与安全性里给终端/守护进程开辅助功能和屏幕录制缺一个都会导致操作静默失败操作黑白名单限制 Agent 只能打开哪些 App、访问哪些目录避免它在文件系统里乱逛超时和操作间隔给每一次鼠标键盘操作设置合理的间隔和整体超时防止脚本陷入死循环预演环境头几次测试建议在 macOS 虚拟机里跑等确认它不会乱点再放到主力机上。我自己的体会是CAU Computer 适合做高度重复、路径固定的操作比如自动把下载目录里的文件按日期归档、自动填写某个内部系统表单。但不要一上来就让它做复杂决策比如帮我整理整个桌面因为 Agent 对整理的理解和你完全可能不一样一旦权限放开后果很难预料。如果你在虚拟机里测试Parallels 或 UTM 都行注意虚拟机里同样存在屏幕录制权限问题有些虚拟机环境对 TCC 的支持并不完整可能会多花不少时间。6.3 消息渠道接入微信插件的风险和替代方案社区里很热门的是把 OpenClaw 接入微信实现直接用微信对话下发任务。但这也是踩坑最多的地方。最典型的两个问题一个是触发即时通讯平台的服务器端风控另一个是会话残留表现为插件看似登录成功发消息却石沉大海或者一段时间后自动掉线。我的建议是分清场景如果是给自己家里的小项目做玩具可以拿小号去试但要做好账号受限的心理准备如果是团队协作或者生产环境使用优先选择有官方开放 API 的平台比如飞书、钉钉的群机器人。这些平台对自动化更友好有完整的消息回调机制不会被当成异常行为。macOS 上如果只是本地测试消息通道还有一个更省事的办法OpenClaw 自带终端交互模式先用openclaw run 你的任务在终端直接对话消息渠道留到后面接入。这样能快速验证 Agent 工作是否正常不用一开始就和各种风控较劲。7. 版本升级、数据备份与日志排查7.1 可维护的升级路径OpenClaw 迭代快升级是常事。如果你当初是用 git 方式安装的升级流程就是标准的 git 更新cd ~/openclaw git pull origin main source .venv/bin/activate pip install -r requirements.txt openclaw restart如果装的是 release 包通常openclaw update一条命令搞定不放心的话重新跑一遍官方安装脚本也是可以的。升级之前一定要备份。OpenClaw 的所有状态都集中在~/.openclaw目录下配置、日志、会话、Skills 都在里面。一条命令的事cp -a ~/.openclaw ~/.openclaw.bak.$(date %Y%m%d)不要嫌麻烦我经历过一次升级后配置结构被自动迁移、旧字段被丢弃的情况没有备份的话几天调的配置全没了。7.2 日志里的常见提示怎么理解很多朋友在 macOS 上跑 OpenClaw 时会在日志里看到一句话gthread 一个 worker 空闲。如果你用的是基于 gunicorn 的服务这其实是正常信息意思是当前有空闲 worker 可以接收新请求。不要一看到空闲就觉得服务挂了要看整体日志上下文。如果确实觉得 Agent 响应很慢可以从三个方向排查第一步打开活动监视器或者htop看 CPU 是不是被某个 Python 进程占满第二步查网络请求是否卡在某个外部 API 上本地小模型和在线 API 都可能因为网络或排队导致超时第三步看是不是某个 Skill 脚本里写了同步阻塞的请求把 worker 线程卡死了。另外热词里提到macOS 系统数据占用过大如果你用 Docker 容器跑过 OpenClaw~/Library/Containers和 Docker 虚拟磁盘会非常膨胀。本地跑也一样Playwright 浏览器缓存、模型缓存、日志文件都是空间杀手。建议定期执行du -sh ~/.openclaw ~/Library/Caches 2/dev/null | sort -h看看哪个目录占得最凶再针对性清理。7.3 用 LaunchAgent 实现开机自启如果你希望 OpenClaw 常驻后台macOS 的典型做法是写一个 LaunchAgent plist 文件放到~/Library/LaunchAgents/?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/你的用户名/.openclaw/venv/bin/openclaw/string stringserve/string /array keyRunAtLoad/key true/ keyKeepAlive/key true/ /dict /plist然后执行launchctl load ~/Library/LaunchAgents/com.openclaw.agent.plist让配置生效。有一个容易忽略的细节LaunchAgent 方式启动的服务进程直接从 launchd 拉起来而不是从你的终端 App 拉起来的TCC 权限的归属和手工在终端里跑完全不同。我遇到过好几次命令行模式能控制 Chrome但变成 LaunchAgent 自启后就没有自动化权限了。解决办法是到自动化列表里给 openclaw 对应的可执行文件路径单独授权而不是只给终端授权。8. 周边玩法从 ESP32 到云服务器OpenClaw 还能这样扩展8.1 用 MicroPython 和 pycoclaw 让 ESP32 接入 Agent社区最近有个很有意思的方向有人用 MicroPython 和 pycoclaw 这个库在 ESP32 这种单片机上也连进了 OpenClaw。你可能会想ESP32 那点 Flash 和内存怎么可能跑 Agent 框架其实它并不是在单片机上跑整套推理而是把它当作一个硬件遥控器。思路很简单ESP32 通过 MicroPython 发送 HTTP 请求把按钮按下或者传感器触发的事件传给运行在 macOS 上的 OpenClaw 服务端OpenClaw 收到后执行既定任务再把结果通过串口或者小屏幕反馈回来。对 macOS 这边来说只需要保证 Agent 开启局域网服务同时加上基本的身份认证别让同一网络里的陌生人也能触发你的任务就行。这类玩法属于典型的周末项目工程意义不一定大但对理解 Agent 的接口分层很有帮助。8.2 云服务器和 macOS 本机怎么分工有些朋友不想让 Mac 一直开机选择把 OpenClaw 部署到云服务器上Mac 只当日常管理终端。这个思路很合理云服务器的优势是公网可达、稳定运行、不占本地资源。但要注意只要服务暴露在公网上认证和加密就不能省至少在网关上配好访问令牌或者用 SSH 隧道等方式做安全连接。就我个人的经验来说学习和调试阶段还是先在 macOS 本机跑通。本机跑的好处是日志直接看、文件直接改、权限问题暴露得及时一旦部署到服务器同样的调试成本会高一个量级。8.3 为什么不要把它当成全能员工OpenClaw 能做的事情确实不少但它依然是一个半自动系统需要你明确地拆解任务、审查输出、设置边界。最后想分享一条建议在让 Agent 做任何批量操作之前先想清楚它如果做错了会有什么影响。命令白名单、成本预算、数据备份这几件事值得在安装完成后的第一周就配置好而不是等出了问题再补。我在 macOS 上把 OpenClaw 跑通之后最深的感受是这类工具真正拉开差距的地方不是模型多聪明而是你对它的调教有多细致。环境配好只是第一步后续的 Skills 维护、模型调优、权限规划才是每天都要花点心思的长期工作。希望这篇记录能让你少走一点弯路少踩几个 macOS 特有的坑。