OpenClaw 飞书机器人配置指南：实现多渠道 AI 助手集成

• 6.1 群白名单配置
• 6.2 群组功能开关
• 6.3 权限控制

一、前言

1.1 为什么需要配置飞书机器人？

OpenClaw 作为开源万能个人助理框架，支持多渠道通信。飞书（Lark）作为企业级协作平台，是集成 AI 助手的理想选择：

✅ 多渠道接入 - 支持私聊、群组、频道
✅ 富媒体交互 - 支持文本、图片、卡片、表情
✅ 企业级安全 - 完善的权限管理
✅ 开放 API - 丰富的集成能力

1.2 飞书机器人支持的功能

OpenClaw 的飞书扩展支持：

二、准备工作

2.1 环境要求

# 操作系统
# Linux (Ubuntu 20.04+ 推荐)
# macOS 12+
# Windows 10+ (WSL2 推荐)

# 基础环境
# Node.js 18+
# pnpm 8+
# Git

2.2 OpenClaw 安装

# 1. 克隆项目
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 2. 安装依赖
pnpm install

# 3. 配置环境变量
cp .env.example .env

# 4. 启动开发模式
pnpm dev

2.3 飞书账号要求

• ✅ 拥有飞书管理员权限
• ✅ 可访问 飞书开放平台
• ✅ 企业版或个人版飞书账号均可

三、飞书应用创建

3.1 创建企业应用

访问飞书开放平台

访问：https://open.feishu.cn/
登录你的飞书账号

此处点击右上角进入开发者后台。

创建应用

点击「创建企业应用」
填写应用名称：OpenClaw 助手
上传应用图标

1. 填写应用基本信息
   • 应用名称：OpenClaw 助手
   • 应用描述：基于 OpenClaw 的 AI 助手
   • 上传应用图标

2. 配置应用信息
   • 应用描述：基于 OpenClaw 的 AI 助手
   • 应用主页：可选填
   • 落地页：可选填

3.2 获取应用凭证

在应用详情页获取：

{
  "appId": "your_app_id_here",
  "appSecret": "your_app_secret_here"
}

⚠️ 注意：妥善保管 appSecret，泄露后需重新创建

3.3 开通权限

在「权限管理」中开通以下权限：

3.4 配置事件订阅

Webhook URL 配置

# 你的服务器地址
https://your-domain.com/api/feishu/webhook

订阅事件

必需事件：
├── im:message
│   └── 接收消息事件
└── im.chat
    └── 群组事件

3.5 发布应用

提交审核

审核时间：1-3 工作日
企业自建应用可无需审核

可见范围

• 全体成员
• 指定部门
• 指定用户

版本管理

版本号：v1.0.0
版本描述：首次发布

审核后看到发布成功，则 OK。

四、OpenClaw 配置

4.1 配置文件结构

openclaw/
├── .env # 环境变量
├── apps/
│   └── feishu/
│       └── config.ts # 飞书配置
└── extensions/
    └── feishu/
        └── src/
            ├── client.ts # 客户端
            ├── accounts.ts # 账号管理
            └── types.ts # 类型定义

4.2 环境变量配置

# .env 文件
# 飞书应用凭证
FEISHU_APP_ID=your_app_id
FEISHU_APP_SECRET=your_app_secret
# 飞书域名
FEISHU_DOMAIN=feishu
# 或 lark
# 连接模式
FEISHU_CONNECTION_MODE=websocket
# websocket | webhook
# Webhook 配置
FEISHU_WEBHOOK_PATH=/api/feishu/webhook
FEISHU_VERIFICATION_TOKEN=your_token

4.3 飞书配置文件

// apps/feishu/config.ts
export const FeishuConfig = {
  // 应用凭证
  credentials: {
    appId: process.env.FEISHU_APP_ID,
    appSecret: process.env.FEISHU_APP_SECRET,
  },
  // 域名配置
  domain: process.env.FEISHU_DOMAIN || 'feishu',
  // 连接模式
  connectionMode: process.env.FEISHU_CONNECTION_MODE || 'websocket',
  // Webhook 配置
  webhook: {
    path: process.env.FEISHU_WEBHOOK_PATH || '/api/feishu/webhook',
    verificationToken: process.env.FEISHU_VERIFICATION_TOKEN,
  },
  // 消息配置
  message: {
    maxLength: 20000,
    retryTimes: 3,
    retryInterval: 1000,
  },
  // 日志配置
  logging: {
    level: 'info',
    format: 'json',
  },
};

4.4 账号配置

// 支持多账号配置
export const feishuAccounts = [
  {
    accountId: 'main',
    appId: process.env.FEISHU_APP_ID,
    appSecret: process.env.FEISHU_APP_SECRET,
    enabled: true,
    configured: true,
    domain: 'feishu',
    connectionMode: 'websocket',
  },
  {
    accountId: 'lark',
    appId: 'your_lark_app_id',
    appSecret: 'your_lark_app_secret',
    enabled: false, // 暂不启用
    configured: false,
    domain: 'lark',
  },
];

