OpenClaw大龙虾机器人完整安装教程

OpenClaw大龙虾机器人完整安装教程

OpenClaw（大龙虾机器人）是一款本地部署的全能AI助手，可通过WhatsApp、Telegram、飞书等聊天软件实现邮件处理、日历管理、系统操作等功能，数据本地存储更隐私。本教程适配macOS/Linux/Windows系统，包含基础安装、初始化配置、聊天软件对接及常见问题解决，新手也能快速上手。

一、安装前准备

1. 系统与硬件要求

|配置项 |最低要求 |推荐配置 |
|:--|
|操作系统 |macOS 12+/Ubuntu 20.04+/Windows 10（需WSL2） |macOS 14+/Ubuntu 22.04+/Windows 11 |
|内存 |4GB |8GB+ |
|磁盘空间 |2GB可用 |10GB+ SSD |
|核心依赖 |Node.js 18.0+ |Node.js v22 LTS最新版 |

2. 必备前置资源

  • AI模型API Key：Claude、GPT-4/5、阿里云百炼、Kimi等兼容OpenAI API的模型密钥（需前往对应平台官网注册获取）；
  • 网络环境：建议配置国内npm镜像（加速依赖下载），Windows用户需提前安装Git（解决依赖拉取问题）。

二、分系统快速安装

方案1：macOS/Linux系统（官方推荐，一键安装）

  1. 打开终端，执行官方一键安装脚本（自动安装Node.js及所有依赖）：
	curl -fsSL https://openclaw.ai/install.sh | bash
  1. 也可通过npm全局安装（备用方式）：
	# 配置国内npm镜像（可选，加速下载）
	npm config set registry https://registry.npmmirror.com
	# 全局安装OpenClaw
	npm install -g openclaw@latest
	```
3. 验证安装成功：

openclaw --version

显示版本号即安装完成。
### 方案2：Windows系统（原生适配，避坑版）
Windows原生对OpenClaw支持较弱，需先配置Node.js环境，**全程用管理员权限打开PowerShell**操作：
1. 安装Node.js v22：

安装nvm（Node版本管理工具，推荐）

iwr -useb https://raw.githubusercontent.com/coreybutler/nvm-windows/master/nvm-setup.exe | iex
# 安装并使用Node.js 22
nvm install 22
nvm use 22.22.0

2. 执行Windows专属安装脚本：
	```
	iwr -useb https://openclaw.ai/install.ps1 | iex
	```
3. 若遇**执行策略报错**，先执行以下命令再重新安装：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

4. 验证安装：

openclaw --version


### 方案3：开发者进阶安装（Git克隆源码）

适合需要自定义开发、修改源码的用户，macOS/Linux/Windows（WSL2）均可使用：

克隆仓库

git clone https://github.com/openclaw/openclaw.git

进入目录并安装依赖

cd openclaw && pnpm install && pnpm run build

初始化

pnpm run openclaw onboard

## 三、初始化配置（核心步骤）

安装完成后，执行初始化命令进入交互式配置向导，配置AI模型和基础参数：

通用初始化命令

openclaw onboard

Windows新手推荐快速配置

openclaw onboard --flow quickstart

### 1. 风险确认
首次配置会出现风险提示：`I understand this is powerful and inherently risky. Continue?`，选择**Yes**继续。
### 2. 选择AI模型并配置API Key
1. 按方向键选择常用AI模型（推荐Claude/GPT-4/阿里云百炼，国内用户优先选阿里云百炼/Kimi，访问更稳定）；
2. 粘贴提前获取的**API Key**（格式为`sk-xxxxxxxx`），回车确认；
3. 部分模型需浏览器打开链接完成账号授权，按提示操作即可。
### 3. 基础功能配置

- **技能包（Skill）**：新手直接选**No**跳过，后续按需安装；
- **记忆功能（Hooks）**：选中`session-memory`（启用多轮对话记忆，避免重复说明需求），其他默认；
- 配置完成后，系统会自动启动**Gateway网关服务**，默认端口`18789`。

### 4. 打开管理控制台

配置完成后，浏览器会自动打开本地控制台，手动访问地址：

http://127.0.0.1:18789

首次进入需输入初始化生成的**配置Token**（妥善保存，丢失需重新初始化）。
## 四、对接聊天软件（以飞书为例，国内常用）

OpenClaw支持WhatsApp、Telegram、飞书、钉钉、微信等平台，**飞书配置难度低、稳定性高**，以下为详细对接步骤，其他平台操作逻辑类似。
### 1. 安装飞书插件

在终端/PowerShell执行插件安装命令：

openclaw plugins install @m1heng-clawd/feishu

进入插件目录完成依赖安装

cd /root/.openclaw/extensions/feishu/ && npm install --verbose

### 2. 飞书开放平台创建应用

1. 访问飞书开放平台：[ https://open.feishu.cn/app/ ，登录后点击](https://open.feishu.cn/app/%EF%BC%8C%E7%99%BB%E5%BD%95%E5%90%8E%E7%82%B9%E5%87%BB)**创建企业自建应用**；
2. 填写应用名称（如「大龙虾AI助手」），选择图标，点击**创建**；
3. 进入应用管理页，点击**添加应用能力** → 选择**机器人** → 点击**添加**。

### 3. 配置飞书应用权限与事件

#### （1）批量导入权限

1. 进入应用管理页**权限管理** → 点击**批量导入权限**；
2. 粘贴以下JSON代码，点击**导入**（核心权限，确保机器人能收发消息）：

{
"scopes": {
"tenant": [
"contact:user.base:readonly",
"im:chat",
"im:message",
"im:message:send_as_bot",
"im:resource"
],
"user": []
}
}


#### （2）事件订阅配置

1. 进入**事件与回调** → 事件配置选择**长连接**，点击**保存**；
2. 点击**添加事件** → 选择**消息与群组** → 勾选**im.message.receive_v1**（接收消息事件，必选）；
3. 订阅方式选择**使用长连接**，无需填写回调地址，自动生效。

#### （3）发布应用

1. 进入**版本管理与发布** → 点击**新建版本**，填写版本号和描述；
2. 点击**保存并发布**，飞书应用配置完成（未发布则配置不生效）。

### 4. OpenClaw绑定飞书应用

1. 在终端执行命令，添加飞书通信渠道：

openclaw channels add
```
2. 按提示输入飞书应用的App ID和App Secret（在飞书开放平台「凭证基础信息」中复制）；
3. 重启网关服务，使配置生效：

	openclaw gateway restart
	```
4. 验证状态：

openclaw status
```
显示Gateway running即绑定成功。

