OpenClaw 完美对接飞书教程：从零到生产级配置

🚀 1. 前言

OpenClaw 是一个强大的 AI 助手框架，支持多种对话平台和 AI 模型。本文将详细介绍如何将 OpenClaw 与飞书（Lark/Feishu）完美对接，实现通过飞书群聊或私聊直接控制你的 AI 助手。

💼 2. 为什么选择飞书

2.1 飞书的优势

企业级稳定性： 字节跳动出品，服务稳定可靠

丰富的 API： 提供完整的消息、机器人、卡片等 API

强大的开放平台： 支持自定义应用开发和集成

安全可控： 企业数据安全保障

多端支持： 支持网页、桌面端、移动端

2.2 OpenClaw + 飞书的组合优势

随时随地通过飞书与 AI 助手对话

支持群聊协作，多人同时使用

可结合飞书日历、文档等生态功能

支持消息卡片、按钮等富交互

可作为企业智能助手入口

🛠️ 3. 准备工作

3.1 服务器要求

# 系统要求
- 操作系统：Linux / macOS / Windows
- Node.js：>= 18.0.0 (推荐 v20+)
- 内存：最低 512MB，推荐 2GB+
- 磁盘：最低 1GB 可用空间
- 网络：可访问外网（需访问飞书 API）

3.2 安装 Node.js

# Linux (Ubuntu/Debian)
sudo apt update
sudo apt install -y curl
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
# 验证安装
node --version
npm --version

3.3 安装 OpenClaw

# 全局安装 OpenClaw
sudo npm install -g openclaw
# 初始化工作目录
mkdir ~/openclaw && cd ~/openclaw
openclaw init

3.4 注册飞书开放平台账号

# 访问飞书开放平台
# https://open.feishu.cn/
# 1. 注册/登录飞书账号
# 2. 点击"创建企业应用"
# 3. 填写应用名称和描述

📱 4. 创建飞书应用

4.1 创建应用

# 步骤：
# 1. 访问：https://open.feishu.cn/
# 2. 登录飞书账号
# 3. 点击"创建企业应用"
# 4. 填写：
#    - 应用名称：OpenClaw AI 助手
#    - 应用描述：通过飞书控制你的 AI 助手

4.2 获取应用凭证

# 获取以下凭证信息：
# 1. App ID
#    位置：应用详情 → "凭证与权限" → "应用凭证"
#    示例：cli_a909ee13c4381bc0
# 2. App Secret
#    位置：应用详情 → "凭证与权限" → "应用凭证" → 点击查看
#    ⚠️ 此密钥需要保密！
# 3. Verification Token
#    位置：应用详情 → "凭证与权限" → "应用凭证"

🔐 5. 配置应用权限

5.1 必需权限列表

# 在飞书开放平台 → 应用详情 → "权限管理" 中添加：
# 1. im:message - 发送和接收消息
# 2. im:message:send_as_bot - 以机器人身份发送消息
# 3. im:chat:readonly - 查看群聊信息
# 4. im:chat - 管理群聊
# 5. cardkit:card:write - 使用卡片消息
# 6. contact:user.base:readonly - 查看用户基本信息

5.2 权限审核

# 敏感权限需要企业管理员审核：
# 1. 填写权限使用说明
# 2. 提交审核
# 3. 管理员在飞书管理后台 → 应用管理 → 应用审核中批准

📦 6. 安装 OpenClaw Feishu 插件

6.1 安装插件

# 安装飞书插件
cd ~/.openclaw
openclaw plugins add @openclaw/feishu
# 或手动安装
cd ~/.openclaw/extensions
git clone https://github.com/openclaw/openclaw-feishu.git
cd openclaw-feishu
npm install

6.2 插件目录结构

# ~/.openclaw/extensions/feishu/
# ├── package.json         # 插件配置
# ├── src/
# │   ├── index.ts        # 入口文件
# │   ├── config.ts       # 配置处理
# │   ├── handler.ts      # 消息处理
# │   └── oauth.ts        # OAuth 认证

⚙️ 7. 配置 OpenClaw

7.1 编辑配置文件