五、核心配置详解

5.1 连接模式配置

WebSocket 模式（推荐）

// 实时双向通信
const wsConfig = {
  connectionMode: 'websocket',
  heartbeatInterval: 30000, // 30 秒心跳
  reconnectInterval: 5000, // 断线重连间隔
  maxReconnectAttempts: 10, // 最大重连次数
};

Webhook 模式

// 被动接收消息
const webhookConfig = {
  connectionMode: 'webhook',
  path: '/api/feishu/webhook',
  methods: ['POST'],
};

5.2 消息类型支持

// 支持的消息类型
const supportedMessageTypes = [
  'text', // 纯文本
  'image', // 图片
  'file', // 文件
  'audio', // 语音
  'video', // 视频
  'rich_text', // 富文本
  'card', // 卡片消息
  'interactive', // 交互卡片
];

5.3 消息发送配置

// apps/feishu/src/send.ts
export interface FeishuMessageInfo {
  messageId: string; // 消息 ID
  chatId: string; // 会话 ID
  senderId?: string; // 发送者 ID
  messageType: string; // 消息类型
  content: string; // 消息内容
  timestamp: number; // 时间戳
}

// 发送富文本消息
const sendRichText = async (chatId: string, markdown: string) => {
  await client.sendMessage({
    receiveId: chatId,
    msgType: 'rich_text',
    content: JSON.stringify({
      rich_text: {
        elements: [
          {
            type: 'text',
            text: markdown,
          },
        ],
      },
    }),
  });
};

六、群组策略配置

6.1 群白名单配置

// 配置允许使用机器人的群组
export const groupPolicy = {
  // 白名单模式
  allowlist: {
    enabled: true,
    mode: 'whitelist', // whitelist | blacklist
    // 匹配方式
    matchSource: 'id', // id | name | wildcard
    // 允许的群组 ID 列表
    allowedGroups: [
      'oc_xxxxxxxxxxxxx', // 群组 ID
    ],
    // 匹配规则
    matchRules: {
      // 群名匹配（支持通配符）
      namePatterns: ['AI-*', '测试群'],
    },
  },
  // 默认策略
  defaultPolicy: {
    allowed: true, // 默认允许
    responseMention: true, // 是否@回复用户
    typingIndicator: true, // 显示"正在输入"
  },
};

6.2 群组功能开关

// 群组功能配置
export const groupFeatures = {
  // 是否允许机器人被@时回复
  mentionReply: {
    enabled: true,
    prefix: '@你的名字', // 机器人昵称
  },
  // 是否允许私聊模式
  privateChat: {
    enabled: true,
    requireFollow: false, // 是否需要先关注
  },
  // 文档功能
  document: {
    enabled: true,
    read: true,
    write: true,
    create: true,
  },
  // 媒体功能
  media: {
    upload: true,
    download: true,
    maxSize: 20 * 1024 * 1024, // 20MB
  },
};

6.3 权限控制

// 用户权限配置
export const userPermissions = {
  // 管理员（可配置机器人）
  admins: [
    'ou_xxxxxxxxxxxxx', // 用户 OpenID
  ],
  // 普通用户权限
  user: {
    canUse: true,
    dailyLimit: 100, // 每日限额
    canUpload: true,
    maxFileSize: 10 * 1024 * 1024,
  },
  // 匿名用户权限
  anonymous: {
    canUse: false,
  },
};

七、功能测试

7.1 基础功能测试

测试 1：私聊对话

# 步骤 1：在飞书中搜索机器人并发起对话
# 步骤 2：发送测试消息
你好，OpenClaw！
# 预期回复
你好！我是 OpenClaw AI 助手。有什么可以帮助你的吗？

测试 2：群组@互动

# 步骤 1：将机器人拉入群组
# 步骤 2：@机器人并提问
@OpenClaw 帮我总结今天的新闻
# 预期回复
今天的主要新闻：
1. xxx
2. xxx
3. xxx

7.2 高级功能测试

测试 3：飞书文档操作

# 测试文档读写功能
## 读文档
@OpenClaw 读取文档 [文档 ID]
## 写文档
@OpenClaw 在文档 [ID] 中添加以下内容：
## 新增章节
- 项目进度更新
- 明日工作计划

测试 4：文件传输

# 测试文件上传下载
## 上传图片
@OpenClaw 上传图片 [图片文件]
## 下载文件
@OpenClaw 下载这个文件

7.3 测试用例表

八、常见问题

Q1: WebSocket 连接失败？

问题描述：

Error: WebSocket connection failed

解决方案：

