【MacOS】OpenClaw 完全安装指南：包教包会保姆级，附常见问题全解

【MACOS版本】OpenClaw 完全安装指南：包教包会保姆级，附常见问题全解

经过几天的折腾，终于把 OpenClaw 在 Mac 上成功跑起来了。过程中踩了无数坑——Homebrew 装不上、Node.js 卡编译、API Key 无效、Rate Limit、绑卡验证…现在把这些经验整理出来，希望能帮你少走弯路。

第一部分：正常安装步骤（5 分钟快速版）

一、环境准备

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 installnode# 验证node-v# 应为 v22.x.xnpm-v# 应为 10.x.x

二、安装 OpenClaw

1. 全局安装

sudonpminstall-g openclaw # 验证 openclaw --version# 应为 2026.x.x

2. 运行配置向导

openclaw onboard --install-daemon 

按提示选择：

• Install daemon? → yes
• Onboarding mode → QuickStart
• 模型提供商可以先选 Skip for now，后续手动配置

三、配置模型（以阿里云百炼为例）

1. 获取阿里云 API Key

• 访问 阿里云百炼
• 开通服务，领取免费额度（新用户 100万-7000万 Token）
• 进入密钥管理 → 创建 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 过期
解决：

# 方法一：通过系统设置更新# 苹果图标 → 系统设置 → 通用 → 软件更新# 方法二：手动重装sudorm-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 # 然后重新安装sudonpminstall-g openclaw 

🚨 问题 12：阿里云 API Key 无效

现象：配置后提示 401 或认证失败
原因：API Key 复制错误，或未开通对应模型
解决：

• 重新在阿里云控制台复制 Key（注意不要有空格）
• 确认已开通百炼服务并领取免费额度
• 确认模型 ID 正确（如 qwen3.5-plus）

第三部分：常用 OpenClaw 命令速查

第四部分：免费模型推荐

个人建议：国内用户首选阿里云百炼，稳定且免费额度高；有谷歌账号的可以试试 Gemini，无需手机号最省事。

写在最后

OpenClaw 是个非常强大的 AI 智能体框架，但初次安装确实会遇到不少坑。最大的心得是：如果某个平台（如 OpenCode Zen）要求绑卡或手机号验证，果断换一个。国内用户推荐阿里云百炼，免费额度高，速度也快。

如果你在安装过程中遇到本文没覆盖的问题，欢迎留言交流～

最后的最后，安装的终极解决大法：打开deepseek，遇到任何问题，把错误代码报给它，它什么都知道！！！