JavaScriptNode.jsAI
MacOS 下 OpenClaw 安装指南与常见问题解决
在 macOS 系统上安装 OpenClaw 智能体框架的完整流程，涵盖环境准备（Homebrew、Node.js）、全局安装、模型配置（以阿里云百炼为例）及 Web 界面启动。同时总结了常见的安装问题如网络卡顿、权限错误、API Key 无效等并提供解决方案，附带常用命令速查表及免费模型推荐对比。
在 macOS 系统上安装 OpenClaw 智能体框架的完整流程，涵盖环境准备（Homebrew、Node.js）、全局安装、模型配置（以阿里云百炼为例）及 Web 界面启动。同时总结了常见的安装问题如网络卡顿、权限错误、API Key 无效等并提供解决方案，附带常用命令速查表及免费模型推荐对比。
本文介绍在 macOS 环境下安装 OpenClaw 的步骤及常见问题解决方案。
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 | 部分模型免费 | ✅ | ✅（必须绑卡） |
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online
JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online
Terser 压缩、变量名混淆，或 javascript-obfuscator 高强度混淆（体积会增大）。 在线工具，JavaScript 压缩与混淆在线工具，online