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

OpenClaw 集成飞书机器人实战指南 | 极客日志

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

特性	OpenClaw	传统 bot 框架
AI 原生设计	✅	❌
跨平台统一接口	✅	❌
本地模型支持	✅	⚠️ 部分支持
持久化上下文	✅	⚠️ 需手动实现
可视化技能市场	✅	❌

# 1. 确保 WSL2 已安装
wsl --list --verbose

# 2. 更新到最新内核
wsl --update

# 3. 启动 Ubuntu
wsl -d Ubuntu

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

# 确认 npm 版本 >= 10
npm --version
# 10.9.0 ✓

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

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

# 方式一：保存到环境变量文件
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

权限标识	类型	必要度	用途说明
`im:message`	Tenant	必需	发送和接收群聊消息
`im:message:send_as_bot`	Tenant	必需	以机器人身份发送消息
`im:chat`	Tenant	必需	创建和管理聊天会话
`im:chat.members:read`	Tenant	可选	读取群成员信息
`docx:document:create`	User	可选	创建飞书云文档
`docx:document:readonly`	User	可选	读取飞书文档
`wiki:space:read`	User	可选	访问知识库空间
`base:record:create`	User	可选	向多维表格写入数据
`calendar:calendar.event:create`	User	可选	创建日程事件
`contact:user.base:readonly`	User	可选	查询用户基础信息
`drive:file:upload`	User	可选	上传文件到云空间

1. 在应用中获取机器人卡片 URL
2. 将链接发到目标群组
3. 群主/群成员点击加入

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

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

# 1. 安装 OpenClaw CLI
npm install -g @openclaw/cli

# 2. 验证安装
openclaw --version
# 输出：2026.3.2

# 3. 初始化配置
openclaw init

# 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

# 使用一键脚本
curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/setup.sh | bash

# 或者使用 npx 临时运行
npx openclaw-cli init

{
  "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 客户端封装
│   ├── send.ts       # 发送消息逻辑
│   ├── reactions.ts  # 表情回复功能
│   ├── mention.ts    # @提及解析
│   ├── bitable/      # 多维表格相关
│   ├── docx/         # 文档操作
│   ├── drive/        # 云盘操作
│   └── wiki/         # 知识库操作
├── skills/           # 预置技能集
│   ├── feishu-doc/
│   ├── feishu-drive/
│   ├── feishu-perm/
│   └── feishu-wiki/
└── package.json

# === 飞书基础配置 ===
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 # debug/info/warn/error
FEISHU_MESSAGE_DEBOUNCE_MS=300 # 消息防抖间隔
FEISHU_RETRY_ATTEMPTS=3 # 失败重试次数

# 列出所有可用插件
openclaw plugins list

# 启用飞书插件
openclaw plugins enable feishu

# 查看插件状态
openclaw plugins status feishu
# 输出：✅ enabled (v2.1.0)

nano ~/.openclaw/config.json

{
  "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

# 查看最近的消息记录
openclaw messages --channel feishu --limit 10

[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
# }

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 "本周数据统计"

{
  "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

# 查看所有知识库空间
openclaw wiki spaces --channel feishu

# 创建新页面
openclaw wiki create \
  --channel feishu \
  --space-id space_xxx \
  --title "技术选型指南" \
  --content-type docx

# 列出所有记录
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"}'

# 给消息点赞
openclaw reaction add \
  --channel feishu \
  --message-id om_msg_id \
  --emoji "👍"

# 取消表情
openclaw reaction remove \
  --channel feishu \
  --message-id om_msg_id \
  --emoji "😄"

# 批量操作
openclaw reaction batch \
  --channel feishu \
  --message-id om_msg_id \
  --add "👍,🎉" \
  --remove "❓"

# 每天早上 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:
- 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

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

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

// 使用指数退避策略
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' };
}

# 使用批量接口提升效率
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
    ]
})

// 缓存常用数据避免重复请求
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);
}

interface MessageTemplate {
  type: 'text' | 'card' | 'image' | 'file';
  priority: 'normal' | 'urgent';
  fallback?: string;
  render(context: Record<string, any>): Promise<MessageContent>;
}

// 示例：每日待办提醒模板
export class DailyTodoTemplate implements MessageTemplate {
  async render(ctx) {
    const today = formatDate(new Date());
    const tasks = await fetchTasksForUser(ctx.userId, today);
    if (tasks.length === 0) {
      return {
        type: 'text',
        content: '✨ 今日无待办事项，享受惬意的一天吧！☕️'
      };
    }
    return {
      type: 'card',
      data: {
        header: { title: `📅 ${today} 的待办` },
        sections: tasks.map(t => ({ content: `[${t.priority}] ${t.title}` }))
      }
    };
  }
}

skills/my-custom-skill/
├── SKILL.md          # 技能说明文档
├── handler.js        # 主处理逻辑
├── tools/
│   ├── helper.js     # 辅助函数
│   └── formatter.js  # 格式化工具
└── tests/
    └── handler.test.js # 单元测试

// handler.js
module.exports = {
  name: 'meeting-organizer',
  description: '智能会议组织者',
  triggers: ['安排会议', '开会', 'schedule meeting'],
  async execute(message, context) {
    const { time, participants, topic } = parseMeetingIntent(message);
    // 查找空闲时间段
    const availableSlots = await findAvailableSlots(participants, time.range);
    // 创建会议邀请
    const meeting = await scheduleMeeting({
      topic,
      startTime: availableSlots[0],
      attendees: participants,
      agenda: message.rawText
    });
    return formatSuccessMessage(meeting);
  }
};

