OpenClaw 完美对接飞书教程：从零到生产级配置
📋 目录
- 1. 前言
- 2. 为什么选择飞书
- 3. 准备工作
- 4. 创建飞书应用
- 5. 配置应用权限
- 6. 安装 OpenClaw Feishu 插件
- 7. 配置 OpenClaw
- 8. OAuth 认证与授权
- 9. 验证对接效果
- 10. 高级配置与优化
- 11. 常见问题解答
- 12. 总结
🚀 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 --version3.3 安装 OpenClaw
# 全局安装 OpenClaw
sudo npm install -g openclaw
# 初始化工作目录
mkdir ~/openclaw && cd ~/openclaw
openclaw init3.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 install6.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/callback8.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).log8.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.ini10.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).logQ2: OAuth 授权失败？
# 1. 检查回调 URL 是否匹配
# 2. 检查网络
curl -v https://open.feishu.cn
# 3. 检查时间同步
sudo ntpdate -u pool.ntp.orgQ3: 消息发送失败？
# 1. 检查频率限制
# 飞书：每分钟最多 60 条消息
# 2. 检查消息内容
# 避免敏感词
# 3. 重启服务
openclaw gateway restartQ4: 公网无法访问？
# 1. 检查云服务器安全组
# 阿里云/腾讯云 → 实例 → 安全组 → 开放端口 3000
# 2. 检查本地防火墙
sudo ufw allow 3000/tcp
# 3. 测试连通性
curl https://your-domain.com/healthQ5: 如何查看用户 Open ID？
# 调用飞书 API：
# GET https://open.feishu.cn/open-apis/contact/v3/users
# 需要权限：contact:user.base:readonlyQ6: 群聊 @消息处理？
# 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 v1.0+ 和飞书开放平台 API 编写。由于软件版本更新，部分步骤可能略有差异。
🔖 标签：#OpenClaw #飞书 #AI助手 #Bot #集成 #教程
声明：本站所有文章，如无特殊说明或标注，均为本站原创发布。任何个人或组织，在未征得本站同意时，禁止复制、盗用、采集、发布本站内容到任何网站、书籍等各类媒体平台。如若本站内容侵犯了原著者的合法权益，可联系我们进行处理。
