附录J：飞书配置检查清单 -规范图集|经验交流-金瓦刀

✅ 使用本清单确保飞书Bot配置完整，避免常见问题

📋 配置前准备

已安装 OpenClaw（版本 2026.2.9+）
已注册飞书开放平台账号
已创建企业/团队（个人也可以）
网络可以访问飞书开放平台

🔧 应用创建（飞书开放平台）

1. 创建应用

登录飞书开放平台：https://open.feishu.cn
点击”创建企业自建应用”
填写应用信息：
- 应用名称（如：OpenClaw助手）
- 应用描述
- 应用图标
记录 App ID 和 App Secret

2. 配置机器人

进入”应用功能” → “机器人”
启用机器人功能
设置机器人名称
设置机器人描述
上传机器人头像

3. 配置权限（⭐ 重要）

在”权限管理”页面，添加以下权限：

必需权限（缺一不可）

im:message – 获取与发送单聊、群组消息
im:message:send_as_bot – 以应用身份发消息
contact:contact.base:readonly – 获取通讯录基本信息 ⭐

⚠️ 特别注意：contact:contact.base:readonly 是最容易遗漏的权限！

如果缺少此权限：

❌ 机器人无法识别用户

❌ 无法响应任何消息

❌ 日志中会出现 “User not found” 错误

可选权限（根据需要添加）

im:message:group_at_msg:readonly – 获取群组中@机器人的消息
im:message:group_msg:readonly – 获取群组消息
im:chat – 获取群组信息
contact:user.base:readonly – 获取用户详细信息

4. 配置事件订阅

在”事件订阅”页面：

选择”使用长连接接收事件”（WebSocket 模式）
添加事件：im.message.receive_v1（接收消息）
确认长连接状态显示”已连接”

💡 提示：如果长连接无法建立，请先完成下面的 OpenClaw 配置步骤

5. 发布应用

点击”版本管理与发布”
创建版本
填写版本说明
提交审核（企业自建应用通常自动通过）
确认应用状态为”已发布”

6. 设置可用范围

在”可用性”页面设置可用范围
添加可使用的部门或成员
或选择”全员可用”

💻 OpenClaw 配置

1. 添加飞书渠道

# 运行添加渠道命令
openclaw channels add

# 选择 Feishu
# 输入 App ID
# 输入 App Secret
```text
**检查配置**：
```bash
# 查看渠道列表
openclaw channels list

# 应该看到 feishu 渠道
```text
### 2. 启动网关

```bash
# 启动网关
openclaw gateway start

# 检查状态
openclaw gateway status

# 应该显示 "running"
```text
### 3. 验证配置

```bash
# 测试飞书连接
openclaw channels test feishu

# 应该显示连接成功
```text
---

## 🧪 测试验证

### 1. 基础测试

- [ ] 在飞书中搜索并添加机器人
- [ ] 发送消息："你好"
- [ ] 机器人应该回复

### 2. 功能测试

- [ ] 测试文本消息
- [ ] 测试文件发送（如果需要）
- [ ] 测试图片发送（如果需要）
- [ ] 测试群组消息（需要@机器人）

### 3. 权限测试

- [ ] 机器人能识别用户名
- [ ] 机器人能正常回复
- [ ] 访问控制正常工作（如果配置了）

---

## 🔍 故障排查

### 机器人不回复？

按以下顺序检查：

1. **检查权限（最常见问题）**
   ```text
   ✅ im:message
   ✅ im:message:send_as_bot
   ✅ contact:contact.base:readonly ⭐ 必需

检查事件订阅✅ 已选择"长连接"模式 ✅ 已添加 im.message.receive_v1 ✅ 长连接状态"已连接"
检查应用状态✅ 应用已发布 ✅ 应用已通过审核 ✅ 用户在可用范围内
检查 OpenClaw# 检查网关状态 openclaw gateway status # 查看日志 openclaw logs --follow # 检查渠道配置 openclaw channels list

查看详细日志

# 实时查看日志
openclaw logs --follow

# 过滤飞书相关日志
openclaw logs --follow | grep feishu

# 查看最近100行日志
openclaw logs --tail 100

常见错误及解决

错误信息	原因	解决方案
`Permission denied`	缺少权限	添加所有必需权限
`User not found`	缺少通讯录权限	添加 `contact:contact.base:readonly`
`Connection failed`	网关未启动	运行 `openclaw gateway start`
`Invalid app_id`	AppID错误	检查配置
`Long connection failed`	长连接失败	确保网关已启动再配置事件订阅