OpenClaw 集成飞书机器人实战指南

OpenClaw 集成飞书机器人实战指南

将大语言模型的能力接入飞书，实现真正的智能化办公。本文将带你从零开始，完成 OpenClaw 与飞书的深度集成。

什么是 OpenClaw

OpenClaw 是一个开源的智能代理框架，支持本地部署 AI 能力、多通道消息接入以及智能任务编排。它的核心优势在于 AI 原生设计、跨平台统一接口以及持久化上下文管理。

核心架构

┌─────────────────────────────────────────────────────┐
│ OpenClaw Framework                                  │
├─────────────────────────────────────────────────────┤
│ ┌──────────┐ ┌──────────┐ ┌──────────┐             │
│ │ Chat     │ │ Email    │ │ Calendar │ ...         │
│ │ Plugin   │ │ Plugin   │ │ Plugin   │             │
│ └──────────┘ └──────────┘ └──────────┘             │
├─────────────────────────────────────────────────────┤
│ Skill Marketplace (Feishu Docs, Drive, Wiki...)     │
├─────────────────────────────────────────────────────┤
│ Memory & Context Management                         │
├─────────────────────────────────────────────────────┤
│ Model Providers Layer (Qwen, DeepSeek, Ollama)      │
└─────────────────────────────────────────────────────┘

相比传统 bot 框架，OpenClaw 在 AI 原生设计和本地模型支持上表现更佳，无需依赖云端服务即可保护隐私。

前期准备

硬件要求

• CPU：双核以上（建议四核）
• 内存：≥ 4GB RAM（AI 推理场景建议 8GB+）
• 磁盘：至少 10GB 可用空间
• 网络：稳定互联网连接

软件环境

Windows 用户推荐 WSL2

# 确保 WSL2 已安装
wsl --list--verbose
# 更新到最新内核
wsl --update
# 启动 Ubuntu
wsl -d Ubuntu

macOS/Linux 原生环境

# 确认 Node.js 版本 >= 20
node --version
# v22.22.0 ✓
# 确认 npm 版本 >= 10
npm --version
# 10.9.0 ✓

飞书应用创建与授权

1. 登录开发者平台

访问 飞书开放平台 → 点击 '企业自建应用' → '创建应用'。

2. 填写基本信息

• 应用名称：OpenClaw Bot
• 图标：选择或上传一个 1024x1024 PNG
• 描述：我的智能 AI 助手，帮助你高效工作
• 可见范围：选择相应的部门或个人

3. 获取关键凭证

创建成功后，进入应用详情页复制以下信息：

• App ID: cli_xxxxxxxxxxxxxx
• App Secret: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

⚠️ 安全提醒：App Secret 是敏感信息，请妥善保管，不要提交到公开的代码仓库！

保存方式任选其一：

# 方式一：保存到环境变量文件
echo "FEISHU_APP_ID=cli_xxx" >> ~/.env.openclaw
echo "FEISHU_APP_SECRET=xxx-xxxx-xxxx-xxxx-xxxxxx" >> ~/.env.openclaw
chmod 600 ~/.env.openclaw

# 方式二：通过命令临时设置
export FEISHU_APP_ID=cli_xxx
export FEISHU_APP_SECRET=xxx-xxxx-xxxx-xxxx-xxxxxx

4. 配置权限范围

在飞书应用后台左侧菜单找到 '管理' → '权限和应用' → '添加权限范围'。

权限标识	类型	必要度	用途说明
im:message	Tenant	必需	发送和接收群聊消息
im:message:send_as_bot	Tenant	必需	以机器人身份发送消息
im:chat	Tenant	必需	创建和管理聊天会话
docx:document:create	User	可选	创建飞书云文档
base:record:create	User	可选	向多维表格写入数据

注意：Tenant 级别权限可能需要管理员审批，生产环境请遵循最小权限原则。

5. 发布应用并邀请进群

• 测试版发布：开发阶段使用，可见范围为当前部门。
• 正式版发布：生产环境使用，需提交代码审核。

邀请进群方法：

1. 打开任意飞书群聊
2. 点击右上角 "..." → "添加机器人"
3. 搜索你的应用名称并加入

验证成功标志：机器人出现在群成员列表中，且可以正常 @ 机器人并收到回复。

OpenClaw 环境搭建

安装方式对比

方式	适用场景	优点	缺点
全局安装	个人开发者	一次安装到处用	可能权限冲突
Docker 部署	团队协作	环境隔离干净	额外学习成本
GitHub Codespace	在线体验	零配置开箱即用	需要网络条件