openclaw skill link ./skills/my-custom-skill
openclaw skill list
# 显示：✅ meeting-organizer (active)

# 设置日志级别
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

#!/bin/bash
echo "=== OpenClaw Feishu Monitor ==="
echo "Timestamp: $(date)"

# 消息统计
openclaw stats --channel feishu --since "24h ago"

# 响应时间
ping -c 5 api.feishu.cn

# 资源使用
ps aux | grep openclaw | awk '{print $3, $4}'

# 队列长度
openclaw queue status

chmod +x monitor.sh
./monitor.sh > logs/health-check-$(date +%Y%m%d).log

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

# 3. 重置 DNS 缓存
sudo systemd-resolve --flush-caches

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

// 添加请求间隔
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))));

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

# 调试@提及
openclaw debug mention-test \
  --chat-id oc_target \
  --trigger-pattern "@me (.*)"

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

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

Error: permission_denied for doc_token=doc_xxx
# 解决方法：
# 1. 确认机器人已被授予文档访问权
# 2. 在文档中设置共享权限
# 3. 刷新 OAuth 授权
openclaw auth reauthorize --provider feishu --scope docx

// 结合本地 LLM 实现智能对话
const { createOpenAI } = require('openai');
const ollama = createOpenAI({
  baseURL: 'http://localhost:11434/v1',
  apiKey: 'ollama'
});

async function intelligentReply(incomingMessage) {
  const response = await ollama.chat.completions.create({
    model: 'qwen2.5:72b',
    messages: [
      { role: 'system', content: '你是团队的智能助手...' },
      { role: 'user', content: incomingMessage.text }
    ]
  });
  return response.choices[0].message.content;
}

资源类型	链接	说明
官方文档	https://docs.openclaw.ai	最新 API 文档
示例代码库	https://github.com/openclaw/examples	丰富的实战案例
Discord 社区	https://discord.gg/clawd	全球开发者交流
Stack Overflow	tag:openclaw	技术问题解答

# Fork 仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 添加新功能分支
git checkout -b feature/my-cool-feature

# 开发完成后提交 PR
git push origin feature/my-cool-feature

Scope	Type	Description	Read	Write
`im:message`	Tenant	群聊消息	✅	✅
`im:message.p2p_msg`	Tenant	私聊消息	✅	✅
`im:chat`	Tenant	聊天会话管理	✅	✅
`im:chat.members`	Tenant	群成员管理	✅	⚠️
`docx:document`	User	云文档操作	✅	✅
`wiki:space`	User	知识库空间	✅	✅
`base:record`	User	多维表格记录	✅	✅
`calendar:calendar.event`	User	日历事件	✅	✅
`drive:file`	User	云盘文件	✅	✅
`contact:user.base`	User	用户基础信息	✅	❌

# ========== 认证与配置 ==========
openclaw init # 初始化配置
openclaw auth login --provider feishu # 登录飞书
openclaw config show # 查看当前配置

# ========== 消息管理 ==========
openclaw message --help # 查看消息命令帮助
openclaw message send --to @all "Hello world"
openclaw message reply --id msg_xxx "Got it"
openclaw message history --count 50 # 查看历史消息

# ========== 文档操作 ==========
openclaw doc create --title "New Doc"
openclaw doc read --token doc_xxx
openclaw doc update --token doc_xxx --content "Updates..."
openclaw doc delete --token doc_xxx

# ========== 插件管理 ==========
openclaw plugins list # 列出所有插件
openclaw plugins enable feishu # 启用飞书插件
openclaw plugins disable feishu # 禁用飞书插件
openclaw plugins update # 更新插件到最新版本

# ========== 诊断工具 ==========
openclaw debug probe # 检测服务连通性
openclaw debug dump # 导出调试信息
openclaw version # 查看版本信息

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

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

目录

前言

什么是 OpenClaw

核心架构图

为什么选择 OpenClaw？

前期准备

硬件要求

软件环境

方案 A：使用 WSL2（推荐 Windows 用户）

方案 B：macOS/Linux 原生环境

前置知识

飞书应用创建与授权

Step 1: 登录飞书开发者平台

Step 2: 填写应用基本信息

Step 3: 获取关键凭证

Step 4: 配置权限范围

批量申请权限示例

Step 5: 发布应用并获取 access_token

方式一：测试版发布（开发阶段）

方式二：正式版发布（生产环境）

Step 6: 邀请应用进群

OpenClaw 环境搭建

安装方式对比

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

方式二：Docker 部署

方式三：快速启动器（适合初学者）

配置文件详解

飞书插件配置详解

插件架构解析

核心配置文件

启用飞书插件

方式一：通过 CLI 启用

方式二：手动编辑 config.json

验证连接状态

核心功能实战

📤 发送文本消息

基础用法

通过 Python 脚本调用

🖼️ 发送富媒体消息

发送图片

发送卡片消息

🎯 @提及与回复功能

@特定人员

@所有人（仅群主可用）

回复指定消息

📑 文档与知识库操作

创建云文档

读取文档内容

追加内容到文档

知识库节点管理

📊 多维表格（Bitable）操作

查询数据

写入数据

🎭 表情回复功能

🔄 定时任务与自动回复

创建周期性任务

配置自动回复规则

进阶技巧与最佳实践

🔒 安全最佳实践

1. 凭证管理

2. API 速率限制

3. 权限最小化

🚀 性能优化

1. 消息批处理

2. 缓存策略

📱 消息模板设计

通用模板结构

🧩 自定义技能开发

技能目录结构

技能注册示例

📈 监控与调试

启用详细日志

常见日志分析

性能指标收集

常见问题排查

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

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

问题 3：消息发送被限流