OpenClaw 飞书集成问题排查与解决完整指南

前言

在使用 OpenClaw 集成飞书时，遇到了一个典型且棘手的问题：消息单向通信。即 OpenClaw 可以向飞书发送消息，但飞书发来的消息无法得到回复。本文记录完整的排查过程和最终解决方案。

问题现象

症状描述

  1. 单向通信正常：OpenClaw 可以成功向飞书发送消息
  2. 双向通信失败：飞书发送给 OpenClaw 的消息无回复
  3. 配对问题：每次发消息都要求重新配对（pairing code）
  4. 大量警告：日志中持续出现 duplicate plugin id detected 警告

错误日志示例

Config warnings:
- plugins.entries.feishu: plugin feishu: duplicate plugin id detected; 
  later plugin may be overridden 
  (/home/user/.nvm/versions/node/v22.22.0/lib/node_modules/openclaw/extensions/feishu/index.ts)

问题根源分析

1. 多插件冲突

OpenClaw 支持多种方式安装飞书插件，可能导致同时存在多个飞书插件：

1. ~/.openclaw/extensions/feishu          (global，自定义安装)
2. ~/.openclaw/extensions/openclaw-feishu (global，社区版本)
3. ~/.nvm/.../openclaw/extensions/feishu  (stock，内置版本)

当这些插件同时存在时，会导致：

  • 插件 ID 冲突
  • 配置覆盖混乱
  • 消息路由错误

2. Session 路由问题

通过日志分析发现，飞书消息被错误路由到 webchat 会话：

{
  "subsystem": "gateway/channels/feishu",
  "message": "received message from ou_xxx in oc_xxx (p2p)"
}
{
  "subsystem": "agent/embedded",
  "runId": "xxx",
  "sessionId": "webchat-session-id",
  "messageChannel": "webchat"  // ❌ 错误！应该是 feishu
}

核心问题：飞书消息使用了 webchat 的 session，导致回复发送到 web 界面而非飞书。

3. 配对信息未持久化

每次发消息都生成新的配对码，说明：

  • 配对信息没有正确保存
  • 或者插件冲突导致配对信息被覆盖

完整解决方案

步骤 1：停止 Gateway

openclaw gateway stop

步骤 2：彻底清理飞书相关内容

2.1 删除所有插件目录
# 删除 global extensions 目录下的飞书插件
rm -rf ~/.openclaw/extensions/feishu*

