OpenClaw macOS 完整安装与本地模型配置教程（实战版）

OpenClaw macOS 完整安装与本地模型配置教程（实战版）

说实话这玩意在 Mac 上装起来真的比 Windows 顺太多了，一条 curl 命令直接梭，Homebrew、Node 都给你检测好，基本不用手动处理什么。这篇就是我边装边记录的实战文档，包含真实日志和所有踩坑点，用过的就算了。

作者：吴佳浩

撰稿时间：2026-3-8

测试模型：qwen3.5:9b（ollama 量化版，Mac 内存小就跑小模型，你们随意）

OpenClaw（前身为 ClawdBot / Moltbot）是一款开源的本地自托管 AI 个人智能助手平台，支持接入 Claude、GPT、Qwen、DeepSeek、Ollama 本地模型等，可实现文件操作、终端执行、浏览器控制、定时任务等全场景自动化。

本文基于 **MacBook Pro M1Pro+ macOS Sequoia（15.3.2 ）真实环境实战整理，包含所有踩坑记录与解决方案。

目录

1. 系统要求
2. 整体流程概览
3. Step 1：安装 Node.js（≥ 22）
4. Step 2：安装 OpenClaw（一键脚本）
5. Step 3：运行初始化向导（完整实战）
6. Step 4：安装 Ollama（本地模型运行环境）
7. Step 5：下载本地模型
8. Step 6：启动 Gateway 与打开 Dashboard
9. Step 7：处理 Skills 安装失败（Xcode 版本问题）
10. 常用命令速查
11. 常见问题 FAQ（实战踩坑）
12. 模型推荐选型（Apple Silicon）
13. openclaw.json 完整配置参考

1. 系统要求

注意：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（推荐）

# 安装 nvmcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh |bash# 重启终端或 source 配置文件source ~/.zshrc # 安装并使用 Node 24（≥ 22 即可） nvm install24 nvm use 24

实战日志：

wujiahao@wujiahaoMacBook-Pro ~ % nvm use 24 Now using node v24.7.0 (npm v11.5.1) 

方法二：Homebrew

brew installnode

验证

node--version# v24.7.0npm--version# 11.5.1

4. Step 2：安装 OpenClaw（一键脚本）

macOS 只需一条命令，安装脚本会自动检测 Homebrew、Node.js 版本并完成安装：

curl-fsSL https://openclaw.ai/install.sh |bash

真实安装日志

wujiahao@wujiahaoMacBook-Pro ~ % curl -fsSL https://openclaw.ai/install.sh | bash 🦞 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）。以下是完整的每一步操作说明。

向导每一步怎么选

openclaw onboard

安全警告
→ 输入 Yes 继续

Onboarding mode
→ QuickStart

Config handling（如有旧配置）
→ Use existing values

Model/auth provider
→ Custom Provider
不要选内置 Ollama 选项

API Base URL
→ http://127.0.0.1:11434/v1

How to provide API key
→ Paste API key now

API Key
→ ollama（随便填，本地不验证）

Endpoint compatibility
→ OpenAI-compatible

Model ID
→ 填你已 pull 的模型
如 qwen3.5:9b

✅ Verification successful

Endpoint ID
→ 直接回车用默认

Model alias
→ 随意，如 qwen3.5-9b

Select channel
→ Skip for now

Configure skills now?
→ Yes

Install missing skill dependencies
→ 勾选需要的（见下表）

API Keys
→ 全部 No（本地不需要）

Enable hooks
→ 勾选 bootstrap-extra-files + command-logger

How to hatch
→ Open the Web UI

✅ 向导完成，浏览器自动打开

向导关键节点实战日志

安全警告确认（必须选 Yes 才能继续）：

◇ 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:9b ◇ Verification successful. ◇ Endpoint ID │ custom-127-0-0-1-11434 ◇ Model alias (optional) │ qwen3.5-9b Configured custom provider: custom-127-0-0-1-11434/qwen3.5:9b 

跳过 Channel 配置：

◇ Select channel (QuickStart) │ Skip for now 

Skills 推荐勾选清单

