通联好老板
78.94M · 2026-03-23
说实话这玩意在 Mac 上装起来真的比 Windows 顺太多了，一条 curl 命令直接梭，Homebrew、Node 都给你检测好，基本不用手动处理什么。这篇就是我边装边记录的实战文档，包含真实日志和所有踩坑点，用过的就算了。
作者：吴佳浩
撰稿时间：2026-3-8
测试模型：qwen3.5:9b（ollama 量化版，Mac 内存小就跑小模型，你们随意）
| 项目 | 最低要求 | 推荐配置 |
|---|---|---|
| 操作系统 | 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 | 需要安装 | — |
| 网络 | 安装时需联网 | — |
flowchart TD
A[" macOS 环境"] --> B["安装 Node.js ≥ 22<br/>nvm use 24"]
B --> C["一键安装 OpenClaw<br/>curl -fsSL openclaw.ai/install.sh | bash"]
C --> D["运行初始化向导<br/>自动触发 openclaw onboard"]
D --> E["选择 Custom Provider<br/>接入 Ollama 本地模型"]
E --> F["安装 Ollama<br/>下载目标模型"]
F --> G["LaunchAgent 自动启动<br/>无需手动 gateway"]
G --> H["openclaw dashboard<br/>打开 Web UI"]
H --> I[" 本地 AI 助手就绪"]
style A fill:#1a1a2e,color:#fff
style I fill:#00aa55,color:#fff
macOS 推荐使用 nvm（Node Version Manager）管理 Node 版本，方便随时切换。
# 安装 nvm
curl -o- | bash
# 重启终端或 source 配置文件
source ~/.zshrc
# 安装并使用 Node 24（≥ 22 即可）
nvm install 24
nvm use 24
实战日志：
wujiahao@wujiahaoMacBook-Pro ~ % nvm use 24
Now using node v24.7.0 (npm v11.5.1)
brew install node
node --version # v24.7.0
npm --version # 11.5.1
macOS 只需一条命令，安装脚本会自动检测 Homebrew、Node.js 版本并完成安装：
curl -fsSL | bash
wujiahao@wujiahaoMacBook-Pro ~ % curl -fsSL | 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?
安装脚本结束后会自动进入初始化向导（等同于手动运行 openclaw onboard）。以下是完整的每一步操作说明。
flowchart TD
A["openclaw onboard"] --> B["安全警告<br/>→ 输入 Yes 继续"]
B --> C["Onboarding mode<br/>→ QuickStart"]
C --> D["Config handling（如有旧配置）<br/>→ Use existing values"]
D --> E["Model/auth provider<br/>→ Custom Provider<br/> 不要选内置 Ollama 选项"]
E --> F["API Base URL<br/>→ 1"]
F --> G["How to provide API key<br/>→ Paste API key now"]
G --> H["API Key<br/>→ ollama（随便填，本地不验证）"]
H --> I["Endpoint compatibility<br/>→ OpenAI-compatible"]
I --> J["Model ID<br/>→ 填你已 pull 的模型<br/>如 qwen3.5:9b"]
J --> K[" Verification successful"]
K --> L["Endpoint ID<br/>→ 直接回车用默认"]
L --> M["Model alias<br/>→ 随意，如 qwen3.5-9b"]
M --> N["Select channel<br/>→ Skip for now"]
N --> O["Configure skills now?<br/>→ Yes"]
O --> P["Install missing skill dependencies<br/>→ 勾选需要的（见下表）"]
P --> Q["API Keys<br/>→ 全部 No（本地不需要）"]
Q --> R["Enable hooks<br/>→ 勾选 bootstrap-extra-files + command-logger"]
R --> S["How to hatch<br/>→ Open the Web UI"]
S --> T[" 向导完成，浏览器自动打开"]
style K fill:#00aa55,color:#fff
style T fill:#00aa55,color:#fff
style E fill:#c62828,color:#fff
安全警告确认（必须选 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
│
◇ 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
| 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 过旧会失败 | 网页/文档总结 |
向导会依次询问以下 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
◇ Enable hooks?
│ bootstrap-extra-files, command-logger
◇ Hooks Configured
│ Enabled 2 hooks: bootstrap-extra-files, command-logger
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.
Ollama.dmgbrew install ollama
ollama serve # 前台运行，或用 brew services start ollama 后台运行
ollama --version
# ollama version 0.x.x
curl
# Ollama is running
graph TD
A["选择模型"] --> B{"统一内存大小？"}
B -- "8 GB" --> C["qwen2.5:3b<br/>~2GB<br/>入门可用"]
B -- "16 GB" --> D["qwen2.5:7b / qwen3.5:9b<br/>~5-6GB<br/>均衡推荐 ⭐"]
B -- "24 GB" --> E["qwen2.5:14b<br/>~10GB<br/>效果更好"]
B -- "32 GB" --> F["qwen2.5:32b<br/>~20GB<br/>旗舰体验"]
B -- "64 GB+" --> G["deepseek-r1:32b<br/>~20GB<br/>强推理首选"]
style D fill:#2d6a4f,color:#fff
style G fill:#7b2d8b,color:#fff
# 本文测试使用（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
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
[hooks] loaded 4 internal hook handlers
方式一：命令自动打开（推荐，自动带 token）
openclaw dashboard
方式二：向导完成时的带 token 链接
向导结束时终端会展示：
Dashboard link (with token):
#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)"
OpenClaw 默认开启 token 认证，防止局域网内其他设备控制你的电脑（它有文件读写、终端执行等高权限）。本机自用可以关闭：
openclaw config set gateway.auth.mode none
关闭后直接访问 无需 token。
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.
graph TD
A["Skills 安装失败"] --> B{"失败原因？"}
B -- "Xcode too outdated" --> C["更新 Xcode 到 16.4+<br/>（App Store 搜索 Xcode）<br/>或删除旧版本"]
B -- "brew not found" --> D["安装 Homebrew<br/>/bin/bash -c $(curl -fsSL…)"]
B -- "其他依赖缺失" --> E["openclaw doctor<br/>查看具体缺失项"]
C --> F["重新安装对应 Skill<br/>openclaw skills install <n>"]
D --> F
E --> F
F --> G[" Skill 可用"]
实测以下 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
apple-notes apple-reminders camsnap
gifgrep gog goplaces
imsg obsidian openhue
ordercli peekaboo sag
songsee summarize wacli
openclaw doctor
mindmap
root((OpenClaw<br/>常用命令))
服务管理
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
| 命令 | 说明 |
|---|---|
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 日志 |
Running doctor failed实战日志：
Running doctor failed — re-run with --verbose for details
原因：已有旧版本配置文件，doctor 检测到不兼容配置。
解决：这个报错不影响后续流程，onboarding 向导会继续。如需详细信息运行 openclaw doctor --verbose。
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 ch@t 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" 让其自动修复。
Config already present; skipping onboarding原因：已有 ~/.openclaw/openclaw.json，安装脚本检测到后跳过了 onboarding。
解决：手动触发向导：
openclaw onboard
localhost:18789 一直报 token_missing原因：OpenClaw 默认开启 token 认证，不能直接访问裸地址。
解决：用 openclaw dashboard 命令打开（自动带 token），或查看 token 手动拼 URL：
openclaw config get gateway.auth.token
原因：向导配置了相关 channel 但未完成认证。
解决：
openclaw config set channels.telegram.enabled false
Your Xcode is too outdated原因：macOS 特有问题，Xcode 14.x 无法编译新版 Homebrew 公式。
解决：去 App Store 更新 Xcode 到 16.4+，或忽略（不影响主功能）。
openclaw gateway 和 LaunchAgent 冲突，端口被占用原因：LaunchAgent 已经启动了 Gateway，手动再运行 openclaw gateway 导致端口冲突。
解决：macOS 上无需手动运行 openclaw gateway，LaunchAgent 已经管好了。检查状态：
launchctl list | grep openclaw
| 模型 | 统一内存需求 | 速度（M 系列） | 拉取命令 |
|---|---|---|---|
| qwen2.5:3b | 2 GB | 极快 | ollama pull qwen2.5:3b |
| qwen2.5:7b | 5 GB | 很快 | ollama pull qwen2.5:7b |
| qwen3.5:9b | 6 GB | 很快 | ollama pull qwen3.5:9b |
| qwen2.5:14b | 10 GB | 快 | ollama pull qwen2.5:14b |
| qwen2.5:32b | 20 GB | 中 | ollama pull qwen2.5:32b |
| deepseek-r1:32b | 20 GB | 中 | ollama pull deepseek-r1:32b |
以下为经过实战验证的完整配置文件（适配 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 | macOS | ||
|---|---|---|---|---|
| 安装命令 | `irm openclaw.ai/install.ps1 | iex` | `curl -fsSL openclaw.ai/install.sh | bash` |
| 包管理器 | scoop / winget | Homebrew（预装检测） | ||
| Gateway 启动 | 需手动运行 openclaw gateway | LaunchAgent 自动管理 | ||
| Skills 主要失败原因 | brew not installed | Xcode 版本过旧 | ||
| Skills 修复方案 | 安装 scoop 替代 | 更新 Xcode 到 16.4+ | ||
| 上下文窗口问题 | ️ 必须手动创建 32k 版本模型 | 无需处理，Ollama 自动适配 | ||
| 配置文件路径 | %USERPROFILE%.openclawopenclaw.json | ~/.openclaw/openclaw.json | ||
| 日志路径 | %USERPROFILE%.openclawlogs | ~/.openclaw/logs/gateway.log |
完成以上步骤后，你拥有了：
graph LR
A[" OpenClaw<br/>本地 AI 助手"] --> B["文件管理"]
A --> C["代码生成"]
A --> D["网页控制"]
A --> E["定时任务"]
A --> F[" Apple 生态<br/>Notes / Things / Bear"]
A --> G["文档分析"]
style A fill:#4a0e8f,color:#fff
style F fill:#1a1a2e,color:#fff
下一步探索：
openclaw security audit --deep 加固安全配置
