OpenClaw 飞书机器人配置指南：从零搭建 AI 助手

开通权限

在「权限管理」中，根据功能需求开通相应权限。核心权限包括：

配置事件订阅

Webhook URL 配置

你需要提供一个服务器地址用于接收飞书推送：

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

订阅事件

必须订阅以下事件以确保机器人能正常响应：

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

发布应用

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

OpenClaw 配置

配置文件结构

了解项目结构有助于定位配置项：

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

环境变量配置

在 .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

飞书配置文件

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

账号配置

支持多账号配置，方便同时管理不同环境或团队：

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

核心配置详解

连接模式配置

WebSocket 模式（推荐）

实时双向通信，适合高并发场景。注意心跳间隔和重连策略：

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

Webhook 模式

被动接收消息，适合无公网 IP 或防火墙限制的环境：

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

消息类型支持

系统支持多种消息格式，开发时可灵活调用：

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

消息发送配置

发送富文本消息时需注意内容长度限制，超过阈值建议拆分：

// 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 },
        ],
      },
    }),
  });
};

群组策略配置

群白名单配置

通过白名单机制控制机器人可用范围，防止滥用：

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

群组功能开关

精细化控制群组内的功能权限：

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

权限控制

区分管理员与普通用户的操作权限：

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

功能测试

基础功能测试

1. 私聊对话：搜索机器人并发起对话，发送测试消息如'你好，OpenClaw！'
2. 群组@互动：将机器人拉入群组，@机器人提问，观察回复是否正常

高级功能测试

• 飞书文档操作：尝试读取或写入飞书云文档
• 文件传输：测试图片和文件的上传下载功能

测试用例表

常见问题

Q1: WebSocket 连接失败？

检查网络连通性、防火墙设置及端口监听情况。开启调试日志查看具体错误：

ping open.feishu.cn
sudo ufw status
netstat -tlnp | grep 443
FEISHU_LOG_LEVEL=debug pnpm dev

Q2: 消息发送失败？

常见原因包括消息过长或频率超限。飞书默认限制 60 条/分钟，建议添加重试机制：

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: 权限不足？

确认已开通所有必要权限，应用已发布且用户可见范围包含当前用户。

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

进阶技巧

多账号配置

支持同时连接飞书和 Lark，实现负载均衡：

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

自定义消息卡片

发送交互式卡片提升用户体验：

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

消息缓存策略

启用 LRU 缓存减少重复请求：

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

性能优化

调整并发限制与队列大小以应对高负载：

export const performance = {
  maxConcurrent: 10,
  queueSize: 100,
  batching: { enabled: true, maxBatchSize: 10, maxWaitTime: 100 },
  pool: { min: 2, max: 10 },
};

日志与监控

配置结构化日志输出至控制台、文件或远程服务：

export const logging = {
  level: 'info',
  format: 'json',
  outputs: [
    { type: 'console', level: 'info' },
    { type: 'file', level: 'info', path: './logs/feishu.log', rotation: 'daily' },
  ],
};

总结

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

1. 创建飞书企业应用并获取凭证
2. 开通必要权限并发布应用
3. 配置环境变量与连接模式
4. 设置群组白名单与权限控制
5. 执行功能测试验证稳定性

遵循上述流程，即可快速搭建一个稳定可靠的企业级 AI 助手。