# 1. 检查网络连通性
ping open.feishu.cn
# 2. 检查防火墙设置
sudo ufw status
# 3. 检查 WebSocket 端口
netstat -tlnp | grep 443
# 4. 查看详细日志
FEISHU_LOG_LEVEL=debug pnpm dev

Q2: 消息发送失败？

问题描述：

Error: Failed to send message

解决方案：

// 1. 检查消息长度
if (message.length > 20000) {
  // 拆分成多条消息发送
}
// 2. 检查频率限制
// 飞书默认限制：60 条/分钟
// 3. 添加重试机制
const sendWithRetry = async (message, retries = 3) => {
  for (let i = 0; i < retries; i++) {
    try {
      return await sendMessage(message);
    } catch (e) {
      if (i === retries - 1) throw e;
      await sleep(1000 * (i + 1));
    }
  }
};

Q3: 机器人无响应？

排查步骤：

# 1. 检查机器人是否启用
curl http://localhost:3000/api/feishu/status
# 2. 检查事件是否正常
curl http://localhost:3000/api/feishu/events
# 3. 查看运行日志
tail -f logs/feishu.log

Q4: 权限不足？

问题描述：

Error: Permission denied

解决方案：

# 1. 确认已开通所有必要权限
# 2. 确认应用已发布
# 3. 确认用户已在可见范围内

Q5: 文档操作失败？

问题描述：

Error: Document operation failed

解决方案：

// 检查文档权限
const checkDocPermission = async (docId: string) => {
  const doc = await client.doc.get({
    document_id: docId,
  });
  if (!doc.readable) {
    throw new Error('文档无读取权限');
  }
  if (!doc.writable) {
    throw new Error('文档无写入权限');
  }
};

九、进阶技巧

9.1 多账号配置

// 同时连接飞书和 Lark
export const multiAccount = {
  accounts: [
    {
      name: '飞书',
      domain: 'feishu',
      config: feishuConfig,
    },
    {
      name: 'Lark',
      domain: 'lark',
      config: larkConfig,
      enabled: false, // 暂不启用
    },
  ],
  // 负载均衡
  loadBalancing: 'round_robin', // 轮询 | 随机
};

9.2 自定义消息卡片

// 发送交互式卡片
const sendCard = async (chatId: string) => {
  await client.sendMessage({
    receiveId: chatId,
    msgType: 'interactive',
    content: JSON.stringify({
      card: {
        config: {
          wide_screen_mode: true,
          enable_forward: true,
        },
        elements: [
          {
            tag: 'div',
            fields: [
              {
                is_short: false,
                text: {
                  tag: 'lark_md',
                  content: '**AI 助手回复**\n你好！有什么可以帮你？',
                },
              },
            ],
          },
          {
            tag: 'action',
            actions: [
              {
                tag: 'button',
                text: {
                  tag: 'plain_text',
                  content: '继续对话',
                },
                type: 'primary',
                action_id: 'continue_chat',
              },
              {
                tag: 'button',
                text: {
                  tag: 'plain_text',
                  content: '结束对话',
                },
                type: 'default',
                action_id: 'end_chat',
              },
            ],
          },
        ],
      },
    }),
  });
};

9.3 消息缓存策略

// 消息缓存配置
export const messageCache = {
  enabled: true,
  maxSize: 1000,
  ttl: 3600, // 1 小时
  strategy: 'lru', // LRU 缓存
  // 缓存操作
  get: async (key: string) => {},
  set: async (key: string, value: any) => {},
  delete: async (key: string) => {},
  clear: async () => {},
};

9.4 性能优化

// 性能配置
export const performance = {
  // 并发限制
  maxConcurrent: 10,
  // 请求队列
  queueSize: 100,
  // 消息批处理
  batching: {
    enabled: true,
    maxBatchSize: 10,
    maxWaitTime: 100, // 毫秒
  },
  // 数据库连接池
  pool: {
    min: 2,
    max: 10,
  },
};

9.5 日志与监控

// 结构化日志
export const logging = {
  level: 'info',
  format: 'json',
  // 日志字段
  fields: {
    traceId: true,
    userId: true,
    chatId: true,
    messageId: true,
    timestamp: true,
  },
  // 日志输出
  outputs: [
    {
      type: 'console',
      level: 'info',
    },
    {
      type: 'file',
      level: 'info',
      path: './logs/feishu.log',
      rotation: 'daily',
    },
    {
      type: 'remote',
      level: 'warn',
      endpoint: 'https://your-log-service.com',
    },
  ],
};

十、总结

10.1 配置要点回顾

1. ✅ 创建飞书企业应用
2. ✅ 获取并保管好应用凭证
3. ✅ 开通必要权限
4. ✅ 配置环境变量
5. ✅ 选择连接模式（推荐 WebSocket）
6. ✅ 配置群组白名单
7. ✅ 测试各功能模块