刘炳琦1. OpenClaw 是什么？为什么需要保姆级安装教程？
OpenClaw 是一款基于 AI 技术的自动化工具，主要用于实现 Windows 系统与飞书等办公平台的深度集成。它能够通过简单的配置，将各种 AI 能力（如大语言模型）接入到日常办公场景中，实现智能问答、文档处理、自动化流程等功能。
为什么需要保姆级安装教程？因为在实际部署过程中，我们发现很多用户会遇到以下典型问题：
- 环境依赖复杂（需要 Node.js、Python 等多种运行环境）
- 权限配置容易出错（特别是 Windows 系统的权限管理）
- 飞书 API 对接步骤繁琐（需要获取多个密钥和配置项）
- 错误提示不友好（很多报错信息对新手不明确）
我在帮三个不同团队部署 OpenClaw 的过程中，总结出了一套能避开 90% 常见坑的安装方法。下面就从最基础的环境准备开始，手把手带你完成整个安装流程。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 安装前的环境检查与准备
2.1 系统要求确认
首先确保你的 Windows 系统满足以下条件：
- 操作系统：Windows 10 或更高版本（建议 21H2 及以上）
- 内存：至少 8GB（运行大模型需要 16GB 以上）
- 存储空间：至少 20GB 可用空间
重要提示：很多安装失败案例都是因为使用了家庭版 Windows。建议使用专业版或企业版，某些系统级功能需要管理员权限。
2.2 必备软件安装
按顺序安装这些基础软件（版本很关键）：
-
Node.js：
- 必须安装 16.x 或 18.x LTS 版本
- 安装时勾选 "Automatically install the necessary tools" 选项
- 安装完成后执行：
bash复制
应该显示类似 v16.20.2 和 8.19.4 的版本号node -v npm -v
-
Python：
- 推荐 3.8 或 3.9 版本（3.10+ 可能有兼容性问题）
- 安装时务必勾选 "Add Python to PATH"
- 验证安装：
bash复制
python --version pip --version
-
Git：
- 使用默认选项安装即可
- 验证：
bash复制
git --version
2.3 飞书开发者账号准备
- 登录飞书开放平台
- 创建自建应用（选择"企业自建应用"）
- 记录以下关键信息：
- App ID
- App Secret
- 加密密钥（Encrypt Key）
- 验证令牌（Verification Token）
实测经验：很多人在这一步会漏掉加密密钥。如果后续出现 400 错误，80% 的概率是这里配置不全。
3. OpenClaw 核心安装步骤
3.1 获取安装包
推荐通过 Git 克隆最新代码：
bash复制git clone https://github.com/openclaw/openclaw.git
cd openclaw
如果网络有问题，也可以直接下载 ZIP 包，但要注意：
- 解压路径不要包含中文或空格
- 解压后需要手动执行
npm install
3.2 依赖安装
在项目目录下执行：
bash复制npm install
常见问题处理：
| 错误类型 | 解决方案 |
|---|---|
| node-gyp 报错 | 以管理员身份运行 PowerShell，执行 npm install --global windows-build-tools |
| Python 找不到 | 确认 Python 已加入 PATH，或显式指定路径：npm config set python "C:\path\to\python.exe" |
| 权限不足 | 右键点击命令行图标，选择"以管理员身份运行" |
3.3 配置文件修改
复制示例配置文件：
bash复制cp config.example.yaml config.yaml
需要修改的关键配置项：
yaml复制feishu:
app_id: "你的飞书App ID"
app_secret: "你的飞书App Secret"
encrypt_key: "你的加密密钥"
verification_token: "你的验证令牌"
model:
type: "ollama" # 也可以是 openai、azure 等
api_base: "http://localhost:11434" # ollama默认地址
model_name: "llama2" # 使用的模型名称
避坑指南：yml 文件对缩进极其敏感！建议使用 VS Code 等专业编辑器，不要用记事本修改。
4. 飞书对接与权限配置
4.1 飞书应用权限配置
在飞书开发者后台，需要为应用开启以下权限：
- 获取用户 user ID
- 获取用户邮箱
- 发送消息
- 接收消息
特别注意：
- 必须设置"事件订阅"中的请求网址（填写你的服务器地址）
- 在"权限管理"中开启所有用到的权限
- 发布版本后要等待约 5 分钟生效
4.2 本地端口转发
由于飞书需要回调你的本地服务，推荐使用 ngrok 进行内网穿透：
bash复制npm install -g ngrok
ngrok http 3000
将生成的 https 地址（如 https://abc123.ngrok.io）填写到飞书后台的"事件订阅"和"机器人"配置中。
5. 启动与验证
5.1 启动服务
bash复制npm start
正常启动会看到类似输出：
code复制[OpenClaw] Server running on port 3000
[Model] Connected to Ollama at http://localhost:11434
[Feishu] Webhook registered successfully
5.2 常见启动问题排查
| 错误信息 | 解决方案 |
|---|---|
could not start the cli |
检查 Node.js 版本是否为 16+/18+ LTS |
gateway closed before connect |
检查端口是否被占用（netstat -ano） |
got exception 400 |
检查飞书配置的四个密钥是否正确 |
ECONNREFUSED |
确认模型服务（如 Ollama）已启动 |
5.3 功能测试
- 在飞书中 @你的机器人，发送"测试"
- 应该能收到自动回复
- 尝试提问一些简单问题，验证 AI 功能
6. 进阶配置与优化
6.1 接入不同大模型
OpenClaw 支持多种模型后端配置：
yaml复制# 使用 OpenAI
model:
type: "openai"
api_key: "sk-xxx"
model_name: "gpt-4"
# 使用 Azure OpenAI
model:
type: "azure"
api_base: "https://your-resource.openai.azure.com"
api_key: "azure-api-key"
deployment_name: "your-deployment"
6.2 持久化部署建议
生产环境建议：
- 使用 PM2 管理进程：
bash复制npm install -g pm2 pm2 start npm --name "openclaw" -- start pm2 save pm2 startup - 配置 Nginx 反向代理
- 设置 HTTPS 证书
6.3 性能监控
可以添加以下监控脚本（保存为 monitor.js）：
javascript复制const { exec } = require('child_process');
setInterval(() => {
exec('netstat -ano | findstr 3000', (err, stdout) => {
if (!stdout.includes('LISTENING')) {
console.error('Service down! Restarting...');
exec('pm2 restart openclaw');
}
});
}, 60000);
7. 我踩过的三个大坑
-
编码问题：Windows 默认是 GBK 编码，而飞书使用 UTF-8。解决方案是在启动脚本前设置：
bash复制set NODE_OPTIONS=--loader ts-node/esm --experimental-specifier-resolution=node chcp 65001 -
内存泄漏：长时间运行后响应变慢。通过增加 Node.js 内存限制解决：
bash复制
node --max-old-space-size=4096 server.js -
多账号冲突：一个 OpenClaw 实例不能同时对接多个飞书账号。需要为每个账号单独部署实例，或者使用商业版。
最后分享一个实用技巧：在 config.yaml 中添加以下配置可以大幅提升响应速度：
yaml复制cache:
enabled: true
ttl: 300 # 5分钟缓存