跳到主要内容 OpenClaw macOS 安装与本地模型配置实战教程 | 极客日志
JavaScript Node.js AI
OpenClaw macOS 安装与本地模型配置实战教程 详细记录了在 macOS 系统下安装 OpenClaw 开源 AI 助手平台的全过程。内容包括 Node.js 环境配置、使用一键脚本安装应用、通过初始化向导接入 Ollama 本地模型。针对 macOS 特有的 Xcode 版本导致 Skills 安装失败的问题提供了排查方案，并说明了 LaunchAgent 开机自启机制。最后整理了常用命令速查与健康检查方法，帮助用户实现完全本地化、免费且断网可用的 AI 助手部署。
独立开发者 发布于 2026/3/28 更新于 2026/4/17 OpenClaw macOS 安装与本地模型配置实战教程
OpenClaw （前身为 ClawdBot / Moltbot）是一款开源的本地自托管 AI 个人智能助手平台，支持接入 Claude、GPT、Qwen、DeepSeek、Ollama 本地模型等，可实现文件操作、终端执行、浏览器控制、定时任务等全场景自动化。
本文基于 MacBook Pro M1Pro + macOS Sequoia（15.3.2）真实环境实战整理，包含所有踩坑记录与解决方案。
1. 系统要求
项目 最低要求 推荐配置 操作系统 macOS 12 Monterey macOS 14 Sonoma+ Node.js ≥ 22.0 最新 LTS 内存 8 GB RAM 16 GB RAM+（统一内存兼做显存） 芯片 Intel / Apple Silicon Apple Silicon（M 系列推荐） 磁盘空间 10 GB 可用 50 GB+ Homebrew 需要安装 — 网络 安装时需联网 —
注意 ：Apple Silicon Mac 的统一内存（Unified Memory）同时作为 GPU 显存使用，跑本地模型效率很高，8B 以下模型体验极佳。
2. 整体流程概览
🍎 macOS 环境
安装 Node.js ≥ 22
nvm use 24
一键安装 OpenClaw：curl -fsSL openclaw.ai/install.sh | bash
运行初始化向导：自动触发 openclaw onboard
选择 Custom Provider：接入 Ollama 本地模型
安装 Ollama：下载目标模型
LaunchAgent 自动启动：无需手动 gateway
openclaw dashboard：打开 Web UI
✅ 本地 AI 助手就绪
3. Step 1：安装 Node.js（≥ 22）
macOS 推荐使用 nvm （Node Version Manager）管理 Node 版本，方便随时切换。
方法一：nvm（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.zshrc
nvm install 24
nvm use 24
实战日志：
wujiahao@wujiahaoMacBook -Pro ~ % nvm use 24
Now using node v24.7 .微信扫一扫，关注极客日志 微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
相关免费在线工具 RSA密钥对生成器 生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
Mermaid 预览与可视化编辑 基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
Keycode 信息 查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online
Escape 与 Native 编解码 JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online
JavaScript / HTML 格式化 使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online
JavaScript 压缩与混淆 Terser 压缩、变量名混淆，或 javascript-obfuscator 高强度混淆（体积会增大）。 在线工具，JavaScript 压缩与混淆在线工具，online
0
v11.5
1
方法二：Homebrew
验证 node --version
npm --version
4. Step 2：安装 OpenClaw（一键脚本） macOS 只需一条命令，安装脚本会自动检测 Homebrew、Node.js 版本并完成安装：
curl -fsSL https://openclaw.ai/install.sh | bash
真实安装日志 wujiahao@wujiahaoMacBook - Pro ~ % curl - fsSL https:
🦞 OpenClaw Installer
I don't just autocomplete—I auto- commit (emotionally), then ask you to review (logically).
✓ Detected : macos
Install plan OS : macos
Install method: npm
Requested version: latest
[1 / 3 ] Preparing environment
✓ Homebrew already installed
✓ Node .js v24.7.0 found
· Active Node .js: v24.7.0 (/Users/ wujiahao/.nvm/ versions/node/ v24.7.0 /bin/ node)
· Active npm: 11.5 .1 (/Users/ wujiahao/.nvm/ versions/node/ v24.7.0 /bin/ npm)
[2 / 3 ] Installing OpenClaw
✓ Git already installed
· Installing OpenClaw v2026.3.2
✓ OpenClaw npm package installed
✓ OpenClaw installed
[3 / 3 ] Finalizing setup
🦞 OpenClaw installed successfully (2026.3 .2 )!
cracks claws
Alright , what are we building?
实战说明 ：安装完成后脚本会自动检测是否存在旧配置文件，如有会跑一次 doctor 迁移设置，随后直接进入 onboarding 向导。
5. Step 3：运行初始化向导（完整实战） 安装脚本结束后会自动进入 初始化向导（等同于手动运行 openclaw onboard）。以下是完整的每一步操作说明。
向导每一步怎么选
安全警告 → 输入 Yes 继续Onboarding mode → QuickStartConfig handling（如有旧配置） → Use existing valuesModel/auth provider → Custom Provider（不要选内置 Ollama 选项）API Base URL → http://127.0.0.1:11434/v1 How to provide API key → Paste API key nowAPI Key → ollama（随便填，本地不验证）Endpoint compatibility → OpenAI-compatibleModel ID → 填你已 pull 的模型（如 qwen3.5:9b）✅ Verification successful
Endpoint ID → 直接回车用默认Model alias → 随意，如 qwen3.5-9bSelect channel → Skip for nowConfigure skills now? → YesInstall missing skill dependencies → 勾选需要的（见下表）API Keys → 全部 No（本地不需要）Enable hooks → 勾选 bootstrap-extra-files + command-loggerHow to hatch → Open the Web UI
向导关键节点实战日志 ◇ I understand this is personal-by -default and shared/multi-user use requires lock -down. Continue? │ Yes
选择 Custom Provider （不要选内置 Ollama，行为不一致）：
◇ Model/auth provider │ Custom Provider
◇ API Base URL │ http://127.0 .0.1 :11434 /v1
◇ API Key (leave blank if not required) │ ollama
◇ Endpoint compatibility │ OpenAI-compatible
◇ Model ID │ qwen3.5 :9 b
◇ Verification successful.
◇ Endpoint ID │ custom -127 -0 -0 -1 -11434
◇ Model alias (optional ) │ qwen3.5 -9 b
Configured custom provider: custom -127 -0 -0 -1 -11434 /qwen3.5 :9 b
◇ Select channel (QuickStart) │ Skip for now
Skills 推荐勾选清单 Skill macOS 可用 说明 clawhub✅ 技能商店，必装 nano-pdf✅ PDF 阅读分析 github✅ GitHub 操作 bear-notes✅ Bear 笔记集成 things-mac✅ Things 3 任务管理 openai-whisper✅ 本地语音识别 apple-notes⚠️ Xcode 过旧会失败 Apple 备忘录 camsnap⚠️ Xcode 过旧会失败 摄像头截图 summarize⚠️ Xcode 过旧会失败 网页/文档总结
实战说明 ：如果你的 Xcode 版本低于 16.4，大量依赖 Homebrew 编译的 Skills 会安装失败，这是正常现象，见 Step 7 处理方案。
API Key 全部跳过 ◇ Set GOOGLE_PLACES_API_KEY for goplaces? → No
◇ Set GEMINI_API_KEY for nano-banana-pro? → No
◇ Set NOTION_API_KEY for notion? → No
◇ Set OPENAI_API_KEY for openai-image-gen? → No
◇ Set OPENAI_API_KEY for openai-whisper-api? → No
◇ Set ELEVENLABS_API_KEY for sag? → No
Hooks 启用 ◇ Enable hooks? │ 📎 bootstrap-extra-files, 📝 command-logger
◇ Hooks Configured │ Enabled 2 hooks: bootstrap-extra-files, command-logger
macOS 专属：LaunchAgent 自动安装 macOS 版会自动将 Gateway 注册为 LaunchAgent ，开机自启，无需手动每次运行 openclaw gateway：
◒ Installing Gateway service…. Installed LaunchAgent : /Users/wujiahao /Library/ LaunchAgents /ai.openclaw.gateway.plist
Logs : /Users/wujiahao /.openclaw/logs /gateway.log
◇ Gateway service installed.
Windows 与 macOS 区别 ：Windows 需要手动运行 openclaw gateway，macOS 则由 LaunchAgent 自动管理，重启后不需要任何操作。
6. Step 4：安装 Ollama（本地模型运行环境）
方法一：官网下载（推荐）
方法二：Homebrew brew install ollama
ollama serve
验证 ollama --version
✓ curl http://localhost:11434
7. Step 5：下载本地模型
按统一内存选择模型（Apple Silicon） 统一内存大小 选择模型 8 GB qwen2.5:3b (~2GB) 入门可用 16 GB qwen2.5:7b / qwen3.5:9b (~5-6GB) 均衡推荐 ⭐ 24 GB qwen2.5:14b (~10GB) 效果更好 32 GB qwen2.5:32b (~20GB) 旗舰体验 64 GB+ deepseek-r1:32b (~20GB) 强推理首选
下载命令
ollama pull qwen3.5:9b
ollama pull qwen2.5:3b
ollama pull qwen2.5:7b
ollama pull qwen2.5:14b
ollama pull deepseek-r1:32b
ollama pull qwen2.5-coder:14b
ollama list
8. Step 6：启动 Gateway 与打开 Dashboard
macOS 的优势：LaunchAgent 自动管理 macOS 安装完成后 Gateway 已作为 LaunchAgent 注册，通常不需要手动启动 。如需手动操作：
launchctl list | grep openclaw
launchctl load ~/Library/LaunchAgents/ai.openclaw.gateway.plist
tail -f ~/.openclaw/logs/gateway.log
正常运行的日志特征 [gateway ] agent model: custom-127 -0 -0 -1 -11434 /qwen3.5 :9b
[gateway ] listening on ws:
[browser/server ] Browser control listening on http:
[hooks ] loaded 4 internal hook handlers
打开 Dashboard（三种方式） Dashboard link (with token): http:// 127.0 .0 .1 :18789 /
Opened in your browser. Keep that tab to control OpenClaw.
openclaw config get gateway.auth.token
open "http://127.0.0.1:18789/#token=$(openclaw config get gateway.auth.token) "
关于 Token 认证 OpenClaw 默认开启 token 认证，防止局域网内其他设备控制你的电脑（它有文件读写、终端执行等高权限）。本机自用可以关闭：
openclaw config set gateway.auth.mode none
关闭后直接访问 http://127.0.0.1:18789 无需 token。
9. Step 7：处理 Skills 安装失败（Xcode 版本问题） macOS 上 Skills 安装失败的主要原因 是 Xcode 版本过旧，而非像 Windows 那样缺少 brew。
实战日志（典型失败场景） ◇ Install failed: apple-notes (exit 1 ) — Error : Your Xcode (14.3 .1 ) at /Applications/Xcode.app is too outdated. Please update to Xcode 16.4 (or delete it). Xcode can be updated from the App Store.
◇ Install failed: camsnap (exit 1 ) — Error : Your Xcode (14.3 .1 ) at /Applications/Xcode.app is too outdated.
◇ Install failed: summarize (exit 1 ) — Error : Your Xcode (14.3 .1 ) at /Applications/Xcode.app is too outdated.
问题原因与解决方案 失败原因 解决方案 Xcode too outdated 更新 Xcode 到 16.4+（App Store 搜索 Xcode）或删除旧版本 brew not found 安装 Homebrew /bin/bash -c $(curl -fsSL...) 其他依赖缺失 openclaw doctor 查看具体缺失项Skills 安装失败 重新安装对应 Skill openclaw skills install
已成功安装的 Skills（Xcode 14.3.1 环境下） 实测以下 Skills 无需更新 Xcode 即可安装成功：
✓ 1password ✓ bear-notes ✓ blogwatcher ✓ blucli ✓ clawhub ✓ eightctl ✓ github ✓ himalaya ✓ mcporter ✓ model-usage ✓ nano-banana-pro ✓ nano-pdf ✓ openai-whisper ✓ oracle ✓ sonoscli ✓ things-mac ✓ xurl
需要更新 Xcode 才能安装的 Skills ✗ apple-notes ✗ apple-reminders ✗ camsnap ✗ gifgrep ✗ gog ✗ goplaces ✗ imsg ✗ obsidian ✗ openhue ✗ ordercli ✗ peekaboo ✗ sag ✗ songsee ✗ summarize ✗ wacli
实战建议 ：Skills 安装失败不影响主程序正常聊天 。如果不需要这些特定功能，直接跳过即可。需要的话去 App Store 把 Xcode 更新到 16.4+ 再重新运行 openclaw skills install <n>。
健康检查
10. 常用命令速查 命令 说明 openclaw gateway前台启动 Gateway（macOS 通常不需要） openclaw dashboard自动用 token 打开浏览器面板 openclaw onboard重新运行初始化向导 openclaw doctor健康检查与依赖检测 openclaw config get查看当前配置 openclaw config set x y修改配置项 openclaw hooks list查看已安装 hooks ollama list查看已下载模型 ollama ps查看模型运行状态 tail -f ~/.openclaw/logs/gateway.log实时查看 Gateway 日志
11. 常见问题 FAQ（实战踩坑）
Q1：安装脚本报 Running doctor failed ✗ Running doctor failed — re- run with
原因 ：已有旧版本配置文件，doctor 检测到不兼容配置。
解决 ：这个报错不影响后续流程，onboarding 向导会继续。如需详细信息运行 openclaw doctor --verbose。
Q2：Doctor 报 SECURITY ERROR: Gateway URL uses plaintext ws:// Error : SECURITY ERROR : Gateway URL "ws://openclaw.local:18789" uses plaintext ws :
原因 ：旧配置文件中残留了 gateway.mode: remote + 非本地地址的配置。
openclaw config set gateway.mode local
openclaw config set gateway.bind loopback
或直接用 openclaw onboard 重新配置一次，向导时选 'Use existing values' 让其自动修复。
Q3：向导完成后提示 Config already present; skipping onboarding 原因 ：已有 ~/.openclaw/openclaw.json，安装脚本检测到后跳过了 onboarding。
Q4：浏览器打开 localhost:18789 一直报 token_missing 原因 ：OpenClaw 默认开启 token 认证，不能直接访问裸地址。
解决 ：用 openclaw dashboard 命令打开（自动带 token），或查看 token 手动拼 URL：
openclaw config get gateway.auth.token
Q5：日志一直刷 Telegram / WhatsApp 报错 原因 ：向导配置了相关 channel 但未完成认证。
openclaw config set channels.telegram.enabled false
Q6：Skills 全部报 Your Xcode is too outdated 原因 ：macOS 特有问题，Xcode 14.x 无法编译新版 Homebrew 公式。
解决 ：去 App Store 更新 Xcode 到 16.4+，或忽略（不影响主功能）。
Q7：openclaw gateway 和 LaunchAgent 冲突，端口被占用 原因 ：LaunchAgent 已经启动了 Gateway，手动再运行 openclaw gateway 导致端口冲突。
解决 ：macOS 上无需手动运行 openclaw gateway，LaunchAgent 已经管好了。检查状态：
launchctl list | grep openclaw
12. 模型推荐选型（Apple Silicon）
完整选型矩阵 模型 统一内存需求 速度（M 系列） 拉取命令 qwen2.5:3b 2 GB 极快 ollama pull qwen2.5:3bqwen2.5:7b 5 GB 很快 ollama pull qwen2.5:7bqwen3.5:9b 6 GB 很快 ollama pull qwen3.5:9bqwen2.5:14b 10 GB 快 ollama pull qwen2.5:14bqwen2.5:32b 20 GB 中 ollama pull qwen2.5:32bdeepseek-r1:32b 20 GB 中 ollama pull deepseek-r1:32b
13. openclaw.json 完整配置参考 以下为经过实战验证的完整配置文件（适配 qwen3.5:9b + 本地 Ollama，macOS 环境）：
{
"models" : {
"mode" : "merge" ,
"providers" : {
"custom-127-0-0-1-11434" : {
"baseUrl" : "http://127.0.0.1:11434/v1" ,
"apiKey" : "ollama" ,
"api" : "openai-completions" ,
"models" : [
{
"id" : "qwen3.5:9b" ,
"name" : "Qwen3.5 9B (Local)" ,
"reasoning" : false ,
"input" : [ "text" ] ,
"cost" : { "input" : 0 , "output" : 0 , "cacheRead" : 0 , "cacheWrite" : 0 } ,
"contextWindow" : 32768 ,
"maxTokens" : 8192
}
]
}
}
} ,
"agents" : {
"defaults" : {
"model" : { "primary" : "custom-127-0-0-1-11434/qwen3.5:9b" } ,
"workspace" : "/Users/{用户名}/.openclaw/workspace" ,
"compaction" : { "mode" : "safeguard" } ,
"maxConcurrent" : 4 ,
"subagents" : { "maxConcurrent" : 8 }
}
} ,
"session" : { "dmScope" : "per-channel-peer" } ,
"hooks" : {
"internal" : {
"enabled" : true ,
"entries" : {
"bootstrap-extra-files" : { "enabled" : true } ,
"command-logger" : { "enabled" : true }
}
}
} ,
"channels" : { "telegram" : { "enabled" : false } } ,
"gateway" : {
"port" : 18789 ,
"mode" : "local" ,
"bind" : "loopback" ,
"auth" : { "mode" : "token" }
} ,
"skills" : { "install" : { "nodeManager" : "npm" } }
}
Windows vs macOS 安装差异速查 对比项 Windows macOS 安装命令 `irm openclaw.ai/install.ps1 iex` 包管理器 scoop / winget Homebrew（预装检测） Gateway 启动 需手动运行 openclaw gateway LaunchAgent 自动管理 Skills 主要失败原因 brew not installedXcode 版本过旧 Skills 修复方案 安装 scoop 替代 更新 Xcode 到 16.4+ 上下文窗口问题 ⚠️ 必须手动创建 32k 版本模型 ✅ 无需处理，Ollama 自动适配 配置文件路径 %USERPROFILE%\.openclaw\openclaw.json~/.openclaw/openclaw.json日志路径 %USERPROFILE%\.openclaw\logs\~/.openclaw/logs/gateway.log
总结
完全本地 的 AI 助手，数据不出本机完全免费 ，无需任何 API 费用断网可用 ，不依赖任何外部服务开机自启 ，LaunchAgent 自动管理，无感运行
配置 Telegram Bot 实现手机端随时对话
更新 Xcode 后重装更多 macOS 专属 Skills
运行 openclaw security audit --deep 加固安全配置
