夜雨聆风> 🦞 OpenClaw 是一个个人 AI 助手，可以部署在本地并通过飞书等平台与你对话。本文档将带你从零开始完成安装、配置和调试。
**适用人群**：技术小白也能看懂的详细指南
**预计时间**：30-60 分钟
**系统要求**：macOS / Linux / Windows (WSL2)
---
## 📋 目录
1. [环境准备](#1-环境准备)
2. [安装 OpenClaw](#2-安装-openclaw)
3. [配置 Qwen 模型](#3-配置-qwen-模型)
4. [配置飞书机器人](#4-配置飞书机器人)
5. [启动 Gateway](#5-启动-gateway)
6. [测试与调试](#6-测试与调试)
7. [常见问题](#7-常见问题)
---
## 1. 环境准备
### 1.1 检查 Node.js 版本
OpenClaw 需要 **Node.js ≥ 22.16.0**。
```bash
node --version
```
如果版本低于 22.16.0，需要升级：
#### macOS 升级 Node.js
```bash
# 使用 n 工具升级（推荐）
npx n latest
# 升级后验证
node --version # 应显示 v22.16.0 或更高
```
#### 或者使用官方安装包
访问 [Node.js 官网](https://nodejs.org/) 下载最新 LTS 版本安装。
### 1.2 安装 pnpm
pnpm 是推荐的包管理器：
```bash
npm install -g pnpm
pnpm --version # 验证安装
```
---
## 2. 安装 OpenClaw
### 2.1 克隆项目
```bash
cd ~
git clone https://github.com/openclaw/openclaw.git
cd openclaw
```
### 2.2 安装依赖
```bash
pnpm install
```
安装过程约需 5-10 分钟，请耐心等待。
### 2.3 构建项目
```bash
pnpm build
```
构建成功后会显示 `Done` 字样。
---
## 3. 配置 Qwen 模型
### 3.1 获取阿里云 DashScope API Key
1. 访问 [阿里云百炼平台](https://bailian.console.aliyun.com/)
2. 登录阿里云账号
3. 进入 **API-KEY 管理** 页面
4. 点击 **创建新的 API-KEY**
5. 复制生成的 API Key（格式：`sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`）
> 💰 **费用说明**：新用户有免费额度，qwen3.5-plus 约 0.002 元/千 tokens
### 3.2 创建配置文件
创建配置目录：
```bash
mkdir -p ~/.openclaw
```
创建配置文件 `~/.openclaw/openclaw.json`：
```bash
cat > ~/.openclaw/openclaw.json << 'EOF'
{
"gateway": {
"mode": "local",
"auth": {
"mode": "token",
"token": "openclaw-dev-token-2026"
},
"bind": "loopback",
"port": 18789
},
"env": {
"MODELSTUDIO_API_KEY": "sk-你的 API_KEY_替换这里"
},
"models": {
"providers": {
"modelstudio": {
"baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"api": "openai-completions",
"models": [
{
"id": "qwen3.5-plus",
"name": "qwen3.5-plus",
"reasoning": false,
"input": ["text", "image"],
"contextWindow": 1000000,
"maxTokens": 65536
}
]
}
}
},
"agents": {
"defaults": {
"model": "modelstudio/qwen3.5-plus"
}
},
"browser": {
"enabled": true,
"color": "#FF4500"
}
}
EOF
```
> ⚠️ **重要**：将 `sk-你的 API_KEY_替换这里` 替换为你实际的 API Key
### 3.3 验证模型配置
```bash
cd ~/openclaw
/Users/qiwen/.n/bin/node dist/index.js models status
```
应显示 `modelstudio effective=env:sk-xxx` 表示配置成功。
---
## 4. 配置飞书机器人
### 4.1 创建飞书应用
1. 访问 [飞书开放平台](https://open.feishu.cn/app)
2. 点击 **创建企业应用**
3. 填写应用信息：
- 应用名称：例如 "OpenClaw 助手"
- 应用图标：可选
4. 点击 **创建**
### 4.2 获取应用凭证
1. 进入创建的应用
2. 点击 **凭证与基础信息**
3. 复制以下信息：
- **App ID**（格式：`cli_xxx`）
- **App Secret**
> ⚠️ **重要**：App Secret 只显示一次，请妥善保存！
### 4.3 配置应用权限
在 **权限管理** 页面：
1. 点击 **批量导入**
2. 粘贴以下 JSON：
```json
{
"scopes": {
"tenant": [
"im:message",
"im:message:send_as_bot",
"im:message.group_at_msg:readonly",
"im:message.p2p_msg:readonly",
"im:message:readonly",
"im:chat.access_event.bot_p2p_chat:read",
"im:chat.members:bot_access"
],
"user": []
}
}
```
3. 点击 **申请权限** 并 **开通**
### 4.4 启用机器人功能
1. 点击 **应用功能** > **机器人**
2. 开启 **机器人** 开关
3. 设置机器人名称和头像
4. 点击 **保存**
### 4.5 配置事件订阅
1. 点击 **事件订阅**
2. 选择 **使用长连接接收事件** (WebSocket)
3. 点击 **添加事件**
4. 搜索并添加：`im.message.receive_v1`
5. 点击 **保存**
### 4.6 发布应用
1. 点击 **版本管理与发布**
2. 点击 **创建版本**
3. 填写版本号（如 1.0.0）和更新说明
4. 点击 **提交发布**
5. 等待审核（通常自动通过）
### 4.7 配置 OpenClaw 飞书集成
编辑 `~/.openclaw/openclaw.json`，添加飞书配置：
```json
{
"channels": {
"feishu": {
"enabled": true,
"appId": "你的 App_ID_替换这里",
"appSecret": "你的 App_Secret_替换这里",
"domain": "feishu",
"connectionMode": "websocket",
"dmPolicy": "pairing"
}
}
}
```
> ⚠️ **重要**：替换 `appId` 和 `appSecret` 为你的实际值
完整配置文件示例：
```json
{
"gateway": {
"mode": "local",
"auth": {
"mode": "token",
"token": "openclaw-dev-token-2026"
},
"bind": "loopback",
"port": 18789
},
"env": {
"MODELSTUDIO_API_KEY": "sk-你的 API_KEY"
},
"models": {
"providers": {
"modelstudio": {
"baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"api": "openai-completions",
"models": [
{
"id": "qwen3.5-plus",
"name": "qwen3.5-plus",
"reasoning": false,
"input": ["text", "image"],
"contextWindow": 1000000,
"maxTokens": 65536
}
]
}
}
},
"channels": {
"feishu": {
"enabled": true,
"appId": "cli_xxxx",
"appSecret": "xxxx",
"domain": "feishu",
"connectionMode": "websocket",
"dmPolicy": "pairing"
}
},
"agents": {
"defaults": {
"model": "modelstudio/qwen3.5-plus"
}
},
"browser": {
"enabled": true,
"color": "#FF4500"
}
}
```
---
## 5. 启动 Gateway
Gateway 是 OpenClaw 的核心服务，负责处理消息和 AI 对话。
### 5.1 启动 Gateway
```bash
cd ~/openclaw
/Users/qiwen/.n/bin/node dist/index.js gateway --port 18789
```
启动成功后，终端会显示 Gateway 运行信息。
> 💡 **提示**：保持此终端窗口打开，Gateway 需要持续运行
### 5.2 验证 Gateway 状态
打开新终端窗口，运行：
```bash
lsof -i :18789
```
应显示端口 18789 正在监听。
---
## 6. 测试与调试
### 6.1 命令行测试
在飞书配置前，可以先通过命令行测试 AI：
```bash
cd ~/openclaw
/Users/qiwen/.n/bin/node dist/index.js agent --session-id test001 --message "你好，请介绍一下你自己"
```
应看到 AI 回复内容。
### 6.2 飞书消息测试
1. 打开飞书 App
2. 搜索你的机器人名称
3. 点击进入聊天窗口
4. 发送消息："你好"
### 6.3 处理配对请求（重要！）
首次收到消息时，由于安全设置，需要管理员批准：
```bash
# 查看配对请求
cd ~/openclaw
/Users/qiwen/.n/bin/node dist/index.js pairing list
# 批准配对（替换 CODE 为实际配对码）
/Users/qiwen/.n/bin/node dist/index.js pairing approve feishu CODE
```
### 6.4 查看消息记录
```bash
# 查看会话列表
/Users/qiwen/.n/bin/node dist/index.js sessions
# 查看配对记录
cat ~/.openclaw/credentials/feishu-pairing.json
# 查看允许列表
cat ~/.openclaw/credentials/feishu-default-allowFrom.json
```
---
## 7. 常见问题
### 7.1 机器人不回复消息
**问题**：发送消息后机器人没有回复
**排查步骤**：
1. **检查配对状态**
```bash
/Users/qiwen/.n/bin/node dist/index.js pairing list
```
如有待批准请求，执行批准命令
2. **检查 Gateway 是否运行**
```bash
lsof -i :18789
```
如无输出，重启 Gateway
3. **检查飞书权限**
- 访问 https://open.feishu.cn/app/你的 AppID
- 确认已添加 `im:message` 和 `im:message:send_as_bot` 权限
- 确认应用已发布
4. **查看会话记录**
```bash
cat ~/.openclaw/agents/main/sessions/*.jsonl | tail -50
```
查看消息是否到达和 AI 是否生成回复
### 7.2 API Key 无效（401 错误）
**错误信息**：`HTTP 401: invalid access token or token expired`
**解决方案**：
1. 确认 API Key 正确（无多余空格）
2. 确认使用正确的 endpoint：
```json
"baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1"
```
3. 在阿里云百炼平台确认 API Key 状态正常
4. 确认账户有可用额度
### 7.3 飞书权限错误（400 错误）
**错误信息**：`Access denied. One of the following scopes is required`
**解决方案**：
1. 访问飞书开放平台权限申请链接（错误信息中提供）
2. 添加所需权限
3. **发布应用**（必须步骤！）
4. 等待 1-2 分钟生效
### 7.4 Node.js 版本过低
**错误信息**：`openclaw requires Node >=22.16.0`
**解决方案**：
```bash
# 使用 n 升级
npx n latest
# 或使用官方安装包
# 访问 https://nodejs.org/ 下载最新版
```
### 7.5 Gateway 无法启动
**可能原因**：
- 端口被占用
- 配置文件格式错误
**解决方案**：
```bash
# 检查端口占用
lsof -i :18789
# 如有占用，停止旧进程
pkill -f "openclaw-gateway"
# 验证配置文件
cat ~/.openclaw/openclaw.json | python -m json.tool
```
### 7.6 消息已读但无回复
查看会话记录确认 AI 是否生成回复：
```bash
# 查看最新会话
ls -lt ~/.openclaw/agents/main/sessions/*.jsonl | head -3
# 查看会话内容
tail -20 ~/.openclaw/agents/main/sessions/最新会话文件.jsonl
```
如 AI 已生成回复但未发送，检查飞书权限配置。
---
## 📚 参考资源
- [OpenClaw 官方文档](https://docs.openclaw.ai)
- [飞书开放平台](https://open.feishu.cn)
- [阿里云百炼平台](https://bailian.console.aliyun.com)
- [Node.js 下载](https://nodejs.org)
---
## 🎉 完成！
恭喜你成功配置 OpenClaw + 飞书机器人！现在你可以：
- 在飞书中与 AI 助手对话
- 通过命令行测试各种功能
- 配置更多聊天渠道（Telegram、Discord 等）
- 开发和添加自定义技能
如有问题，欢迎查阅官方文档或提交 Issue。🦞