OpenClaw（大龙虾机器人）是一款支持本地部署的全能 AI 助手，能够对接 WhatsApp、Telegram、飞书等聊天软件，实现邮件处理、日历管理及系统操作等功能。数据本地存储特性使其在隐私保护方面表现优异。本指南适配 macOS、Linux 和 Windows 系统，涵盖基础安装、初始化配置、第三方应用对接及常见问题排查，帮助开发者快速搭建私有化 AI 工作流。
一、环境与硬件准备
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（官方推荐）
验证安装是否成功，执行：
openclaw --version
若显示版本号即表示安装完成。也可通过 npm 全局安装作为备用方式：
# 配置国内 npm 镜像（可选，加速下载）
npm config set registry https://registry.npmmirror.com
# 全局安装 OpenClaw
npm install -g openclaw@latest
打开终端，执行官方一键安装脚本（自动安装 Node.js 及所有依赖）：
curl -fsSL https://openclaw.ai/install.sh | bash
方案 2：Windows（原生适配）
Windows 原生对 OpenClaw 支持较弱，需先配置 Node.js 环境，全程使用管理员权限打开 PowerShell 操作。
验证安装：
openclaw --version
若遇执行策略报错，先执行以下命令再重新安装：
Set-ExecutionPolicy ExecutionPolicy RemoteSigned -Scope CurrentUser
执行 Windows 专属安装脚本：
iwr -useb https://openclaw.ai/install.ps1 | iex
如需管理 Node 版本，推荐安装 nvm：
# 安装 nvm
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
方案 3：开发者进阶（源码克隆）
适合需要自定义开发或修改源码的用户，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
- 按方向键选择常用 AI 模型（推荐 Claude/GPT-4/阿里云百炼，国内用户优先选阿里云百炼/Kimi，访问更稳定）；
- 粘贴提前获取的 API Key（格式为
sk-xxxxxxxx），回车确认； - 部分模型需浏览器打开链接完成账号授权，按提示操作即可。
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. 飞书开放平台创建应用
- 访问飞书开放平台，登录后点击 创建企业自建应用；
- 填写应用名称（如「大龙虾 AI 助手」），选择图标，点击 创建；
- 进入应用管理页，点击 添加应用能力 → 选择 机器人 → 点击 添加。
3. 配置飞书应用权限与事件
（1）批量导入权限
- 进入应用管理页 权限管理 → 点击 批量导入权限；
- 粘贴以下 JSON 代码，点击 导入（核心权限，确保机器人能收发消息）：
{"scopes":{"tenant":["contact:user.base:readonly","im:chat","im:message","im:message:send_as_bot","im:resource"],"user":[]}}
（2）事件订阅配置
- 进入 事件与回调 → 事件配置选择 长连接，点击 保存；
- 点击 添加事件 → 选择 消息与群组 → 勾选 im.message.receive_v1（接收消息事件，必选）；
- 订阅方式选择 使用长连接，无需填写回调地址，自动生效。
（3）发布应用
- 进入 版本管理与发布 → 点击 新建版本，填写版本号和描述；
- 点击 保存并发布，飞书应用配置完成（未发布则配置不生效）。
4. OpenClaw 绑定飞书应用
- 按提示输入飞书应用的 App ID 和 App Secret（在飞书开放平台「凭证基础信息」中复制）；
验证状态：
openclaw status
显示 Gateway running 即绑定成功。
重启网关服务，使配置生效：
openclaw gateway restart
在终端执行命令，添加飞书通信渠道：
openclaw channels add
5. 飞书端测试使用
- 打开飞书 APP，进入 工作台 → 找到创建的「大龙虾 AI 助手」，点击进入私聊窗口；
- 发送任意消息（如「你好」「整理我的今日日程」），收到机器人回复即对接完成。
五、基础使用与常用命令
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 环境未配置； 解决：
- 安装 Git，安装后重启电脑；
- 启用 WSL2：在 PowerShell 执行
wsl --install；
清理 npm 缓存并重装：
npm cache clean --force
npm install -g openclaw@latest
3. 飞书配置提示「未建立长连接」
解决：
- 检查 App ID 和 App Secret 是否输入正确；
- 等待 1-2 分钟再重新保存长连接配置（网络延迟导致）；
- 执行
openclaw gateway restart重启网关，再重新配置。
4. 聊天软件发送消息无回复
排查步骤：
- 执行
openclaw status确认网关服务正常运行； - 检查聊天软件应用的 事件订阅 是否添加
im.message.receive_v1； - 确认应用已在飞书开放平台 发布（未发布无法收发消息）；
- 查看网关日志：
openclaw gateway --verbose，定位错误原因。
5. 国内网络下载依赖卡顿/失败
解决：
- 配置国内 npm 镜像：
npm config set registry https://registry.npmmirror.com； - 使用代理工具，或手动下载离线安装包进行安装。
七、进阶优化（可选）
- 本地模型部署：修改
.env文件中的MODEL_PROVIDER和API_KEY，支持本地运行 Llama、Qwen 等模型，完全脱离外网。 - 权限限制：在
config.json中设置allowed_commands和denied_commands，禁止机器人执行危险 shell 命令，提升安全性。
Docker 部署：适合需要 7×24 小时运行的用户，容器化部署更稳定：
git clone https://github.com/openclaw/openclaw.git
cd openclaw
docker compose up -d openclaw-gateway
汉化适配：国内用户建议安装社区汉化版，优化微信/企业微信支持：
npm install -g openclaw-cn@latest
八、注意事项
- 隐私安全：OpenClaw 默认本地部署，数据不上传，但建议 不要在装有重要商业/隐私数据的电脑上运行，可使用闲置设备或云端虚拟机（VPS）；
- 版本兼容：避免使用最新版（官方频繁更新易出问题），新手建议安装稳定版：
npm install -g [email protected]（替换为实际稳定版本号）； - 服务保活：本地部署时，关闭终端/PowerShell 会导致网关服务停止，可使用
pm2等工具实现后台保活。