方式一：全局安装（推荐）

# 1. 安装 OpenClaw CLI
npm install -g @openclaw/cli
# 2. 验证安装
openclaw --version
# 输出：2026.3.2
# 3. 初始化配置
openclaw init

方式二：Docker 部署

# Dockerfile
FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci
EXPOSE 8765
CMD ["node", "dist/index.js"]

# docker-compose.yml
version: '3.8'
services:
  openclaw:
    build: .
    ports:
      - "8765:8765"
    environment:
      - NODE_ENV=production
      - FEISHU_APP_ID=${FEISHU_APP_ID}
      - FEISHU_APP_SECRET=${FEISHU_APP_SECRET}
    volumes:
      - ./workspace:/app/workspace
      - ./memory:/app/memory

启动服务：

docker-compose up -d
docker-compose logs -f openclaw

配置文件详解

生成后的 /root/.openclaw/config.json 核心字段说明：

{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "auth": { "mode": "token", "token": "自动生成" }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "deepseek/deepseek-chat" },
      "workspace": "/root/.openclaw/workspace"
    }
  },
  "plugins": {
    "entries": { "feishu": { "enabled": true } }
  }
}

飞书插件配置详解

插件架构解析

/root/.openclaw/extensions/feishu/
├── index.ts # 插件入口文件
├── src/
│   ├── channel.ts # 消息通道处理
│   ├── monitor.ts # WebSocket 监听
│   ├── client.ts # SDK 客户端封装
│   └── skills/ # 预置技能集
└── package.json

核心配置文件

创建 .env.openclaw 或使用以下方式配置：

# === 飞书基础配置 ===
FEISHU_APP_ID=cli_xxxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# === 连接模式（二选一）===
# WebSocket 模式（实时双向通信）
FEISHU_CONNECTION_MODE=websocket

# Webhook 模式（需要公网回调地址）
# FEISHU_CONNECTION_MODE=webhook
# FEISHU_WEBHOOK_URL=https://your-domain.com/api/webhook/feishu

# === 高级选项 ===
FEISHU_LOG_LEVEL=debug
FEISHU_MESSAGE_DEBOUNCE_MS=300
FEISHU_RETRY_ATTEMPTS=3

启用飞书插件

方式一：通过 CLI 启用

# 列出所有可用插件
openclaw plugins list
# 启用飞书插件
openclaw plugins enable feishu
# 查看插件状态
openclaw plugins status feishu
# 输出：✅ enabled (v2.1.0)

方式二：手动编辑 config.json

nano ~/.openclaw/config.json

添加以下内容到 plugins.entries：

{"plugins":{"entries":{"qwen-portal-auth":{"enabled":true},"feishu":{"enabled":true}}}}

重启服务使配置生效：

pkill -f openclaw-gateway
openclaw gateway start

验证连接状态

# 检查插件是否正常加载
openclaw gateway status | grep feishu
# Expected: [Plugin loaded] feishu -> OK

# 测试飞书连通性
openclaw probe feishu
# Expected: Connection successful, bot_id=oc_xxx

如果看到如下输出，说明一切正常：

[INFO] Feishu plugin initialized
[INFO] Connected to IM Cloud Server
[INFO] Bot info: id=oc_f91fe..., name=OpenClaw Bot
[INFO] Listening for incoming messages...

核心功能实战

📤 发送文本消息

基础用法

# 单条消息发送
openclaw message \--channel feishu \--target oc_group_chat_id_here \--message "你好，我是 OpenClaw 机器人！"
# 响应输出：
# {
#   "messageId": "om_x100b543...",
#   "chatId": "oc_f91fe152...",
#   "timestamp": 1710072345
# }

通过 Python 脚本调用

import subprocess
import json

def send_feishu_message(chat_id, content):
    result = subprocess.run(
        ['openclaw', 'message', '--channel', 'feishu', '--target', chat_id, '--message', content, '--output', 'json'],
        capture_output=True, text=True
    )
    return json.loads(result.stdout)

# 使用示例
response = send_feishu_message("oc_abc123xyz", "今天的日报已完成，请及时查收！📊")
print(f"消息已发送：{response['messageId']}")

🖼️ 发送富媒体消息

发送图片

