OpenClaw正确安装——保姆级教程(以阿里百炼模型为例)以及避坑指南

OpenClaw正确安装——保姆级教程（以阿里百炼模型为例）以及避坑指南

这篇文章的目标是让一个完全的新手，能跟着步骤一步一步成功安装并运行 OpenClaw。

第一步：环境准备

安装 Node.js（用 nvm 装）(OpenClaw 需要 Node.js 22 及以上版本）* 访问 nvm 官网(https://www.nvmnode.com/zh/)安装方法。 * 安装完成后，重启终端。 * 安装最新的 LTS 版本 Node.js：nvm install --lts* 验证安装：node -v 和 npm -v

第二步：安装 OpenClaw

打开终端，执行全局安装命令：

npm install -g openclaw@latest

第三步：运行配置向导（最关键的一步）

启动向导
```
openclaw onboard
```
选择配置模式

选择 **QuickStart**（快速开始）。

配置 AI 模型（以阿里百炼为例）

Model/auth provider: 选择 OpenAI。（注意：不要选 Qwen 或其他，因为阿里百炼的 API 是 OpenAI 兼容的）
OpenAI auth method: 选择 **OpenAI API key**。
How do you want to provide this API key?: 选择 **Paste API key now**。
Enter OpenAI API key: 粘贴你的阿里百炼 API Key（以 sk- 开头）。
Enter OpenAI base URL (optional): 这一步非常关键！ 必须手动输入阿里百炼的 OpenAI 兼容地址：https://dashscope.aliyuncs.com/compatible-mode/v1。如果向导没有自动跳出这个输入框，先完成向导，之后手动修改配置文件（见第四步）。
Default model: 选择 **Enter model manually**，然后输入你想要的模型 ID，例如 qwen-plus（推荐，性能均衡）。（注意：不要加任何前缀，如 openai/ 或 anthropic/，直接输入 qwen-plus）

配置频道（以跳过飞书为例，推荐新手先跳过）

Select channel: 如果看到 Feishu/Lark，不要选它。如果有 Skip 或 None 选项，直接选择跳过。如果强制要求选一个，可以暂时选 Telegram，随便填一个 Token（如 123:abc），后续可以修改或禁用。
Install Feishu plugin?: 选择 **Skip for now**。飞书配置较复杂，建议核心功能跑通后再折腾。

配置技能（全部跳过）

在 Install missing skill dependencies 界面，选择 **Skip for now**。
后续的 Configure skills now?，也选择 **No**。技能可以以后按需安装。

完成配置

一路按默认选项继续，直到看到类似 Gateway service installed 和 How do you want to hatch your bot? 的界面。

第四步：验证和修复（关键补丁）

如果一切顺利，选择 Hatch in TUI (recommended) 回车，应该就能看到对话界面。但如果报错 Unknown model: anthropic/qwen-plus，说明配置有问题，需要手动修正。

检查配置文件
```
cat ~/.openclaw/openclaw.json
```
修正配置文件（确保格式正确）用 nano 编辑配置文件：
```
nano ~/.openclaw/openclaw.json
```
核心修改点：

找到 "auth" -> "profiles" -> "openai:default"，确保它只有 provider 和 mode，**不要有 apiKey 和 baseURL**。
在文件末尾（或合适位置）添加或确认存在"models" 块，并且 "providers" 下的 "bailian" 包含了正确的 baseUrl 和 apiKey。
找到 "agents" -> "defaults" -> "model" -> "primary"，确保它的值是 **"bailian/qwen-plus"**（格式是 提供商ID/模型ID）。
修改后保存 (Ctrl+O, 回车) 并退出 (Ctrl+X)。

重启网关
```
openclaw gateway restart
```

第五步：测试并开始使用

终端交互界面
```
openclaw tui
```
输入你的第一条消息，如果看到 AI 的正常回复，恭喜你，成功了！
网页界面打开浏览器，访问 http://127.0.0.1:18789，你也可以在这里与 AI 对话。

###避坑指南——安装 OpenClaw 踩过的那些坑

以下记录我从零开始安装 OpenClaw 遇到的坑，希望你无需看下去，因为你一次就成功安装open claw。如何你搞不定，看看怎么帮你绕过这些坑。

坑一：被 Homebrew 的自动更新误导

现象：执行 brew upgrade node 想升级 Node.js，结果提示 Error: node not installed。
真相：我的 Node.js 是用 nvm 安装的，Homebrew 根本不认识它。
教训：先搞清楚你的 Node.js 是谁装的！用 which node 查看路径。如果是 ~/.nvm/...，就老老实实用 nvm install 来升级。如果希望统一管理，可以卸载 nvm 版，改用 Homebrew 安装，但需要权衡利弊。

坑二：配置文件中的模型名和提供商总是不对

现象：反复报错 Unknown model: anthropic/qwen-plus。
真相：

配置位置错误：OpenClaw 要求 API Key 和 Base URL 放在 models.providers 下，而不是 auth.profiles 里。
模型引用格式错误：agents.defaults.model.primary 的值必须是 "提供商ID/模型ID"，比如 "bailian/qwen-plus"，而不能只是 "qwen-plus"，也不能是 "openai/qwen-plus"。
Base URL 键名写错：在 models.providers 中，接入点地址的键名必须是 **baseUrl**（小写 'u'），而不是 baseURL。拼写错误会导致配置被忽略。

教训：不要完全相信向导，它可能不会提示你输入所有关键信息。配置完成后，务必检查 openclaw.json 文件，按照官方推荐的格式手动修正。

坑三：飞书插件配置过于复杂，容易卡住

现象：在 onboard 中选择了飞书，结果卡在 app do not have bot 错误，需要去飞书后台开机器人、配权限、发版本，流程繁琐。
真相：飞书的企业应用配置确实比较重，需要机器人能力、特定权限，并且要发布版本才能生效，不适合快速测试。
教训：对于新手，第一次配置时务必选择跳过飞书插件！ 先确保核心 AI 对话功能跑通，之后再根据官方文档一步步配置飞书。不要在一个频道上耗费太多精力。

坑四：技能安装时 Homebrew 报错

现象：在 onboard 或后续安装技能（如 apple-notes）时，出现 Failed to download https://formulae.brew.sh/... 错误。
真相：OpenClaw 的某些技能依赖于 Homebrew 来安装底层工具。如果网络无法访问 Homebrew 的 API，或者 Homebrew 本身有问题，就会失败。
教训：在 onboard 时，对于所有技能依赖，都选择 **Skip for now**。核心功能跑通后，再根据需要，逐个安装技能。安装时如果遇到网络问题，可以配置代理或手动解决 Homebrew 的访问问题。

坑五：修改配置文件后，错误依然存在

现象：明明按照教程改好了 openclaw.json，但运行 openclaw tui 还是报旧错误。
真相：可能是缓存（cache）或旧的会话数据（sessions）在作祟。

教训：修改配置文件后，如果问题依旧，尝试以下清理步骤：

openclaw gateway stoprm -rf ~/.openclaw/cacherm -rf ~/.openclaw/agents/main/sessions/*openclaw gateway startopenclaw tui

坑六：Gateway 服务反复提示 "not loaded"

现象：运行 openclaw gateway start 或 openclaw tui 时，提示网关服务未加载。
真相：可能是因为配置文件错误导致网关启动失败，或者是服务令牌与配置文件中的令牌不一致。
教训：遇到网关未加载，先检查配置文件有效性。然后用 openclaw gateway install --force 强制重新安装并同步令牌，再尝试启动。