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

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

4. 配置事件订阅

Webhook URL 配置

https://your-domain.com/api/feishu/webhook

订阅事件

必需事件包括：

• im:message：接收消息事件
• im.chat：群组事件

5. 发布应用

提交审核（企业自建应用通常无需审核），设置可见范围为全体成员或指定部门用户。版本号建议标记为 v1.0.0。

四、OpenClaw 配置

1. 配置文件结构

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

2. 环境变量配置

在 .env 文件中配置飞书应用凭证及连接参数：

# 飞书应用凭证
FEISHU_APP_ID=your_app_id
FEISHU_APP_SECRET=your_app_secret

# 飞书域名 (feishu 或 lark)
FEISHU_DOMAIN=feishu

# 连接模式 (websocket | webhook)
FEISHU_CONNECTION_MODE=websocket

# Webhook 配置
FEISHU_WEBHOOK_PATH=/api/feishu/webhook
FEISHU_VERIFICATION_TOKEN=your_token

3. 飞书配置文件

在 apps/feishu/config.ts 中定义配置对象，注意从环境变量读取敏感信息：

// 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. 账号配置

支持多账号配置，例如同时连接飞书和 Lark：

// 支持多账号配置
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',
  },
];

五、核心配置详解

1. 连接模式配置

WebSocket 模式（推荐）

适用于实时双向通信场景，配置心跳与重连策略：

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

Webhook 模式

适用于被动接收消息场景，需确保服务器能接收 POST 请求：

const webhookConfig = {
  connectionMode: 'webhook',
  path: '/api/feishu/webhook',
  methods: ['POST'],
};

2. 消息类型支持

系统支持多种消息格式，包括纯文本、图片、文件、语音、视频、富文本及交互卡片。

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

3. 消息发送配置

发送富文本消息时，需注意内容长度限制及 JSON 序列化：

// apps/feishu/src/send.ts
export interface FeishuMessageInfo {
  messageId: string;
  chatId: string;
  senderId?: string;
  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 },
        ],
      },
    }),
  });
};

六、群组策略配置

1. 群白名单配置

通过白名单控制哪些群组可以使用机器人，支持 ID 匹配或名称通配符：

export const groupPolicy = {
  allowlist: {
    enabled: true,
    mode: 'whitelist', // whitelist | blacklist
    matchSource: 'id', // id | name | wildcard
    allowedGroups: ['oc_xxxxxxxxxxxxx'],
    matchRules: {
      namePatterns: ['AI-*', '测试群'],
    },
  },
  defaultPolicy: {
    allowed: true,
    responseMention: true,
    typingIndicator: true,
  },
};

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
  },
};

3. 权限控制

区分管理员与普通用户的权限，防止滥用：

export const userPermissions = {
  admins: ['ou_xxxxxxxxxxxxx'],
  user: {
    canUse: true,
    dailyLimit: 100,
    canUpload: true,
    maxFileSize: 10 * 1024 * 1024,
  },
  anonymous: {
    canUse: false,
  },
};

七、功能测试

1. 基础功能测试

• 私聊对话：搜索机器人发起对话，发送'你好，OpenClaw！'预期收到欢迎语。
• 群组@互动：将机器人拉入群组，@机器人提问，观察 AI 回复。

2. 高级功能测试

• 飞书文档操作：尝试@机器人读取或写入飞书云文档。
• 文件传输：测试上传图片及下载文件功能。

3. 测试用例表

八、常见问题

Q1: WebSocket 连接失败？

检查网络连通性 (ping open.feishu.cn)、防火墙设置 (sudo ufw status) 及端口监听情况 (netstat -tlnp | grep 443)。开启调试日志查看具体错误：FEISHU_LOG_LEVEL=debug pnpm dev。

Q2: 消息发送失败？

确认消息长度未超过 20000 字符限制，注意飞书默认频率限制（60 条/分钟）。建议添加重试机制处理临时网络波动。

Q3: 机器人无响应？

检查机器人状态接口 (curl http://localhost:3000/api/feishu/status) 及事件订阅是否正常 (curl http://localhost:3000/api/feishu/events)，查看运行日志 (tail -f logs/feishu.log)。

Q4: 权限不足？

确认已开通所有必要权限，应用已发布，且调用用户在应用可见范围内。

Q5: 文档操作失败？

检查文档权限，确保应用具有读写权限。代码层面可添加权限校验逻辑：

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('文档无写入权限');
};

九、进阶技巧

1. 多账号配置

可同时连接飞书和 Lark，通过负载均衡策略分发请求：

export const multiAccount = {
  accounts: [
    { name: '飞书', domain: 'feishu', config: feishuConfig },
    { name: 'Lark', domain: 'lark', config: larkConfig, enabled: false },
  ],
  loadBalancing: 'round_robin',
};

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 助手回复**' } }] },
          { tag: 'action', actions: [{ tag: 'button', text: { tag: 'plain_text', content: '继续对话' }, type: 'primary', action_id: 'continue_chat' }] },
        ],
      },
    }),
  });
};

3. 消息缓存策略

启用 LRU 缓存减少重复请求，配置过期时间与最大容量：

export const messageCache = {
  enabled: true,
  maxSize: 1000,
  ttl: 3600,
  strategy: 'lru',
};

4. 性能优化

调整并发限制、请求队列大小及批处理策略，优化数据库连接池配置以提升吞吐量。

5. 日志与监控

使用结构化日志输出，包含 TraceID 等追踪字段，支持控制台、文件及远程服务三种输出方式。

十、总结

配置 OpenClaw 飞书机器人主要涉及以下步骤：

1. 创建飞书企业应用并获取凭证。
2. 开通必要权限并发布应用。
3. 配置环境变量及核心连接模式（推荐 WebSocket）。
4. 设置群组白名单与权限控制。
5. 完成功能测试与问题排查。

按照上述流程操作，即可快速搭建起稳定可靠的企业级 AI 助手。