MacOS 下 OpenClaw 安装指南与常见问题解决

{"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 命令速查

第四部分：免费模型推荐