# 发送本地图片
openclaw message \--channel feishu \--target oc_target_id \--media /path/to/image.png \--caption "项目架构图"
# 发送网络图片
openclaw message \--channel feishu \--target oc_target_id \--media "https://example.com/chart.png" \--caption "本周数据统计"

发送卡片消息

创建 card.json 文件：

{
  "type": "text card",
  "header": { "title": "📅 会议提醒", "subtitle": "重要项目评审会" },
  "hero": { "type": "image", "sub_type": "cover", "url": "https://cdn.example.com/meeting.jpg" },
  "content": [{ "section": { "text": { "content": "时间：今天 14:00-16:00\n地点：会议室 A\n参会人：产品部全体" } } }]
}

# 发送卡片
openclaw message \--channel feishu \--target oc_target_id \--card-file card.json

🎯 @提及与回复功能

# 在群聊中@某人
openclaw message \--channel feishu \--target oc_group_id \--message "这个问题需要跟进一下" \--mention-user ou_user_open_id

# @所有人（仅群主可用）
openclaw message \--channel feishu \--target oc_group_id \--message "紧急通知：服务器维护将于今晚 0 点开始" \--mention-all

# 回复指定消息
openclaw message \--channel feishu \--target oc_group_id \--reply-to om_original_message_id \--message "@user 好的，这个需求我已经理解了"

📑 文档与知识库操作

创建云文档

# 新建空白文档
openclaw doc create \--channel feishu \--title "2026 年 Q1 工作计划" \--folder-token folder_token_optional

读取文档内容

# 获取文档全文
openclaw doc read \--channel feishu \--token doc_token_from_url
# 结果示例
# Document: 2026 年 Q1 工作计划
# Blocks: 15
# Content:
# ## 一、季度目标
# - 完成产品 V3.0 上线
# - 用户数突破 100 万

追加内容到文档

<!-- 创建 update.txt -->
## 新增模块
- [x] 数据分析看板
- [ ] 报表导出功能
- [ ] 第三方集成

openclaw doc append \--channel feishu \--token doc_xxx \--file update.txt

📊 多维表格（Bitable）操作

查询数据

# 列出所有记录
openclaw bitable query \--channel feishu \--app-token app_xxx \--table-id table_xxx \--filter "Status='进行中'"
# 输出格式：JSON
[{"id":"rec_abc", "Name":"用户中心重构", "Priority":"高", "Assignee":["张三", "李四"]}]

写入数据

openclaw bitable insert \--channel feishu \--app-token app_xxx \--table-id table_xxx \--fields '{"Task":"编写技术文档","Owner":"王五","DueDate":"2026-03-20"}'

🔄 定时任务与自动回复

创建周期性任务

创建 crontab.txt:

# 每天早上 9 点发送昨日总结
0 9 * * * openclaw message --channel feishu --target oc_team_chat --template daily-summary
# 每周一下午 3 点提醒周报
0 15 1 * * openclaw message --channel feishu --target oc_management --template weekly-report-reminder

导入定时任务：

openclaw cron import crontab.txt
openclaw cron list

配置自动回复规则

创建 rules.yaml:

rules:
- trigger: "@me 天气"
  response: "正在查询今日天气...{{weather(city)}}"
- trigger: "帮我定个会议"
  action: calendar.create
  fields:
    title: "团队例会"
    duration: 60
- trigger: "周报"
  response_template: |
    📊 **本周工作总结**
    已完成： {{tasks.completed}}
    进行中： {{tasks.in_progress}}

启用规则引擎：

openclaw rules load rules.yaml

进阶技巧与最佳实践

🔒 安全最佳实践

1. 凭证管理

# ❌ 错误做法：硬编码在代码中
const appId = "cli_xxx"; // DANGER!

# ✅ 正确做法：环境变量 + 加密存储
npm install -g keytar
keytar.setPassword("openclaw", "feishu_secret", "xxx-xxxx-xxxx");
# 使用时读取
const secret = keytar.getPasswordSync("openclaw", "feishu_secret");

2. API 速率限制

// 使用指数退避策略
async function sendWithRetry(message, maxAttempts = 5) {
  let attempt = 0;
  while (attempt < maxAttempts) {
    try {
      await sendMessage(message);
      return { success: true };
    } catch (error) {
      if (error.code === 'RATE_LIMITED') {
        const delay = Math.pow(2, attempt) * 1000;
        console.log(`Rate limited, retrying in ${delay}ms`);
        await sleep(delay);
        attempt++;
      } else {
        throw error;
      }
    }
  }
  return { success: false, error: 'Max retries exceeded' };
}

