OpenClaw（小龙虾）从零开始安装教程

OpenClaw（小龙虾）从零开始安装教程

> 适用人群：完全零基础新手

> 预计时间：30-60 分钟

> 更新时间：2026-03-15

---

📋 目录

1. [什么是 OpenClaw](#什么是-openclaw)

2. [安装前准备](#安装前准备)

3. [Windows 系统安装](#windows-系统安装)

4. [macOS 系统安装](#macos-系统安装)

5. [配置大模型 API](#配置大模型-api)

6. [连接飞书/微信](#连接飞书微信)

7. [常见问题](#常见问题)

---

什么是 OpenClaw

OpenClaw（中文名：小龙虾）是一款开源的个人 AI 智能体平台。

🦞 它能做什么？

🆚 和 ChatGPT 的区别

---

安装前准备

🌐 国内网络环境注意事项（重要！）

本教程面向中国大陆用户，所有资源均可直接访问，无需科学上网！

---

为什么需要配置：npm 官方源在国外，下载速度极慢，配置国内镜像可提升 10 倍以上速度！

配置方法：

1. 打开命令提示符（CMD）或 PowerShell

2. 配置淘宝镜像（推荐）：

# 设置淘宝镜像
npm config set registry https://registry.npmmirror.com

# 验证配置
npm config get registry

看到 `https://registry.npmmirror.com/` 说明配置成功 ✅

3. （可选）配置腾讯云镜像：

npm config set registry https://mirrors.cloud.tencent.com/npm/

4. （可选）配置华为云镜像：

npm config set registry https://mirrors.huaweicloud.com/repository/npm/

---

---

推荐顺序（按性价比和稳定性）：

不推荐：

• ❌ OpenAI（需要国际信用卡 + 科学上网）
• ❌ Anthropic Claude（同上）
• ❌ Google Gemini（同上）

---

强烈推荐飞书：

• 国内访问速度快
• 免费个人版够用
• OpenClaw 集成完善
• 支持群聊、私聊、机器人

---

✅ 系统要求

✅ 硬件要求

✅ 软件准备

1. Node.js 22+（必须）
- 下载地址：https://nodejs.org/
- 选择 LTS 版本（长期支持版，LTS = Long Term Support，即官方长期维护的稳定版本）

2. Git（可选，推荐）
- Windows：https://git-scm.com/download/win
- macOS：安装 Xcode Command Line Tools

3. 大模型 API 密钥（必须，选一个即可）
- 阿里云通义千问：https://dashscope.console.aliyun.com/
- 腾讯云混元：https://cloud.tencent.com/product/hunyuan
- 百度文心一言：https://cloud.baidu.com/product/wenxinworkshop

---

🖥️ 如何打开命令行（小白必看）

教程中需要输入命令，首先要打开命令行工具：

Windows 用户：
1. 按键盘上的 `Win + R`（Win 键是左下角带 Windows 图标的键）
2. 输入 `cmd`，按回车
3. 看到黑色窗口，就是命令提示符了 ✅

> 💡 小技巧：也可以直接在开始菜单搜索框输入 `cmd` 或 `PowerShell`，点击打开

macOS 用户：
1. 按 `Cmd + 空格` 打开 Spotlight 搜索
2. 输入 `terminal` 或 `终端`
3. 点击「终端」应用打开 ✅

> 💡 小技巧：也可以在「启动台」→「其他」文件夹中找到「终端」

---

Windows 系统安装

⚠️ Windows 家庭版注意事项（重要！）

如果你的系统是 Windows 10/11 家庭中文版，请先阅读以下内容！

1. 安装 Visual C++ 运行库

1. 访问：https://aka.ms/vs/17/release/vc_redist.x64.exe

2. 下载并安装 Visual C++ 2015-2022 运行库

3. 安装完成后重启电脑

2. 启用开发者模式

1. 打开 设置 → 更新和安全 → 对于开发人员

2. 选择 开发者模式

3. 确认启用

3. 检查系统版本

# 在命令提示符中输入
winver

确保版本号 ≥ Windows 10 版本 2004

---

步骤 1：安装 Node.js

1. 打开浏览器，访问 https://nodejs.org/

2. 点击绿色按钮 Download Node.js (LTS)

3. 下载完成后，双击安装包

4. 一直点击 Next，使用默认设置即可

5. 安装完成后，打开 命令提示符（CMD）或 PowerShell

6. 输入以下命令验证安装：

node --version

看到类似 `v22.x.x` 的版本号，说明安装成功 ✅

> ⚠️ 如果显示「'node' 不是内部或外部命令」：
> 1. 关闭命令行窗口，重新打开再试
> 2. 如果还是不行，说明环境变量没配置好，请查看下方「常见问题」的解决方案

---

步骤 2：安装 OpenClaw

1. 在命令提示符中输入以下命令：

npm install -g openclaw@latest

> 📌 命令解释：`npm` 是 Node.js 的包管理工具，`-g` 表示全局安装（装到系统目录，以后在任何地方都能用），`@latest` 表示安装最新版本

2. 等待安装完成（可能需要 3-5 分钟）

3. 验证安装：

openclaw --version

看到版本号说明安装成功 ✅

> ⚠️ 如果显示「'openclaw' 不是内部或外部命令」：
> 1. 关闭命令行窗口，重新打开再试
> 2. 如果还是不行，尝试运行 `npm install -g openclaw@latest` 重新安装

---

步骤 3：初始化配置

1. 运行初始化命令：

openclaw onboard --install-daemon

2. 系统会提示你选择配置模式，选择 Local（本地配置）

3. 接下来会引导你配置大模型 API

---

步骤 4：配置大模型 API

以阿里云通义千问为例：

1. 访问 https://dashscope.console.aliyun.com/

2. 注册/登录阿里云账号

3. 进入 API-KEY 管理 页面

4. 点击 创建新的 API-KEY

5. 复制生成的 API-KEY（类似 `sk-xxxxxxxxxxxxxxxx`）

6. 回到命令提示符，运行：

openclaw config

7. 按照提示选择：
- Provider → 选择 `aliyun` 或 `dashscope`
- API Key → 粘贴刚才复制的 API-KEY
- Model → 新手建议选择 `qwen-turbo`（速度快、便宜），进阶可选 `qwen-plus`（能力更强）

8. 配置完成后，系统会提示重启 Gateway

---

步骤 5：启动 Gateway

> 📌 什么是 Gateway？
> Gateway 是 OpenClaw 的核心服务程序，负责接收消息、调用大模型、执行任务。简单说，它是小龙虾的「大脑」，必须先启动它才能正常使用。

openclaw gateway start

看到 Gateway started 提示，说明启动成功 ✅

> ⚠️ 如果启动失败：请检查端口是否被占用，或查看下方「常见问题」章节

---

macOS 系统安装

步骤 1：安装 Homebrew（如果没有）

> 📌 什么是 Homebrew？
> Homebrew 是 macOS 上最流行的软件包管理工具，可以像 App Store 一样方便地安装各种开发工具。这是开发者社区公认的标准工具，安全可靠。

打开 终端（Terminal），输入：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

按照提示完成安装。

---

步骤 2：安装 Node.js

brew install node@22

验证安装：

node --version

---

步骤 3：安装 OpenClaw

npm install -g openclaw@latest

---

步骤 4：初始化配置

openclaw onboard --install-daemon

按照提示完成配置。

---

步骤 5：配置大模型 API

openclaw config

选择你的大模型提供商，输入 API-KEY。

---

步骤 6：启动 Gateway

openclaw gateway start

---

配置大模型 API

推荐配置（性价比最高）

为什么不推荐免费额度？

• 免费额度通常只有几百万 token
• 和小龙虾聊十几轮就用完了
• 后续收费更贵

建议：直接购买 Coding Plan 套餐，按次计费，更划算！

---

阿里云 Coding Plan 开通步骤

1. 访问：https://www.aliyun.com/benefit/scene/codingplan

2. 登录阿里云账号

3. 选择 Coding Plan Lite 套餐

4. 支付 9.9 元/月

5. 开通后，在 API-KEY 管理 页面创建密钥

---

连接飞书/微信

连接飞书（推荐）

1. 运行命令：

openclaw channels add feishu

2. 系统会返回一个 URL，在浏览器中打开

3. 登录你的飞书账号

4. 授权 OpenClaw 访问

5. 授权完成后，飞书 channel 就配置好了

6. 在飞书中搜索 OpenClaw 或 小爪，找到机器人

7. 发送消息测试：`你好`

---

连接微信公众号（高级功能）

需要公众号管理员权限：

1. 获取公众号 AppID 和 AppSecret

2. 配置服务器地址

3. 运行命令：

openclaw channels add wechat

4. 按照提示完成配置

---

常见问题

🪟 Windows 家庭版专题

症状：输入 `npm install` 提示"'npm' 不是内部或外部命令"

解决方案：

1. 找到 Node.js 安装路径（默认：`C:Program Filesnodejs`）
2. 右键 此电脑 → 属性 → 高级系统设置
3. 点击 环境变量
4. 在 系统变量 中找到 `Path`，点击 编辑
5. 点击 新建，添加：`C:Program Filesnodejs`
6. 点击 确定 保存
7. 重启命令提示符，再次尝试

---

症状：安装时提示 `Error: EACCES: permission denied`

解决方案 A：使用管理员身份

1. 在开始菜单搜索 cmd 或 PowerShell

2. 右键 → 以管理员身份运行

3. 在管理员窗口中运行安装命令

解决方案 B：修改 npm 全局目录

# 1. 创建新的全局目录
mkdir C:npm-global

# 2. 配置 npm 使用新目录
npm config set prefix "C:npm-global"

# 3. 添加环境变量
# 在系统环境变量 Path 中添加：C:npm-global

# 4. 重新安装
npm install -g openclaw@latest

---

症状：`openclaw gateway start` 失败，提示端口被占用

解决方案：

1. 查找占用端口的进程：

# 查找 18789 端口占用
netstat -ano | findstr 18789

2. 如果看到类似输出：

TCP    0.0.0.0:18789    0.0.0.0:0    LISTENING    12345

3. 结束占用进程：

taskkill /F /PID 12345

4. 或者修改 OpenClaw 端口：

openclaw config
# 选择修改端口为其他值，如 18790

---

症状：启动时提示 `找不到 VCRUNTIME140.dll` 或类似错误

解决方案：

1. 下载微软官方运行库合集：
- 链接：https://aka.ms/vs/17/release/vc_redist.x64.exe

2. 安装后重启电脑

3. 如果仍有问题，安装 DirectX 运行库：
- 链接：https://www.microsoft.com/zh-cn/download/details.aspx?id=35

---

症状：安装或运行时被 Windows Defender 拦截

解决方案：

1. 打开 Windows 安全中心

2. 选择 病毒和威胁防护

3. 点击 管理设置

4. 在 排除项 中添加：

- `C:Users你的用户名.openclaw`

- `C:Program Filesnodejs`

---

症状：某些教程提到 `gpedit.msc` 但无法打开

解决方案：

家庭版确实没有组策略编辑器，但 OpenClaw 不需要它。如果遇到需要修改系统策略的情况：

1. 使用 注册表编辑器（`regedit`）替代

2. 或者考虑升级到 Windows 专业版

---

❓ 国内网络环境问题

症状：`npm install -g openclaw` 卡住不动，或者提示 `ETIMEDOUT`

解决方案：

1. 检查是否配置了国内镜像：

npm config get registry

应该显示 `https://registry.npmmirror.com/`

2. 如果没有配置，执行：

npm config set registry https://registry.npmmirror.com

3. 清除 npm 缓存：

npm cache clean --force

4. 重试安装：

npm install -g openclaw@latest

---

症状：某些依赖从 GitHub 下载失败

解决方案：

OpenClaw 已发布到 npm，不需要访问 GitHub。如果确实需要访问 GitHub：

1. 使用镜像站：

- https://github.com.cnpmjs.org/

- https://hub.fastgit.xyz/

2. 或者配置 Git 代理（如果有）：

git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890

---

症状：调用阿里云/腾讯云 API 时超时

解决方案：

1. 检查 API-KEY 是否正确
- 登录对应云厂商控制台
- 重新生成 API-KEY
- 更新配置：`openclaw config`

2. 检查是否有余额/额度
- 阿里云：https://dashscope.console.aliyun.com/
- 腾讯云：https://console.cloud.tencent.com/

3. 检查网络防火墙
- 临时关闭防火墙测试
- 或者添加白名单规则

4. 使用内网端点（如果在对应云上）
- 阿里云 ECS 可使用内网访问 OSS

---

症状：运行 `openclaw channels add feishu` 后，浏览器打不开授权页面

解决方案：

1. 手动复制链接到浏览器
- 命令提示符中会显示一个 URL
- 完整复制，粘贴到浏览器地址栏

2. 更换浏览器
- 推荐使用 Chrome、Edge、Firefox
- 避免使用 IE、360 浏览器兼容模式

3. 检查浏览器扩展
- 禁用广告拦截插件
- 禁用隐私保护插件

4. 飞书版本问题
- 确保使用最新版飞书
- 或者使用网页版飞书授权

---

症状：某些资源域名解析失败

解决方案：

1. 修改 DNS 为国内 DNS

- 打开 网络和共享中心

- 点击当前连接的网络

- 点击 属性

- 双击 Internet 协议版本 4 (TCP/IPv4)

- 选择 使用下面的 DNS 服务器地址

- 填写：

- 首选：`223.5.5.5`（阿里云 DNS）

- 备用：`119.29.29.29`（腾讯云 DNS）

2. 刷新 DNS 缓存

ipconfig /flushdns

---

症状：在公司或学校网络下无法安装或运行

解决方案：

1. 使用手机热点
- 最简单的方法
- 安装完成后切回公司网络

2. 申请网络白名单
- 向 IT 部门申请开放以下域名：
- `registry.npmmirror.com`
- `dashscope.aliyuncs.com`（阿里云 API）
- `open.feishu.cn`（飞书 API）

3. 离线安装（高级）
- 在有网络的电脑上下载离线包
- 拷贝到目标电脑安装

---

❓ 安装时提示权限错误

Windows：

• 以管理员身份运行命令提示符
• 或者在命令前加 `--force`：

  npm install -g openclaw@latest --force

macOS/linux：

sudo npm install -g openclaw@latest

---

❓ Gateway 启动失败

1. 检查端口是否被占用：

# Windows
netstat -ano | findstr 18789

# macOS/Linux
lsof -i :18789

2. 如果端口被占用，关闭占用程序或修改配置

3. 查看日志：

openclaw gateway logs

---

❓ API 调用失败

1. 检查 API-KEY 是否正确

2. 检查是否有余额/额度

3. 检查网络连接

4. 查看错误日志：

openclaw gateway logs --follow

---

❓ 飞书机器人不回复

1. 检查飞书 channel 是否配置成功：

openclaw channels list

2. 确认机器人已添加到聊天
3. 检查是否@了机器人（群聊需要@）

---

❓ 如何更新 OpenClaw

npm update -g openclaw
openclaw gateway restart

---

❓ 如何查看帮助

openclaw --help
openclaw gateway --help

---

下一步学习

安装完成后，建议学习：

1. 基础对话 - 和小龙虾聊天，测试功能

2. 技能使用 - 学习使用内置技能

3. 记忆系统 - 了解 MEMORY.md、SOUL.md 等文件

4. 定时任务 - 配置心跳、提醒等自动化任务

5. 多 Agent 协作 - 创建多个智能体分工合作

---

📚 相关资源

---

🆘 获取帮助

遇到问题可以：

1. 查看官方文档

2. 在社区 Discord 提问

3. 查看 GitHub Issues

4. 联系技术支持

---

祝你安装顺利！有问题随时提问！ 🦞

---

教程版本：1.0
最后更新：2026-03-15