夜雨聆风
openclaw 连接飞书机器人完整指南
原文地址: https://code.newban.cn/496.html如果本文有相关附件下载 请将上面地址复制到浏览器打开
文档概述
本文档提供 OpenClaw 与飞书机器人集成的完整配置指南，包含本地部署、云端部署、问题排查及高级配置等全流程说明。
一、方案选择与对比
1.1 方案对比表
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
1.2 快速选择指南
# 如果你需要：# 1. 仅基础聊天 → 用社区版# 2. 操作飞书文档/日历 → 用官方插件# 3. 不确定需求 → 从社区版开始，需要时升级二、前置准备
2.1 环境检查
确保满足以下条件：
-
✅ OpenClaw 已正确安装并可运行 -
✅ 网络通畅，可访问飞书服务器 -
✅ 拥有飞书管理员权限（创建应用需要）
2.2 飞书账号权限
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
三、本地部署配置（扫码方式）
3.1 安装官方插件
# 通过 npm 安装最新版npx -y @larksuite/openclaw-lark install# 或指定版本安装npx -y @larksuite/openclaw-lark@1.2.0 install3.2 扫码绑定流程
-
执行安装命令后，会显示如下信息：
正在初始化飞书插件... 请使用飞书扫描下方二维码完成绑定：████████████████████████████████████████████████████████████████ -
使用飞书APP扫码：
-
确保登录正确的飞书账号 -
扫码后自动创建机器人应用 -
自动完成权限配置 -
绑定成功提示：
✅ 飞书通道连接成功！机器人名称: OpenClaw助手企业: Your Company绑定时间: 2024-01-01 10:00:00
3.3 验证本地连接
# 验证连接状态openclaw channels status --channel feishu# 测试发送消息openclaw feishu test "Hello, Feishu!"四、云端部署配置（手动方式）
4.1 创建飞书机器人应用
方式一：快速创建（推荐）
访问专属链接：open.feishu.cn/page/openclaw
步骤：
-
使用企业管理员账号登录 -
点击”一键创建” -
自动生成包含所有必需权限的应用 -
保存生成的 App ID 和 App Secret
方式二：手动创建
-
访问飞书开放平台：
https://open.feishu.cn/app -
创建企业自建应用：
-
应用名称： OpenClaw-Bot -
应用描述：智能助手机器人 -
权限范围：选择”企业内部使用” -
配置机器人能力：
# 必需权限列表：权限名称: 获取应用信息权限范围: 全部状态: 开启权限名称: 获取用户基础信息权限范围: 全部状态: 开启权限名称: 获取用户邮箱信息权限范围: 全部状态: 开启权限名称: 获取用户user_id权限范围: 全部状态: 开启权限名称: 以应用身份读取通讯录权限范围: 全部状态: 开启权限名称: 获取与发送单聊、群组消息权限范围: 全部状态: 开启 -
发布应用：
-
版本管理 → 创建版本 -
申请发布 → 等待管理员审批 -
审批通过后获取凭证
4.2 获取应用凭证
-
进入应用后台：
开发者后台 → 应用功能 → 凭证与基础信息 -
获取关键信息：
# 必需信息App ID = cli_xxxxxApp Secret = xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx# 可选：加密密钥Encrypt Key = （如有）Verification Token = （如有） -
安全建议：
# 将凭证保存在安全位置# 避免提交到版本控制系统export FEISHU_APP_ID="cli_xxxxx"export FEISHU_APP_SECRET="your_secret_here"
4.3 安装并配置插件
安装插件
# 如果尚未安装官方插件npx -y @larksuite/openclaw-lark install# 或通过 OpenClaw 安装openclaw plugins install @larksuite/openclaw-lark配置凭证
# 方法1：通过配置文件# 编辑 ~/.openclaw/config.yamlchannels: feishu: app_id: "cli_xxxxx" app_secret: "your_secret_here" verification_token: "" # 可选 encrypt_key: "" # 可选# 方法2：通过环境变量export FEISHU_APP_ID="cli_xxxxx"export FEISHU_APP_SECRET="your_secret_here"export FEISHU_VERIFICATION_TOKEN="your_token"export FEISHU_ENCRYPT_KEY="your_encrypt_key"启用插件
# 启用飞书通道openclaw channels enable feishu# 重启 OpenClaw 服务openclaw restart4.4 配对验证
获取配对码
-
进入飞书，找到刚创建的机器人
-
发送任意消息，例如：
hi你好test -
机器人回复示例：
烙 OpenClaw: 访问未配置配对信息:用户ID: ou_4cfc4b4ed6334283a697bfe77a8cf2xx配对码: 7B9K请管理员执行以下命令完成配对:openclaw pairing approve feishu 7B9K
完成配对
-
在 OpenClaw 终端执行：
# 复制上一步获取的命令openclaw pairing approve feishu 7B9K -
成功响应：
✅ 配对成功！用户: 张三 (zhangsan@company.com)时间: 2024-01-01 10:00:00权限: 完全访问 -
返回飞书验证：
# 发送测试消息/help# 应该能收到 OpenClaw 的帮助信息
五、社区版插件使用
5.1 社区版配置
# 1. 清空旧配置（如有）openclaw config unset channels.feishu# 2. 触发登录向导openclaw channels login --channel feishu# 3. 按照提示输入凭证? 请输入 Feishu App ID: cli_xxxxx? 请输入 Feishu App Secret: ********? 是否需要加密验证 [y/N]: N# 4. 验证状态openclaw channels status --channel feishu# 期望输出: Status: connected5.2 版本检测
# 在飞书机器人对话框输入/feishu version# 或输入/feishu auth# 官方插件: 显示授权界面# 社区插件: 提示"命令未找到"六、连接状态检查
6.1 基础检查命令
# 查看所有通道状态openclaw channels list# 查看飞书通道详细状态openclaw channels status --channel feishu --verbose# 测试消息发送openclaw feishu test "连接测试"6.2 状态诊断表
|
|
|
|
|---|---|---|
connected |
|
|
disconnected |
|
|
connecting |
|
|
error |
|
|
not_configured |
|
|
6.3 日志检查
# 查看详细连接日志openclaw --debug channels status --channel feishu# 实时查看日志tail -f ~/.openclaw/logs/feishu.log# 常见日志位置# Linux/macOS: ~/.openclaw/logs/# Windows: %APPDATA%\.openclaw\logs\七、常见问题排查
7.1 连接问题
问题：收不到配对码
可能原因及解决：
# 1. 检查应用是否已发布# 访问飞书开发者后台 → 应用发布状态# 确保状态为"已启用"# 2. 检查网络连接ping open.feishu.cn# 应能正常ping通# 3. 重置配置openclaw config unset channels.feishuopenclaw config set channels.feishu.app_id "你的AppID"openclaw config set channels.feishu.app_secret "你的Secret"openclaw channels restart feishu问题：配对码无效/过期
解决步骤：
-
配对码有效期为 5分钟 -
重新在飞书发送消息获取新配对码 -
确保执行配对命令的 OpenClaw 实例是同一个
7.2 权限问题
权限检查清单
# 必需权限配置required_permissions: - contact:user.basic:readall # 读取用户基础信息 - contact:user.employee_id:readall # 读取员工号 - contact:user.email:readall # 读取用户邮箱 - im:message:send_as_bot # 发送消息 - im:message:send # 接收消息 - im:message:read_users # 读取用户消息# 按需开启权限optional_permissions: - drive:drive:readonly # 云文档读取 - calendar:calendar:readonly # 日历读取 - sheets:spreadsheet:readonly # 表格读取7.3 消息问题
机器人能收不能发
检查步骤：
# 1. 检查机器人是否加入会话# 飞书要求机器人必须被@或加入群聊才能主动发消息# 2. 检查消息频率限制# 飞书限制：单聊 5条/秒，群聊 20条/秒# 3. 检查内容安全# 部分内容可能被飞书安全策略拦截消息延迟高
优化建议：
# 调整消息处理参数openclaw config set channels.feishu.concurrency 10openclaw config set channels.feishu.timeout 30openclaw config set channels.feishu.retry_attempts 3八、高级配置
8.1 多环境配置
# 配置文件示例：~/.openclaw/config.yamlchannels: feishu: # 生产环境 production: app_id: "cli_prod_xxxx" app_secret: "${FEISHU_PROD_SECRET}" enabled: true # 测试环境 staging: app_id: "cli_test_xxxx" app_secret: "${FEISHU_TEST_SECRET}" enabled: false # 开发环境 development: app_id: "cli_dev_xxxx" app_secret: "${FEISHU_DEV_SECRET}" enabled: false8.2 安全增强配置
security: # 启用消息加密 encryption: true encrypt_key: "${FEISHU_ENCRYPT_KEY}" # IP白名单 ip_whitelist: - "127.0.0.1" - "192.168.1.0/24" # 访问令牌刷新 token_refresh: 7200 # 2小时刷新一次 # 审计日志 audit_log: true log_path: "/var/log/openclaw/audit.log"8.3 性能调优
# 调整并发数openclaw config set channels.feishu.concurrency 20# 设置超时时间openclaw config set channels.feishu.timeout 60# 启用消息缓存openclaw config set channels.feishu.cache.enabled trueopenclaw config set channels.feishu.cache.ttl 300# 连接池配置openclaw config set channels.feishu.connection_pool.min 5openclaw config set channels.feishu.connection_pool.max 508.4 监控与告警
# 启用健康检查openclaw config set channels.feishu.health_check.enabled trueopenclaw config set channels.feishu.health_check.interval 30# 配置告警openclaw config set channels.feishu.alerts.enabled trueopenclaw config set channels.feishu.alerts.webhook "https://hooks.slack.com/..."openclaw config set channels.feishu.alerts.thresholds.error_rate 0.1openclaw config set channels.feishu.alerts.thresholds.latency 1000九、故障排查流程图
graph TD A[连接出现问题] --> B{能收到配对码吗?} B -->|能| C[执行配对命令] C --> D[配对成功?] D -->|是| E[✅ 连接成功] D -->|否| F[检查网络连接] F --> G[网络正常?] G -->|是| H[检查凭证有效期] G -->|否| I[修复网络问题] H --> J[凭证有效?] J -->|是| K[检查飞书应用状态] J -->|否| L[重新获取凭证] B -->|不能| M{终端显示二维码?} M -->|是| N[用飞书扫码] M -->|否| O[检查App ID/Secret] O --> P[凭证正确?] P -->|是| Q[检查应用权限] P -->|否| R[重新获取凭证] N --> E R --> S[重新配置] S --> B K --> T[应用已发布?] T -->|是| U[检查机器人是否在会话中] T -->|否| V[发布应用] U --> W[在会话中?] W -->|是| X[查看详细错误日志] W -->|否| Y[将机器人加入会话] X --> Z[根据错误码处理] classDef success fill:#d4edda,stroke:#155724 classDef warning fill:#fff3cd,stroke:#856404 classDef danger fill:#f8d7da,stroke:#721c24 classDef info fill:#d1ecf1,stroke:#0c5460 class E success class F,G,H,I,J,K,L warning class M,N,O,P,Q,R danger class S,T,U,V,W,X,Y,Z info十、附录
10.1 错误代码表
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
10.2 相关命令速查
# 基础命令openclaw channels list # 列出所有通道openclaw channels enable feishu # 启用飞书通道openclaw channels disable feishu # 禁用飞书通道openclaw channels restart feishu # 重启飞书通道# 诊断命令openclaw feishu debug # 调试模式openclaw feishu test "消息" # 测试消息openclaw feishu webhook info # 查看webhook信息# 配置命令openclaw config get channels.feishu # 查看飞书配置openclaw config set channels.feishu.app_id "xxx" # 设置App IDopenclaw config unset channels.feishu # 清除配置10.3 资源链接
-
飞书开放平台 -
OpenClaw 官方文档 -
飞书插件 GitHub -
问题反馈 -
社区支持
10.4 联系支持
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
文档版本
-
版本：v2.1 -
更新日期：2024-12-17 -
适用版本：OpenClaw v0.8.0+ -
飞书插件版本：v1.2.0+
更新日志
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
本文为作者原创 转载时请注明出处 谢谢
乱码三千 – 点滴积累 ,欢迎来到乱码三千技术博客站