飞书平台接入基础

📋 准备工作

账号准备

• 飞书企业账号（个人版也可）
• 管理员权限或应用创建权限

开发者准备

• 了解基本的 API 概念
• 熟悉 JSON 数据格式
• 掌握基本的调试技能

🚀 创建飞书应用

1. 登录开发者平台

访问 飞书开放平台

2. 创建新应用

点击「创建应用」→ 选择「企业自建应用」

3. 填写应用信息

应用名称: OpenClaw Bot
应用描述: AI 自动化助手
应用图标: 上传自定义图标或使用默认

4. 获取关键信息

创建完成后记录以下信息：

• App ID: cli_a1b2c3d4e5f6789
• App Secret: gHIjKlMnOpQrStUvWxYz123456

⚠️ 安全提醒: App Secret 是敏感信息，请妥善保管

🔐 权限配置详解

核心必需权限

消息相关权限

[
  "im:message",           // 发送消息
  "im:message:send",      // 发送普通消息
  "im:message.p2p_msg",   // 发送私聊消息
  "im:message.group_msg"  // 发送群聊消息
]

联系人权限

[
  "contact:user.base:readonly",  // 读取用户基本信息
  "contact:department.base:readonly"  // 读取部门信息
]

应用管理权限

[
  "application:application"  // 应用基本信息访问
]

完整权限配置模板

# config.yaml 中的权限配置
channels:
  feishu:
    enabled: true
    appId: "cli_your_app_id_here"
    appSecret: "your_app_secret_here"
    domain: "feishu"  # 国内版用 feishu，国际版用 lark
    connectionMode: "websocket"  # 推荐使用 websocket
    
    # 消息策略配置
    dmPolicy: "pairing"      # 私聊策略：配对模式
    groupPolicy: "allowlist" # 群聊策略：白名单模式
    requireMention: true     # 群聊需要 @ 机器人
    
    # 性能配置
    mediaMaxMb: 30           # 媒体文件最大大小(MB)
    renderMode: "auto"       # 回复渲染模式

🔗 连接模式选择

WebSocket 模式（推荐）

优势：

• 实时性强
• 连接稳定
• 延迟低

适用场景：

• 需要实时响应的应用
• 高频交互场景

Webhook 模式

优势：

• 配置简单
• 不需要维持长连接
• 适合简单场景

适用场景：

• 低频消息处理
• 简单通知场景

⚙️ OpenClaw 配置步骤

1. 安装飞书插件

# 方法一：npm 安装（推荐）
openclaw plugins install @m1heng-clawd/feishu

# 方法二：升级现有插件
openclaw plugins update feishu

2. 配置应用信息

# 启动配置向导
openclaw config

# 或直接编辑配置文件
nano ~/.openclaw/config.yaml

3. 验证配置

# 检查配置状态
openclaw config:validate

# 测试连接
openclaw gateway:test

🔧 事件订阅配置

1. 配置事件回调地址

在飞书开发者后台：

1. 进入「事件订阅」页面
2. 添加请求地址 URL
3. 选择需要订阅的事件

2. 必需事件类型

✓ im.message.receive_v1  # 接收消息事件
✓ im.chat.disband_v1     # 解散群聊事件
✓ contact.user.updated_v3 # 用户信息变更

3. 加密配置

加密方式: AES-256-CBC
加密密钥: 从 OpenClaw 配置中获取

🧪 测试连接

1. 启动网关服务

# 启动服务
openclaw gateway

# 或在后台运行
openclaw gateway:start

2. 验证连接状态

# 检查服务状态
openclaw gateway:status

# 查看连接日志
openclaw gateway:logs

3. 发送测试消息

在飞书中：

1. 添加机器人到群聊
2. 发送测试消息：ping
3. 观察机器人回复

🛡️ 安全配置

IP 白名单设置

在飞书开发者后台配置服务器 IP 白名单

请求验证

// 验证飞书签名示例
const crypto = require('crypto');

function verifySignature(timestamp, nonce, signature, body) {
  const content = timestamp + nonce + body;
  const computedSignature = crypto
    .createHmac('sha256', APP_SECRET)
    .update(content)
    .digest('hex');
    
  return computedSignature === signature;
}

敏感信息保护

# 使用环境变量存储敏感信息
export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="xxx"

# 在配置中引用
appId: ${FEISHU_APP_ID}
appSecret: ${FEISHU_APP_SECRET}

📊 监控和日志

日志级别配置

logging:
  level: info  # debug/info/warn/error
  file: /var/log/openclaw/feishu.log
  maxSize: 100MB
  maxFiles: 5

关键指标监控

• 消息处理成功率
• 平均响应时间
• 连接稳定性
• 错误率统计

🆘 常见问题排查

连接失败

# 检查网络连通性
ping open.feishu.cn

# 验证证书
openssl s_client -connect open.feishu.cn:443

# 查看详细错误日志
openclaw gateway:logs --level debug

权限不足

1. 检查飞书后台权限配置
2. 确认所有必需权限已授权
3. 重新安装插件并重启服务

消息不响应

# 检查事件订阅配置
openclaw gateway:events

# 测试消息接收
openclaw gateway:test-message

# 查看处理链路
openclaw gateway:trace <message_id>

📚 最佳实践

配置管理

# 开发环境配置
cp config.yaml config.dev.yaml
openclaw config --env dev

# 生产环境配置
cp config.yaml config.prod.yaml
openclaw config --env prod

版本控制

# .gitignore 配置
.env
*.log
config.local.yaml
credentials/

自动化部署

# Docker 部署示例
version: '3'
services:
  openclaw:
    image: openclaw/openclaw:latest
    environment:
      - FEISHU_APP_ID=${FEISHU_APP_ID}
      - FEISHU_APP_SECRET=${FEISHU_APP_SECRET}
    ports:
      - "3000:3000"
    volumes:
      - ./config:/app/config

✅ 接入检查清单

完成接入后请检查：

• 应用创建成功并获取凭证
• 必需权限全部配置完成
• OpenClaw 插件安装成功
• 配置文件填写正确
• 网关服务正常启动
• 能够接收和发送消息
• 日志记录正常
• 安全配置到位

📖 下一步学习

成功接入后，建议学习：

1. 提示词工程进阶
2. 工作流设计模式
3. 技能包开发实战

遇到问题？参考 权限配置详解 或查看官方文档