OpenClaw 是一款基于 Node.js 的 AI 智能体框架，支持在 macOS 环境下通过命令行快速部署。本文详细说明了环境准备（Homebrew、Xcode Tools、Node.js）、全局安装步骤、模型配置（以阿里云百炼为例）以及 Web 界面启动方法。同时整理了常见安装问题如 Homebrew 下载卡住、npm 权限错误、网关未重启等场景的排查与修复方案，帮助用户顺利完成本地 AI 代理搭建。
本文整理了 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
1. 全局安装
sudo npm install -g openclaw
# 验证
openclaw --version # 应为 2026.x.x
2. 运行配置向导
openclaw onboard --install-daemon
按提示选择：
Install daemon? → yesOnboarding mode → QuickStartSkip for now，后续手动配置1. 获取阿里云 API Key
sk- 开头）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/，开始对话！
现象：==> Downloading and installing Homebrew... 长时间不动
原因：GitHub 连接不稳定
解决：使用国内镜像
/bin/zsh -c "$(curl -fsSL https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh)"
现象：长时间停在 OpenSSL 编译 原因：从源码编译慢，或网络问题 解决：强制使用预编译版本
brew install --force-bottle node
现象：
npm error [email protected]: Permission denied (publickey)
原因：npm 尝试用 SSH 协议拉取 GitHub 依赖 解决：强制使用 HTTPS
git config --global url."https://github.com/".insteadOf [email protected]:
现象：打开 http://127.0.0.1:18789/ 后无限转圈
原因：模型未配置 / API Key 无效 / 网关未重启
解决：
# 1. 检查网关状态
openclaw gateway status
# 2. 运行自动修复
openclaw doctor --fix
# 3. 重启网关
openclaw gateway restart
现象：
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
现象：用几分钟就提示速率限制 原因：免费账户 RPM 限制很严（约 3-5 次/分钟） 解决：换用阿里云百炼或 Google Gemini
现象：配置时跳转到 billing 页面，要求绑卡 原因：平台需要身份验证，免费模型也要绑卡 解决：直接放弃，换用阿里云百炼或 Google Gemini
现象：改了 openclaw.json 但 Web 界面没变化
原因：没有重启网关
解决：
openclaw gateway restart
现象：模型有回复，但内容是空的
原因：配置中 reasoning 参数设为 true
解决：在模型配置中设置 "reasoning": false
现象：brew 命令提示 Xcode Command Line Tools 过期
解决：
# 方法一：通过系统设置更新
# 苹果图标 → 系统设置 → 通用 → 软件更新
# 方法二：手动重装
sudo rm -rf /Library/Developer/CommandLineTools
sudo xcode-select --install
现象：sudo npm install -g openclaw 长时间无响应
原因：npm 默认 registry 在国外
解决：切换国内镜像
npm config set registry https://registry.npmmirror.com
# 然后重新安装
sudo npm install -g openclaw
现象：配置后提示 401 或认证失败 原因：API Key 复制错误，或未开通对应模型 解决：
qwen3.5-plus）| 命令 | 作用 |
|---|---|
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 助手辅助排查错误代码。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online