【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 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? → 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 git@github.com: Permission denied (publickey)

原因：npm 尝试用 SSH 协议拉取 GitHub 依赖
解决：强制使用 HTTPS

git config --global url."https://github.com/".insteadOf git@github.com:

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

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

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