5. 飞书端测试使用

  1. 打开飞书APP，进入工作台 → 找到创建的「大龙虾AI助手」，点击进入私聊窗口；
  2. 发送任意消息（如「你好」「整理我的今日日程」），收到机器人回复即对接完成。

五、基础使用与常用命令

1. 核心使用方式

在绑定的聊天软件中直接发送自然语言指令，机器人即可执行操作，例如：

  • 邮件处理：「帮我整理上周的未读邮件，提取会议纪要」；
  • 文件管理：「将桌面PDF文件按日期归档到文档文件夹」；
  • 系统操作：「执行shell命令查看电脑CPU使用率」；
  • 定时任务：「每天早上9点给我发送今日待办事项」。

2. 常用终端命令汇总

|功能 |命令 |
|:--|
|查看版本 |openclaw --version |
|查看运行状态 |openclaw status |
|启动/停止/重启机器人 |openclaw start/stop/restart |
|重新初始化配置 |openclaw onboard |
|重启网关服务 |openclaw gateway restart |
|查看已安装插件 |openclaw plugins list |
|安装插件 |openclaw plugins install 插件名 |
|卸载插件 |openclaw plugins uninstall 插件名 |
|查看帮助 |openclaw --help |

六、常见问题与避坑指南

1. 安装时卡在node-gyp rebuild

原因：缺少Python和C++编译工具；
解决：

  • Windows：安装Visual Studio Build Tools和CMake；
  • macOS：执行xcode-select --install安装Xcode命令行工具；
  • Linux：执行sudo apt install build-essential python3。

2. Windows提示「系统找不到指定的路径」

原因：系统组件被精简、WSL未启用或Git环境未配置；
解决：

  1. 安装Git（官网： https://git-scm.com/download/win ），安装后重启电脑；
  2. 启用WSL2：在PowerShell执行wsl --install；
  3. 清理npm缓存并重装：
	npm cache clean --force
	npm install -g openclaw@latest
	```

### 3. 飞书配置提示「未建立长连接」

**解决**：
1. 检查App ID和App Secret是否输入正确；
2. 等待1-2分钟再重新保存长连接配置（网络延迟导致）；
3. 执行`openclaw gateway restart`重启网关，再重新配置。

### 4. 聊天软件发送消息无回复

**排查步骤**：
1. 执行`openclaw status`确认网关服务正常运行；
2. 检查聊天软件应用的**事件订阅**是否添加`im.message.receive_v1`；
3. 确认应用已在飞书开放平台**发布**（未发布无法收发消息）；
4. 查看网关日志：`openclaw gateway --verbose`，定位错误原因。

### 5. 国内网络下载依赖卡顿/失败

**解决**：
1. 配置国内npm镜像：`npm config set registry https://registry.npmmirror.com`；
2. 使用代理工具，或手动下载离线安装包进行安装。

## 七、进阶优化（可选）

1. **汉化适配**：国内用户建议安装社区汉化版，优化微信/企业微信支持：

npm install -g openclaw-cn@latest
```
2. Docker部署：适合需要7×24小时运行的用户，容器化部署更稳定：

	git clone https://github.com/openclaw/openclaw.git
	cd openclaw
	docker compose up -d openclaw-gateway
	```
3. **本地模型部署**：修改`.env`文件中的`MODEL_PROVIDER`和`API_KEY`，支持本地运行Llama、Qwen等模型，完全脱离外网。
4. **权限限制**：在`config.json`中设置`allowed_commands`和`denied_commands`，禁止机器人执行危险shell命令，提升安全性。

## 八、注意事项

1. **隐私安全**：OpenClaw默认本地部署，数据不上传，但建议**不要在装有重要商业/隐私数据的电脑上运行**，可使用闲置设备或云端虚拟机（VPS）；
2. **版本兼容**：避免使用最新版（官方频繁更新易出问题），新手建议安装稳定版：`npm install -g openclaw@1.0.0`（替换为实际稳定版本号）；
3. **服务保活**：本地部署时，关闭终端/PowerShell会导致网关服务停止，可使用`pm2`等工具实现后台保活。

本文来自博客园，作者：[家兴网络技术工作室](https://www.cnblogs.com/seozimt/)，转载请注明原文链接：https://www.cnblogs.com/seozimt/p/19634519

posted on 2026-08-10 15:32  爱河  阅读(2)  评论(0)    收藏  举报

导航