MacOS 版本 OpenClaw 完全安装指南
本文整理了 OpenClaw 在 macOS 环境下的完整安装流程，涵盖环境准备、全局安装、模型配置及常见问题排查，帮助快速搭建本地 AI 智能体框架。
第一部分：正常安装步骤
一、环境准备
1. 安装 Homebrew（已装可跳过）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
如果遇到网络问题，使用国内镜像：
/bin/zsh -c "$(curl -fsSL https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh)"
2. 安装 Xcode Command Line Tools（如未安装）
xcode-select --install
按提示完成图形化安装。
3. 安装 Node.js（必须 22+）
brew install node
# 验证
node -v # 应为 v22.x.x
npm -v # 应为 10.x.x
二、安装 OpenClaw
1. 全局安装
sudo npm install -g openclaw
# 验证
openclaw --version # 应为 2026.x.x
2. 运行配置向导
openclaw onboard --install-daemon
按提示选择：
Install daemon?→yesOnboarding mode→QuickStart- 模型提供商可以先选
Skip for now，后续手动配置
三、配置模型（以阿里云百炼为例）
1. 获取阿里云 API Key
- 访问阿里云百炼控制台
- 开通服务，领取免费额度
- 进入密钥管理 → 创建 API Key（以
sk-开头） - 在模型广场找到想用的模型 ID（如
qwen3.5-plus）
2. 修改 OpenClaw 配置文件
nano ~/.openclaw/openclaw.json
粘贴以下内容（替换 YOUR_API_KEY_HERE 为你的真实 Key）：
{
"models": {
"providers": {
"bailian": {
"baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"api": "openai-completions",
"apiKey": "YOUR_API_KEY_HERE",
"models": [
{
"id": "qwen3.5-plus",
"name": "qwen3.5-plus",
"reasoning": false,
"input": ["text"],
"contextWindow": 128000,
"maxTokens": 8192
}
]
}
}
},
"agents": {
"defaults": {
"model": {
"primary": "bailian/qwen3.5-plus"
}
}
},
"gateway": {
"mode": "local",
"auth": {
"mode": "none"
}
}
}
保存退出：Ctrl+O → Enter → Ctrl+X
3. 重启网关
openclaw gateway restart
4. 打开 Web 界面
openclaw dashboard
浏览器自动打开 http://127.0.0.1:18789/，开始对话！
第二部分：常见问题及解决方案
🚨 问题 1：Homebrew 安装卡在 89%
现象：==> Downloading and installing Homebrew... 长时间不动
原因：GitHub 连接不稳定
解决：使用国内镜像
/bin/zsh -c "$(curl -fsSL https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh)"
🚨 问题 2：brew install node 卡在 'make install'
现象：长时间停在 OpenSSL 编译 原因：从源码编译慢，或网络问题 解决：强制使用预编译版本
brew install --force-bottle node
🚨 问题 3：npm 安装时报错 'Permission denied (publickey)'
现象：
npm error [email protected]: Permission denied (publickey)
原因：npm 尝试用 SSH 协议拉取 GitHub 依赖 解决：强制使用 HTTPS
git config --global url."https://github.com/".insteadOf [email protected]:
🚨 问题 4：Web 界面一直转圈加载
现象：打开 http://127.0.0.1:18789/ 后无限转圈
原因：模型未配置 / API Key 无效 / 网关未重启
解决：
# 1. 检查网关状态
openclaw gateway status
# 2. 运行自动修复
openclaw doctor --fix
# 3. 重启网关
openclaw gateway restart
🚨 问题 5：报错 'FormulaUnavailableError: formula.jws.json'
现象：
Error: No available formula with the name "formula.jws.json"
原因：Homebrew 4.0+ 的 API 文件下载失败 解决：强制使用旧版模式
echo 'export HOMEBREW_NO_INSTALL_FROM_API=1' >> ~/.zshrc
source ~/.zshrc
brew update
🚨 问题 6：Moonshot 频繁提示 'rate limit reached'
现象：用几分钟就提示速率限制 原因：免费账户 RPM 限制很严（约 3-5 次/分钟） 解决：换用阿里云百炼或 Google Gemini
- 阿里云百炼：国内稳定，免费额度高
- Google Gemini：无需手机号，500 次/天
🚨 问题 7：OpenCode Zen 要求绑定支付方式
现象：配置时跳转到 billing 页面，要求绑卡 原因：平台需要身份验证，免费模型也要绑卡 解决：直接放弃，换用阿里云百炼或 Google Gemini
🚨 问题 8：配置文件修改后不生效
现象：改了 openclaw.json 但 Web 界面没变化
原因：没有重启网关
解决：
openclaw gateway restart
🚨 问题 9：阿里云模型返回空内容
现象：模型有回复，但内容是空的
原因：配置中 reasoning 参数设为 true
解决：在模型配置中设置 "reasoning": false
🚨 问题 10：macOS 提示 'Command Line Tools 需要更新'
现象：brew 命令提示 Xcode Command Line Tools 过期
解决：
# 方法一：通过系统设置更新
# 苹果图标 → 系统设置 → 通用 → 软件更新
# 方法二：手动重装
sudo rm -rf /Library/Developer/CommandLineTools
sudo xcode-select --install
🚨 问题 11：npm 安装时卡住或极慢
现象：sudo npm install -g openclaw 长时间无响应
原因：npm 默认 registry 在国外
解决：切换国内镜像
npm config set registry https://registry.npmmirror.com
# 然后重新安装
sudo npm install -g openclaw
🚨 问题 12：阿里云 API Key 无效
现象：配置后提示 401 或认证失败 原因：API Key 复制错误，或未开通对应模型 解决：
- 重新在阿里云控制台复制 Key（注意不要有空格）
- 确认已开通百炼服务并领取免费额度
- 确认模型 ID 正确（如
qwen3.5-plus）
第三部分：常用 OpenClaw 命令速查
| 命令 | 作用 |
|---|---|
openclaw dashboard | 打开 Web 控制台 |
openclaw gateway status | 查看网关状态 |
openclaw gateway restart | 重启网关（修改配置后必做） |
openclaw doctor --fix | 自动修复常见问题 |
openclaw configure | 重新运行配置向导 |
openclaw models | 查看可用模型 |
openclaw skills install <技能名> | 安装技能 |
openclaw update | 更新 OpenClaw |
openclaw --version | 查看版本 |
第四部分：免费模型推荐
| 平台 | 免费额度 | 是否需要手机号 | 是否需要绑卡 |
|---|---|---|---|
| 阿里云百炼 | 100 万 -7000 万 Token | ✅ | ❌ |
| Google Gemini | 500-1500 次/天 | ❌（谷歌账号） | ❌ |
| Moonshot (Kimi) | 15 元体验金 | ✅ | ❌ |
| 智谱 GLM-4.7-Flash | 完全免费 | ✅ | ❌ |
| OpenCode Zen | 部分模型免费 | ✅ | ✅（必须绑卡） |
个人建议：国内用户首选阿里云百炼，稳定且免费额度高；有谷歌账号的可以试试 Gemini，无需手机号最省事。
总结
OpenClaw 是一个强大的 AI 智能体框架，初次安装可能遇到环境依赖或网络问题。核心建议是：如果某个平台要求绑卡或复杂验证，优先更换其他服务商。国内用户推荐阿里云百炼，免费额度高且速度稳定。如遇未覆盖问题，可查阅官方文档或使用通用 AI 助手辅助排查错误代码。