🚀 性能优化

1. 消息批处理

from openclaw import FeishuClient
client = FeishuClient()

# ❌ 低效：逐个发送
for member in members:
    client.send_message(member.chat_id, "通知内容")

# ✅ 高效：批量发送
client.batch_send({
    'messages': [{'chat_id': m.id, 'content': '通知内容'} for m in members]
})

2. 缓存策略

class CacheManager {
  constructor(ttl = 300000) { // 5 分钟
    this.cache = new Map();
    this.ttl = ttl;
  }
  get(key) {
    const entry = this.cache.get(key);
    if (!entry || Date.now() > entry.expiry) {
      this.cache.delete(key);
      return null;
    }
    return entry.value;
  }
  set(key, value) {
    this.cache.set(key, { value, expiry: Date.now() + this.ttl });
  }
}

// 使用示例
const cache = new CacheManager();
let groupInfo = cache.get('group_' + chatId);
if (!groupInfo) {
  groupInfo = await client.getChatInfo(chatId);
  cache.set('group_' + chatId, groupInfo);
}

📈 监控与调试

启用详细日志

export OPENCLAW_LOG_LEVEL=debug
export LOGGING_MODULES="feishu,monitor,sender"

常见日志分析

# ✅ 正常运行
[INFO] [feishu] Message received from oc_xxx
[DEBUG] [parser] Extracted intent: check_status
[INFO] [executor] Running task: status_report
[INFO] [sender] Response sent successfully

# ⚠️ 警告信息
[WARN] [rate-limit] Approaching quota limit (85%)
[WARN] [cache] Cache miss rate high: 45%

# ❌ 错误信息
[ERROR] [auth] Access token expired, refreshing...
[ERROR] [network] Request timeout after 30s

常见问题排查

问题 1：无法连接到飞书服务器

症状： Error: Connection refused at api.feishu.cn:443 解决方案：

# 1. 检查网络连接
curl -I https://api.feishu.cn/open-apis/auth/v3/version
# 预期返回 HTTP/2 200
# 2. 检查防火墙
sudo iptables -L | grep 443
# 如有拦截，放行端口
sudo iptables -A OUTPUT -p tcp --dport 443 -j ACCEPT

问题 2：认证失败 / Token 无效

症状： Error: invalid_access_token 解决步骤：

# 1. 重新获取 token
openclaw auth refresh --provider feishu
# 2. 检查凭证是否正确
cat ~/.openclaw/credentials/feishu.json | jq '.app_id'
# 3. 清除过期缓存
rm -rf ~/.openclaw/cache/feishu/*
openclaw cache clear

问题 3：消息发送被限流

缓解策略：

// 添加请求间隔
const DELAY_PER_REQUEST = 100; // ms
async function sendMessageBatch(messages) {
  for (const msg of messages) {
    await sendSingleMessage(msg);
    await sleep(DELAY_PER_REQUEST);
  }
}
// 或使用并发控制
const pLimit = require('p-limit');
const limit = pLimit(5); // 最多 5 个并发
Promise.all(messages.map(msg => limit(() => sendSingleMessage(msg))));

问题 4：@提及无法触发响应

排查清单：

• 确认机器人已在群内
• 确认权限包含 im:message.group_at_msg:readonly
• 检查 webhook 是否配置正确
• 查看日志中是否有 mention 事件捕获

问题 5：WebSocket 连接频繁断开

根本原因： 网络不稳定或心跳超时 优化配置：

{"plugins":{"feishu":{"websocket":{"heartbeat_interval_ms":30000,"reconnect_delay_base_ms":5000,"max_reconnect_attempts":10}}}}

问题 6：无法读取/写入文档

权限检查：

# 查看当前应用的权限范围
openclaw scope list --provider feishu
# 应该包含 ✅ docx:document:readonly ✅ docx:document:write_only

总结与展望

通过本文的学习，你应该已经掌握了 OpenClaw 与飞书集成的全流程：

• 基础篇：理解 OpenClaw 特性，完成飞书应用创建与权限配置。
• 进阶篇：掌握多通道消息发送、@提及与智能回复、文档与多维表格的 CRUD 操作。
• 高阶篇：学会自定义技能开发、性能优化与缓存策略，以及安全最佳实践。

下一步可以尝试结合本地 LLM 实现智能对话，构建更复杂的工作流引擎，或探索多租户与企业级部署方案。参考官方文档获取更多 API 细节与示例代码。