OpenClaw 飞书通信端机器人配置指南

一、前言

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

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

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

1.2 飞书机器人支持的功能

OpenClaw 的飞书扩展支持：

功能	说明
私聊对话	与 AI 助手 1 对 1 交流
群组互动	群聊中@机器人对话
文档操作	飞书云文档读写
表情回应	支持各类消息互动
Webhook	实时消息推送
双模式	WebSocket / Webhook

二、准备工作

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 助手，上传应用图标。

填写应用基本信息
- 应用名称：OpenClaw 助手
- 应用描述：基于 OpenClaw 的 AI 助手
- 上传应用图标
配置应用信息
- 应用描述：基于 OpenClaw 的 AI 助手
- 应用主页：可选填
- 落地页：可选填

3.2 获取应用凭证

在应用详情页获取：

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

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

3.3 开通权限

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

权限名称	权限说明	必要性
im:message	发送和接收消息	⭐ 必选
im:chat	群组管理	⭐ 必选
im:contact	联系人读取	⭐ 必选
doc:document	云文档读写	🔸 可选
drive:file	云空间文件	🔸 可选
approval:instance	审批流程	🔸 可选

3.4 配置事件订阅

Webhook URL 配置

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

订阅事件

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

3.5 发布应用

提交审核

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

可见范围

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

版本管理

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

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

四、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 测试用例表

测试项	测试步骤	预期结果	实际结果
私聊对话	发送"你好"	回复欢迎语	✅
群组@互动	@机器人提问	AI 回复	✅
文档读取	请求读取文档	返回文档内容	✅
文档写入	添加内容	内容成功添加	✅
图片发送	发送图片	图片正常显示	✅
文件上传	上传文件	文件上传成功	✅
断线重连	断开网络后重连	自动重连成功	✅
高频测试	连续发送 10 条	全部正常回复	✅

文章配图

八、常见问题

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',
                : {
                  : ,
                  : ,
                },
                : ,
                : ,
              },
            ],
          },
        ],
      },
    }),
  });
};

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 配置要点回顾

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

OpenClaw 飞书通信端机器人配置指南

一、前言

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

1.2 飞书机器人支持的功能

二、准备工作

2.1 环境要求

2.2 OpenClaw 安装

2.3 飞书账号要求

三、飞书应用创建

3.1 创建企业应用

3.2 获取应用凭证

3.3 开通权限

3.4 配置事件订阅

Webhook URL 配置

订阅事件

3.5 发布应用

四、OpenClaw 配置

4.1 配置文件结构

4.2 环境变量配置

4.3 飞书配置文件

4.4 账号配置

五、核心配置详解

5.1 连接模式配置

WebSocket 模式（推荐）

Webhook 模式

5.2 消息类型支持

5.3 消息发送配置

六、群组策略配置

6.1 群白名单配置

6.2 群组功能开关

6.3 权限控制

七、功能测试

7.1 基础功能测试

测试 1：私聊对话

测试 2：群组@互动

7.2 高级功能测试

测试 3：飞书文档操作

测试 4：文件传输

7.3 测试用例表

八、常见问题

Q1: WebSocket 连接失败？

Q2: 消息发送失败？

Q3: 机器人无响应？

Q4: 权限不足？

Q5: 文档操作失败？

九、进阶技巧

9.1 多账号配置

9.2 自定义消息卡片

9.3 消息缓存策略

9.4 性能优化

9.5 日志与监控

十、总结

10.1 配置要点回顾

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具