# 删除备份目录（如果有）
rm -rf ~/.openclaw/extensions/*.backup
2.2 清理配置文件

使用 jq 删除配置中的飞书相关项：

jq 'del(.channels.feishu) | 
    del(.plugins.entries.feishu) | 
    del(.plugins.entries."@openclaw/feishu") | 
    del(.plugins.entries."openclaw-feishu")' \
    ~/.openclaw/openclaw.json > /tmp/openclaw-clean.json

mv /tmp/openclaw-clean.json ~/.openclaw/openclaw.json
2.3 清理 Pairing 数据
rm -rf ~/.openclaw/pairing/feishu* 2>/dev/null

步骤 3：重新配置飞书

3.1 启用内置飞书插件

只使用 OpenClaw 内置的 stock 飞书插件：

openclaw plugins enable feishu
3.2 配置飞书应用信息
# 启用飞书 channel
openclaw config set channels.feishu.enabled true

# 配置应用 ID 和密钥
openclaw config set channels.feishu.appId "cli_your_app_id"
openclaw config set channels.feishu.appSecret "your_app_secret"

# 【重要】配置 session 模式为 per-chat
openclaw config set channels.feishu.sessionMode "per-chat"

关键配置说明：

  • sessionMode: "per-chat" - 确保每个飞书对话使用独立会话
  • 不设置此项会导致飞书消息路由到默认会话（如 webchat）

步骤 4：启动 Gateway 并验证

# 启动 Gateway
openclaw gateway start

# 等待几秒让服务完全启动
sleep 3

# 检查是否有冲突警告
openclaw gateway status 2>&1 | grep -i "duplicate"

预期结果：应该没有任何 duplicate 警告输出。

步骤 5：配对与测试

5.1 发送测试消息
openclaw message send \
  --channel feishu \
  --target ou_your_user_id \
  --message "测试消息"
5.2 处理配对请求

首次使用时，飞书会提示配对：

OpenClaw: access not configured.
Your Feishu user id: ou_xxx
Pairing code: ABC123
Ask the bot owner to approve with:
openclaw pairing approve feishu ABC123

立即执行批准命令（配对码有时效性）：

openclaw pairing approve feishu ABC123

或者配置自动批准白名单：

openclaw config set channels.feishu.senders.allowed '["ou_your_user_id"]'
openclaw gateway restart
5.3 验证双向通信
  1. OpenClaw → 飞书：使用上述命令发送消息
  2. 飞书 → OpenClaw：在飞书中回复消息
  3. 验证回复：检查是否收到 OpenClaw 的回复

验证清单

完成配置后，检查以下项目：

# ✅ 1. 无插件冲突警告
openclaw gateway status 2>&1 | grep duplicate
# 应该无输出

# ✅ 2. 只有一个飞书插件
openclaw plugins list | grep -i feishu
# 应该只显示一个 loaded 的 feishu

# ✅ 3. 配置正确
openclaw config get channels.feishu | jq '.sessionMode'
# 应该输出 "per-chat"

# ✅ 4. 飞书 WebSocket 连接正常
tail -100 /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | grep "feishu.*WebSocket"
# 应该看到 "WebSocket client started"

# ✅ 5. 消息路由正确
# 发送飞书消息后检查日志
tail -100 /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | grep "messageChannel"
# 应该看到 messageChannel=feishu（而非 webchat）

常见问题 FAQ

Q1: 为什么会有多个飞书插件？

A: 可能原因：

  1. 使用 openclaw plugins install 安装了社区版本
  2. 手动复制了插件到 ~/.openclaw/extensions/
  3. 系统升级后内置插件路径变化

建议：始终使用内置插件，避免手动安装。

Q2: sessionMode 为什么重要？

A:

  • 默认情况下，多个 channel 可能共享同一个 session
  • sessionMode: "per-chat" 确保每个飞书对话有独立的会话
  • 没有独立会话，回复会发送到错误的 channel

Q3: 配对码一直变化怎么办？

A:

  • 立即批准配对码（不要延迟）
  • 或者使用 senders.allowed 白名单自动批准
  • 检查是否有插件冲突导致配对信息丢失

Q4: 如何查看详细日志？

A:

# 实时查看日志
tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

# 过滤飞书相关日志
tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | grep feishu

# 查看错误日志
tail -100 /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | grep -i error

Q5: 清理后如何备份配置？

A:

# 备份配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup

# 恢复配置
cp ~/.openclaw/openclaw.json.backup ~/.openclaw/openclaw.json
openclaw gateway restart

技术细节

插件加载优先级

OpenClaw 插件加载顺序：

  1. global extensions（~/.openclaw/extensions/）
  2. stock extensions（OpenClaw 内置）

当两者 ID 相同时，global 优先，但会触发冲突警告。

Session 路由机制

// 期望的路由逻辑
Message from Feishu 
  → Create/Reuse Feishu Session
  → Process with Agent
  → Reply to Feishu

// 错误的路由（无 sessionMode 配置）
Message from Feishu 
  → Reuse Default/Webchat Session  // ❌
  → Process with Agent
  → Reply to Webchat  // ❌ 回复到错误的 channel

WebSocket 连接状态

飞书使用 WebSocket 长连接接收消息：

# 检查连接状态
tail -100 /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | \
  grep "feishu.*WebSocket"

# 正常输出示例：
# feishu[default]: starting WebSocket connection...
# feishu[default]: WebSocket client started

如果连接断开，消息接收会失败。

预防措施

1. 使用配置管理

创建配置模板文件：

# ~/.openclaw/feishu-config-template.json
{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_your_app_id",
      "appSecret": "your_app_secret",
      "sessionMode": "per-chat",
      "senders": {
        "allowed": ["ou_your_user_id"]
      }
    }
  }
}

2. 版本控制

# 记录工作配置的 Git commit
cd ~/.openclaw
git init
git add openclaw.json
git commit -m "Working feishu config"

3. 定期检查

创建检查脚本：

#!/bin/bash
# check-feishu.sh

echo "=== 飞书插件检查 ==="
FEISHU_COUNT=$(openclaw plugins list 2>&1 | grep -c "feishu.*loaded")
if [ "$FEISHU_COUNT" -eq 1 ]; then
    echo "✅ 只有一个飞书插件"
else
    echo "❌ 发现 $FEISHU_COUNT 个飞书插件，可能存在冲突"
fi

echo ""
echo "=== 配置检查 ==="
SESSION_MODE=$(openclaw config get channels.feishu.sessionMode 2>&1 | grep -v "^Config")
if [ "$SESSION_MODE" = '"per-chat"' ]; then
    echo "✅ sessionMode 配置正确"
else
    echo "❌ sessionMode 未配置或不正确"
fi

echo ""
echo "=== 连接状态 ==="
if tail -50 /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | \
   grep -q "feishu.*WebSocket client started"; then
    echo "✅ WebSocket 连接正常"
else
    echo "⚠️  WebSocket 状态未知"
fi

4. 文档化

记录你的配置：

# 我的飞书配置备忘

## 应用信息
- App ID: cli_xxx
- 配对 User ID: ou_xxx

## 关键配置
- sessionMode: per-chat
- WebSocket 模式：enabled

## 最后验证时间
- 2026-03-02: ✅ 双向通信正常

## 已知问题
- 无

总结

问题核心

多插件冲突 + Session 路由错误 = 单向通信失败

解决要点

  1. 彻底清理：删除所有冲突插件和配置
  2. 使用内置插件：只启用 stock 飞书插件
  3. 正确配置：设置 sessionMode: "per-chat"
  4. 验证路由：确认消息使用正确的 session

关键命令速查

# 清理
rm -rf ~/.openclaw/extensions/feishu*
jq 'del(.channels.feishu) | del(.plugins.entries.feishu)' \
  ~/.openclaw/openclaw.json > /tmp/clean.json
mv /tmp/clean.json ~/.openclaw/openclaw.json

# 配置
openclaw plugins enable feishu
openclaw config set channels.feishu.enabled true
openclaw config set channels.feishu.sessionMode "per-chat"
openclaw config set channels.feishu.appId "your_app_id"
openclaw config set channels.feishu.appSecret "your_secret"

# 启动
openclaw gateway restart

# 验证
openclaw gateway status 2>&1 | grep duplicate
openclaw plugins list | grep feishu

后续建议

  1. 不要手动安装飞书插件，始终使用内置版本
  2. 配置后立即备份 openclaw.json
  3. 定期检查是否出现新的插件冲突
  4. 更新 OpenClaw 后重新验证飞书功能

参考资源

  • OpenClaw 官方文档：https://docs.openclaw.ai
  • 飞书开放平台：https://open.feishu.cn
  • OpenClaw GitHub：https://github.com/openclaw/openclaw
  • 社区讨论：https://discord.com/invite/clawd

写作时间：2026-03-02
问题状态：✅ 已解决
配置环境：OpenClaw 2026.2.26 / Node.js 22.22.0 / Ubuntu 24.04

如有问题欢迎交流讨论！

# asp.net # 服务器
Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

学生党福音：OpenClaw+nanobot搭建学习监督助手

本文介绍了如何在星图GPU平台上自动化部署🐈 nanobot：超轻量级OpenClaw镜像，构建智能学习监督助手。该方案利用轻量级模型实现网课进度跟踪、自动生成练习题和错题整理功能，特别适合学生群体通过QQ机器人实现移动端学习管理，显著提升学习效率。

avatar 龙虾开发者社区

OpenClaw+GLM-4.7-Flash语音交互：对接Whisper实现语音控制

本文介绍了如何在星图GPU平台上自动化部署【ollama】GLM-4.7-Flash镜像，构建语音交互系统。该系统结合Whisper语音识别与GLM-4.7-Flash的指令理解能力，实现智能家居控制等场景的语音操作，提升日常任务执行效率。

avatar 龙虾开发者社区

OpenClaw创意工坊：用nanobot镜像生成技术海报文案

本文介绍了如何在星图GPU平台上自动化部署🐈 nanobot：超轻量级OpenClaw镜像，快速生成技术海报文案。该镜像基于Qwen3-4B模型，能将复杂技术术语转化为通俗表达，适用于技术活动宣传、社交媒体推广等场景，显著提升内容创作效率。

avatar 龙虾开发者社区