# 编辑 ~/.openclaw/openclaw.json
  "model": {
    "provider": "minimax-portal",
    "model": "MiniMax-M2.1"
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_a909ee13c4381bc0",
      "appSecret": "your_app_secret_here",
      "verificationToken": "your_verification_token",
      "eventWebhookUrl": "https://your-domain.com/webhook/feishu",
      "mode": "streaming",
      "features": {
        "cards": true,
        "mentions": true,
        "multiChat": true
  "extensions": [
    "@openclaw/feishu"
7.2 配置项说明
# 1. appId - 飞书应用 ID
# 2. appSecret - 飞书应用密钥
# 3. verificationToken - 验证令牌
# 4. eventWebhookUrl - 事件接收 URL（需公网可访问）
# 5. mode - 消息模式：blocking 或 streaming（推荐 streaming）
# 6. features - 功能开关
# 验证配置
openclaw config validate
🔑 8. OAuth 认证与授权
8.1 配置回调地址
# 飞书开放平台 → 应用详情 → "安全设置"
# 添加重定向 URL：
# 开发环境：http://localhost:3000/oauth/feishu/callback
# 生产环境：https://your-domain.com/oauth/feishu/callback
8.2 配置应用首页
# 应用详情 → "应用发布" → "桌面应用"
# 配置：
# - 应用首页 URL
# - 机器人：启用
# - 消息：启用
# - 卡片：启用
8.3 启动 OpenClaw
# 前台启动（开发）
openclaw gateway start
# 后台启动（生产）
openclaw gateway start --daemon
# systemd 管理
sudo systemctl enable openclaw
sudo systemctl start openclaw
# 查看日志
tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log
8.4 用户授权
# 用户首次使用流程：
# 1. 在飞书中打开你的应用
# 2. 点击"授权"按钮
# 3. 确认授权范围
# 4. 授权成功后收到确认消息
# 查看已授权用户
cat ~/.openclaw/data/users.json
✅ 9. 验证对接效果
9.1 基础功能测试
# 测试 1：私聊机器人
# 发送："你好"
# 预期：收到 AI 助手回复
# 测试 2：群聊 @机器人
# 发送："@机器人 今天天气怎么样"
# 预期：正常回复并 @提问者
# 测试 3：命令执行
# 发送："帮我查询服务器状态"
# 预期：返回服务器监控信息
9.2 高级功能测试
# 测试知识库查询
# 发送："公司年假政策是什么"
# 预期：返回知识库内容
# 测试工具调用
# 发送："明天的日程安排"
# 预期：返回日历信息
# 测试多轮对话
# 发送多条连续消息
# 预期：正确理解上下文
🚀 10. 高级配置与优化
10.1 内网穿透
# 方案一：frp
# 下载：https://github.com/fatedier/frp/releases
# frpc.ini 配置：
[common]
server_addr = your_vps_ip
server_port = 7000
[openclaw-web]
type = tcp
local_ip = 127.0.0.1
local_port = 3000
remote_port = 3000
./frpc -c frpc.ini
10.2 HTTPS 配置
# Nginx 反向代理配置：
server {
    listen 443 ssl;
    server_name your-domain.com;
    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
    location / {
        proxy_pass http://127.0.0.1:3000;
10.3 日志配置
# ~/.openclaw/openclaw.json
  "logging": {
    "level": "info",
    "format": "json",
    "output": {
      "file": {
        "enabled": true,
        "path": "/var/log/openclaw/",
        "maxSize": "100m",
        "maxFiles": 5
10.4 高可用部署
# Docker Compose 部署：
version: '3.8'
services:
  openclaw:
    image: openclaw/openclaw:latest
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - OPENCLAW_CONFIG=/app/openclaw.json
    volumes:
      - ./openclaw.json:/app/openclaw.json
      - ./data:/app/data
  redis:
    image: redis:7-alpine
    restart: unless-stopped
    volumes:
      - redis_data:/data
volumes:
  redis_data:
❓ 11. 常见问题解答
Q1: 收不到飞书消息？
# 检查清单：
# 1. OpenClaw 是否运行
ps aux | grep openclaw
# 2. 配置是否正确
#    - App ID/Secret 正确
#    - 权限已审批
# 3. 防火墙
sudo ufw status
# 4. 查看错误日志
tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log
Q2: OAuth 授权失败？
# 1. 检查回调 URL 是否匹配
# 2. 检查网络
curl -v https://open.feishu.cn
# 3. 检查时间同步
sudo ntpdate -u pool.ntp.org
Q3: 消息发送失败？
# 1. 检查频率限制
#    飞书：每分钟最多 60 条消息
# 2. 检查消息内容
#    避免敏感词
# 3. 重启服务
openclaw gateway restart
Q4: 公网无法访问？
# 1. 检查云服务器安全组
#    阿里云/腾讯云 → 实例 → 安全组 → 开放端口 3000
# 2. 检查本地防火墙
sudo ufw allow 3000/tcp
# 3. 测试连通性
curl https://your-domain.com/health
Q5: 如何查看用户 Open ID？
# 调用飞书 API：
# GET https://open.feishu.cn/open-apis/contact/v3/users
# 需要权限：contact:user.base:readonly
Q6: 群聊 @消息处理？
# 1. 启用 mentions 功能
  "channels": {
    "feishu": {
      "features": {
        "mentions": true
# 2. 回复时 @提问者
📚 12. 总结
本文详细介绍了 OpenClaw 与飞书从零到生产级的完整对接流程。
🔑 关键要点：
准备工作：安装 Node.js、OpenClaw，注册飞书账号
创建应用：获取 App ID、App Secret、Verification Token
权限配置：申请必要权限并完成审核
安装插件：npm 安装 Feishu 插件
配置对接：编辑 openclaw.json
OAuth 授权：用户完成授权配对
测试验证：测试私聊、群聊、@提及
生产部署：HTTPS、日志、监控、高可用
🚀 进阶功能：
对接飞书日历（查询/创建日程）
对接飞书文档（读取/写入）
对接飞书审批（查询状态）
自定义消息卡片
多机器人协同
🔗 参考资源：
OpenClaw 官方文档
飞书开放平台文档
OpenClaw GitHub
OpenClaw Discord
📢 声明：本文基于 OpenClaw v1.0+ 和飞书开放平台 API 编写。由于软件版本更新，部分步骤可能略有差异。
🔖 标签：#OpenClaw #飞书 #AI助手 #Bot #集成 #教程
声明：本站所有文章，如无特殊说明或标注，均为本站原创发布。任何个人或组织，在未征得本站同意时，禁止复制、盗用、采集、发布本站内容到任何网站、书籍等各类媒体平台。如若本站内容侵犯了原著者的合法权益，可联系我们进行处理。