实战说明：如果你的 Xcode 版本低于 16.4，大量依赖 Homebrew 编译的 Skills 会安装失败，这是正常现象，见 Step 7 处理方案。

API Key 全部跳过

向导会依次询问以下 Key，全部选 No：

◇ 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（本地模型运行环境）

方法一：官网下载（推荐）

1. 访问 https://ollama.com
2. 点击 Download for Mac，下载 Ollama.dmg
3. 拖入应用程序，启动后菜单栏出现 🦙 图标

方法二：Homebrew

brew install ollama ollama serve # 前台运行，或用 brew services start ollama 后台运行

验证

ollama --version# ollama version 0.x.x ✓curl http://localhost:11434 # Ollama is running ✓

7. Step 5：下载本地模型

按统一内存选择模型（Apple Silicon）

8 GB

16 GB

24 GB

32 GB

64 GB+

选择模型

统一内存大小？

qwen2.5:3b
~2GB
入门可用

qwen2.5:7b / qwen3.5:9b
~5-6GB
均衡推荐 ⭐

qwen2.5:14b
~10GB
效果更好

qwen2.5:32b
~20GB
旗舰体验

deepseek-r1:32b
~20GB
强推理首选

下载命令

# 本文测试使用（16GB 内存推荐） ollama pull qwen3.5:9b # 其他选项 ollama pull qwen2.5:3b # 8GB 内存入门 ollama pull qwen2.5:7b # 通用均衡 ollama pull qwen2.5:14b # 24GB 内存 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://127.0.0.1:18789 [browser/server] Browser control listening on http://127.0.0.1:18791/ [hooks] loaded 4 internal hook handlers 

打开 Dashboard（三种方式）

方式一：命令自动打开（推荐，自动带 token）

openclaw dashboard 

方式二：向导完成时的带 token 链接

向导结束时终端会展示：

Dashboard link (with token): http://127.0.0.1:18789/#token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Opened in your browser. Keep that tab to control OpenClaw. 

方式三：查看当前 token 并手动拼 URL

# 查看 token 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

brew not found

其他依赖缺失

Skills 安装失败

失败原因？

更新 Xcode 到 16.4+
（App Store 搜索 Xcode）
或删除旧版本

安装 Homebrew
/bin/bash -c $(curl -fsSL…)

openclaw doctor
查看具体缺失项

重新安装对应 Skill
openclaw skills install

✅ Skill 可用

已成功安装的 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>。

健康检查

openclaw doctor 

10. 常用命令速查

OpenClaw
常用命令

服务管理

openclaw gateway

openclaw gateway install

openclaw gateway status

launchctl load/unload

配置管理

openclaw onboard

openclaw config get

openclaw config set

openclaw doctor

模型管理

ollama list

ollama pull

ollama create

ollama ps

面板访问

openclaw dashboard

Hooks管理

openclaw hooks list

openclaw hooks enable

openclaw hooks disable

11. 常见问题 FAQ（实战踩坑）

Q1：安装脚本报 Running doctor failed

实战日志：

✗ Running doctor failed — re-run with --verbose for details 

原因：已有旧版本配置文件，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:// to a non-loopback address. Both credentials and chat data would be exposed. Fix: Use wss:// for remote gateway URLs. 

原因：旧配置文件中残留了 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。

解决：手动触发向导：

openclaw onboard 

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）

完整选型矩阵

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 安装差异速查

总结

完成以上步骤后，你拥有了：

• 完全本地的 AI 助手，数据不出本机
• 完全免费，无需任何 API 费用
• 断网可用，不依赖任何外部服务
• 开机自启，LaunchAgent 自动管理，无感运行

🦞 OpenClaw
本地 AI 助手

文件管理

代码生成

网页控制

定时任务

🍎 Apple 生态
Notes / Things / Bear

文档分析

下一步探索：

• 访问 ClawHub 安装更多社区 Skills
• 配置 Telegram Bot 实现手机端随时对话
• 更新 Xcode 后重装更多 macOS 专属 Skills
• 运行 openclaw security audit --deep 加固安全配置

文档版本：2026年3月（基于 吴佳浩 OpenClaw 2026.3.2 实战整理） 官方文档：https://openclaw.ai