OpenClaw 对接飞书完整配置指南 — 100 个常见问题与解决方案

OpenClaw 对接飞书 — 全流程配置教程

本教程基于实际部署经验，手把手教你将 OpenClaw 接入飞书，让 AI 助手直接在飞书群聊/私聊中响应消息。整个过程分为 6 个步骤，预计 15-30 分钟完成。

前置条件：已安装 OpenClaw 并完成 openclaw onboard 向导；已有飞书企业/团队账号且拥有管理员权限。

步骤 1 在飞书开放平台创建应用

1. 打开飞书开放平台，登录管理员账号。

2. 点击「创建企业自建应用」，填写应用名称（如 "OpenClaw Bot"）和描述。

3. 创建完成后，进入应用详情页，记录 App ID 和 App Secret：

App ID: cli_a9xxxxxxxxxxxxxxx App Secret: v3XQxxxxxxxxxxxxxxxxxxxxxxxx

安全提醒：App Secret 是敏感信息，请勿泄露。不要将其提交到 Git 仓库或公开分享。

步骤 2 配置应用权限与事件订阅

在飞书开放平台的应用管理页面中：

2.1 添加机器人能力：

进入「添加应用能力」→ 勾选「机器人」。

2.2 配置权限：

进入「权限管理」，搜索并开启以下权限：

im:message                    # 获取与发送单聊/群聊消息
im:message.group_at_msg       # 接收群聊中 @机器人 消息
im:message.group_at_msg:readonly  # 读取群聊中 @机器人 消息
im:message.p2p_msg            # 接收私聊消息
im:message.p2p_msg:readonly   # 读取私聊消息
im:message:send_as_bot        # 以机器人身份发送消息
im:chat                       # 获取群信息
im:chat:readonly              # 读取群信息
contact:user.id:readonly      # 读取用户 ID

2.3 配置事件订阅：

进入「事件订阅」→ 选择 WebSocket 模式（推荐，无需公网地址）。

添加以下事件：

im.message.receive_v1         # 接收消息事件

步骤 3 安装 OpenClaw 飞书插件

在 OpenClaw 中安装官方飞书插件：

openclaw plugin install @openclaw/feishu

安装完成后，确认插件已启用：

openclaw plugin list
# 应该看到：
# feishu  @openclaw/feishu@2026.3.2  enabled

提示：插件安装后会自动写入 ~/.openclaw/openclaw.json 的 plugins 配置段。

步骤 4 配置 openclaw.json 中的飞书渠道

编辑 ~/.openclaw/openclaw.json，在 "channels" 中添加飞书配置：

"channels": { "feishu": { "enabled": true, "appId": "cli_a9xxxxxxxxxxxxxxx", // 飞书 App ID "appSecret": "v3XQrxxxxxxxxxxxxxxxx", // 飞书 App Secret "connectionMode": "websocket", // 连接模式：websocket（推荐） "domain": "feishu", // feishu 或 lark（海外版） "groupPolicy": "open", // 群聊策略：open/allowlist "groupSessionScope": "group", // 群会话范围 "groupAllowFrom": [ // 允许的群聊 ID 列表 "oc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ], "allowFrom": [ // 允许的来源列表 "oc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ], "dmPolicy": "open", // 私聊策略：open/closed "requireMention": false // 是否需要 @机器人才响应 } }

注意：groupAllowFrom 和 allowFrom 中的群组 ID 以 oc_ 开头，可在飞书群设置中查看，或通过飞书 API 获取。

步骤 5 启用插件并在飞书中发布应用

5.1 确认 plugins 配置：

"plugins": { "entries": { "feishu": { "enabled": true } } }

5.2 在飞书开放平台发布应用：

回到飞书开放平台 → 「版本管理与发布」→ 创建版本 → 提交审核。

如果是内部应用（企业自建），审核通常即时通过。

5.3 将机器人添加到群聊：

打开目标飞书群 → 群设置 → 群机器人 → 添加机器人 → 选择刚创建的应用。

步骤 6 启动 OpenClaw 并验证连接

重启 OpenClaw Gateway 使配置生效：

# 重启 Gateway
openclaw gateway restart

# 查看日志确认飞书连接成功
openclaw logs --tail 50

成功连接后，日志中应出现：

[feishu] WebSocket connected [feishu] Bot ready, listening for messages...

在飞书群中发送消息（或 @机器人），如果 OpenClaw 正常回复，说明对接成功。

完成！现在你的 OpenClaw AI 助手已经在飞书中运行了。下面是 100 个配置中常见的问题与解决方案。

100 个常见问题 — 目录概览

以下是 OpenClaw 对接飞书过程中最常见的 100 个问题，按类别分组。点击分类快速跳转：

一、飞书开放平台配置

#1 – #15：创建应用、权限、事件订阅等

二、插件安装与更新

#16 – #25：插件安装失败、版本冲突等

三、openclaw.json 配置

#26 – #40：配置字段、格式、验证等

四、WebSocket 连接问题

#41 – #55：连接失败、断线、超时等

五、群聊相关问题

#56 – #68：群聊不响应、权限、@机器人等

六、私聊相关问题

#69 – #76：私聊无响应、消息丢失等

七、权限与安全问题

#77 – #85：API 权限、Token 过期等

八、飞书技能（Skills）

#86 – #92：飞书文档/云盘/Wiki 技能等

九、消息收发问题

#93 – #98：富文本、图片、卡片等

十、其他问题

#99 – #100：Lark 海外版、性能等

一、飞书开放平台配置问题(#1 – #15)

#1 找不到「创建企业自建应用」入口

飞书开放平台首页没有「创建企业自建应用」按钮

原因：当前登录账号没有管理员或开发者权限。
解决：①联系飞书团队管理员，在「飞书管理后台 → 应用管理」中授予你开发者权限；②或使用具有管理员角色的账号登录 open.feishu.cn。

#2 App ID 和 App Secret 在哪里获取？

创建应用后找不到 App ID 和 App Secret

原因：飞书开放平台界面改版，位置可能变化。
解决：进入应用详情页 → 左侧菜单「凭证与基础信息」→ 页面顶部即可看到 App ID（以 cli_ 开头）和 App Secret。点击「显示」查看完整 Secret。

#3 添加机器人能力后没有「事件订阅」菜单

添加了机器人能力，但左侧菜单看不到「事件订阅」选项

原因：需要先保存机器人能力配置。
解决：添加「机器人」能力后，点击页面底部「保存」按钮，刷新页面后左侧菜单会出现「事件与回调」→「事件订阅」。

#4 事件订阅选择 WebSocket 还是 HTTP？

不确定应该选择 WebSocket 模式还是 HTTP 回调模式

原因：飞书支持两种事件接收模式。
解决： 强烈推荐 WebSocket 模式。优势：①无需公网 IP 或域名；②无需配置 HTTPS 证书；③无需 Nginx 反向代理；④OpenClaw 原生支持。只有当你有特殊需求（如需要在负载均衡后部署多实例）时才考虑 HTTP 模式。在 openclaw.json 中设置："connectionMode": "websocket"

#5 事件订阅中找不到 im.message.receive_v1

在事件列表中搜索不到 im.message.receive_v1 事件

原因：未添加「机器人」能力或未开启相关权限。
解决：①先确认已添加「机器人」能力并保存；②在「权限管理」中搜索并开启 im:message 相关权限；③刷新事件订阅页面，搜索 im.message.receive_v1。

#6 权限申请后显示「待审核」状态

权限管理中显示：已申请 - 待管理员审核

原因：企业安全策略要求管理员审批高敏感权限。
解决：①如果你是管理员，在「飞书管理后台 → 工作台 → 应用审核」中批准；②如果不是管理员，联系管理员尽快审批；③对于企业自建应用的基础权限，通常可自动通过。

#7 应用发布审核不通过

应用版本提交后审核被拒：「请补充应用描述/隐私说明」

原因：企业自建应用在部分企业中也需要审核。
解决：①填写完整的应用描述和用途说明；②补充隐私政策（可以写内部使用说明）；③上传应用图标；④企业内部应用通常由本企业管理员审核，沟通即可通过。

#8 应用的可用范围设置

机器人创建后只有自己能看到，其他同事看不到

原因：应用默认可用范围可能限制为开发者本人。
解决：进入应用 → 「版本管理与发布」→ 编辑可用范围 → 选择「全部成员」或指定部门/人员 → 重新发布版本。

#9 测试企业与正式企业的区别

在测试企业中配置正常，切到正式企业后不工作

原因：测试企业和正式企业的 App ID 和权限是独立的。
解决：①在正式企业中重新创建应用或迁移配置；②更新 openclaw.json 中的 appId 和 appSecret；③重新申请并审批权限；④重新发布应用。

#10 多个飞书企业如何配置？

需要在多个飞书企业中同时使用 OpenClaw Bot

原因：每个飞书企业需要独立的应用和凭证。
解决：目前 OpenClaw 的飞书渠道配置只支持单个企业。如需多企业，可运行多个 OpenClaw 实例，每个实例使用不同的配置文件：

OPENCLAW_CONFIG=~/.openclaw/openclaw-company-a.json openclaw gateway start
OPENCLAW_CONFIG=~/.openclaw/openclaw-company-b.json openclaw gateway start

#11 飞书 ISV（应用商店）应用 vs 企业自建应用

应该创建 ISV 应用还是企业自建应用？

原因：两者适用场景不同。
解决：个人/团队使用选「企业自建应用」，无需上架飞书应用商店，审核流程简单。ISV 应用适合要分发给其他企业的场景，需要更复杂的审核和 OAuth 授权流程。OpenClaw 目前主要面向企业自建场景。

#12 Encrypt Key 需要配置吗？

飞书开放平台中的 Encrypt Key（加密密钥）是否需要填写？

原因：Encrypt Key 用于 HTTP 回调模式下的消息加密。
解决：如果使用 WebSocket 模式（推荐），不需要配置 Encrypt Key。如果使用 HTTP 回调模式，建议配置以增强安全性，并在 openclaw.json 中添加对应的 "encryptKey" 字段。

#13 Verification Token 在哪里使用？

飞书应用中有一个 Verification Token，不确定用途

原因：Verification Token 是旧版验证方式。
解决：WebSocket 模式下不需要 Verification Token。它主要用于 HTTP 回调模式下的请求验证。OpenClaw 的飞书插件在 WebSocket 模式下使用 App ID + App Secret 进行认证。

#14 机器人描述和头像怎么设置？

想要自定义机器人在飞书中的名称、头像和描述

原因：机器人在飞书中展示的信息来自飞书开放平台配置。
解决：在飞书开放平台 → 应用详情 → 「机器人」配置页面中，可以设置：①机器人名称；②机器人头像（建议 256x256 PNG）；③机器人描述。修改后需要创建新版本并发布。

#15 应用状态为「已停用」

飞书开放平台显示应用已停用，机器人无法使用

原因：管理员手动停用了应用，或应用长期未使用被自动停用。
解决：在飞书管理后台 → 「工作台」→ 找到对应应用 → 点击「启用」。如果是管理员主动停用的，需要和管理员沟通。

二、插件安装与更新问题(#16 – #25)

#16 openclaw plugin install @openclaw/feishu 失败

Error: npm install failed for @openclaw/feishu

原因：npm 网络问题或 Node.js 版本不兼容。
解决：

# 使用国内镜像
npm config set registry https://registry.npmmirror.com
openclaw plugin install @openclaw/feishu

# 或手动安装
cd ~/.openclaw/extensions
mkdir feishu && cd feishu
npm init -y
npm install @openclaw/feishu

#17 插件安装后 plugin list 中看不到

openclaw plugin list 显示为空

原因：插件注册信息未正确写入 openclaw.json。
解决：检查 ~/.openclaw/openclaw.json 中 plugins.entries 和 plugins.installs 是否都包含 feishu 条目。如果缺失，手动添加：

"plugins": {
  "entries": { "feishu": { "enabled": true } },
  "installs": {
    "feishu": {
      "source": "npm",
      "spec": "@openclaw/feishu",
      "installPath": "~/.openclaw/extensions/feishu"
    }
  }
}

#18 飞书插件与 OpenClaw 版本不兼容

Error: Plugin feishu requires openclaw >= 2026.3.x but found 2026.2.x

原因：飞书插件需要较新版本的 OpenClaw。
解决：

# 更新 OpenClaw 到最新版
npm install -g openclaw@latest
# 再安装飞书插件
openclaw plugin install @openclaw/feishu

#19 插件安装目录权限不足

EACCES: permission denied, mkdir '~/.openclaw/extensions/feishu'

原因：OpenClaw 配置目录权限问题。
解决：

# 修复权限
chmod -R 755 ~/.openclaw
# 重新安装
openclaw plugin install @openclaw/feishu

#20 Windows 上安装飞书插件报 EPERM 错误

Error: EPERM: operation not permitted, rename '...\extensions\feishu'

原因：Windows 文件锁定或杀毒软件拦截。
解决：①关闭所有 OpenClaw 进程后重试；②以管理员权限运行；③将 %USERPROFILE%\.openclaw 目录添加到杀毒软件白名单。

#21 如何更新飞书插件到最新版？

想更新 @openclaw/feishu 插件

原因：需要获取最新功能或修复。
解决：

# 直接重新安装即可更新
openclaw plugin install @openclaw/feishu
# 重启 Gateway 生效
openclaw gateway restart

#22 插件安装后 enabled 为 false

插件安装了但 openclaw.json 中 enabled 为 false

原因：某些情况下插件安装后不会自动启用。
解决：手动编辑 ~/.openclaw/openclaw.json，将 plugins.entries.feishu.enabled 改为 true，然后重启 Gateway。

#23 飞书插件的 integrity/shasum 校验失败

Error: Integrity check failed for @openclaw/feishu

原因：下载过程中包损坏或被篡改。
解决：

# 清除缓存后重新安装
npm cache clean --force
rm -rf ~/.openclaw/extensions/feishu
openclaw plugin install @openclaw/feishu

#24 离线环境如何安装飞书插件？

服务器无外网访问，无法从 npm 安装插件

原因：内网服务器无法访问 npm 仓库。
解决：①在有网络的机器上运行 npm pack @openclaw/feishu 下载 tgz 包；②将 tgz 传到目标服务器；③手动解压到 ~/.openclaw/extensions/feishu；④在 openclaw.json 中手动添加 plugins 配置。

#25 卸载飞书插件后残留配置

卸载插件后 openclaw.json 中仍有 feishu 相关配置

原因：插件卸载只删除文件，不清理配置。
解决：手动编辑 ~/.openclaw/openclaw.json，删除 channels.feishu、plugins.entries.feishu 和 plugins.installs.feishu 三处配置，然后重启 Gateway。

三、openclaw.json 配置问题(#26 – #40)

#26 JSON 格式错误导致启动失败

SyntaxError: Unexpected token in JSON at position xxx

原因：手动编辑 openclaw.json 时引入了语法错误（多余逗号、缺少引号等）。
解决：使用 JSON 验证工具检查格式，推荐用 VS Code 打开，语法错误会自动高亮。备份文件在 openclaw.json.bak，可用于恢复。

#27 channels.feishu 配置放在哪个位置？

不确定 feishu 配置应该放在 openclaw.json 的哪个位置

原因：openclaw.json 结构较复杂。
解决：飞书渠道配置放在顶层的 "channels" 对象中，与 "models"、"agents"、"gateway" 同级。如果没有 "channels" 字段，手动添加即可。

#28 appId 格式不正确

Error: Invalid appId format. Expected cli_xxxxxxxxxx

原因：appId 必须以 cli_ 开头，后跟 16-20 位字母数字。
解决：检查是否复制了完整的 App ID。正确格式示例："cli_a92393ccde789bd9"。注意不要多复制空格或换行符。

#29 appSecret 包含特殊字符导致 JSON 解析失败

SyntaxError: Unexpected token 后跟 App Secret 中的反斜杠

原因：appSecret 中可能包含 JSON 需要转义的字符。
解决：确保 appSecret 用双引号包裹，如果包含 \ 或 "，需要转义为 \\ 或 \"。一般飞书 Secret 只包含字母数字，不需要特殊处理。

#30 connectionMode 可选值有哪些？

不确定 connectionMode 应该填什么

原因：配置字段文档不完整。
解决：支持两个值： "websocket"（推荐）— 使用飞书长连接，无需公网 IP； "webhook" — 使用 HTTP 回调，需要公网可访问的地址。绝大多数场景使用 websocket 即可。

#31 domain 字段填 feishu 还是 lark？

domain 字段应该填什么？

原因：飞书有国内版和海外版（Lark），API 域名不同。
解决：国内用户填 "feishu"（使用 open.feishu.cn 域名），海外用户填 "lark"（使用 open.larksuite.com 域名）。

#32 groupPolicy 的 open 和 allowlist 区别

groupPolicy 应该设 open 还是 allowlist？

原因：控制机器人在群聊中的响应范围。
解决： "open" — 机器人被加入的所有群聊都会响应； "allowlist" — 仅在 groupAllowFrom 列表中的群聊才响应。建议初期测试用 allowlist 控制范围，稳定后可改为 open。

#33 如何获取群聊 ID（oc_ 开头）？

groupAllowFrom 需要群聊 ID，不知道怎么获取

原因：飞书的群聊 ID 不在界面上直接显示。
解决：方法一：使用飞书 API 调试工具（在开放平台 → API 调试台 → im/v1/chats）获取机器人加入的群列表；方法二：查看 OpenClaw 日志，当机器人收到群消息时会打印群聊 ID；方法三：设 groupPolicy: "open" 先运行，从日志中找到目标群的 oc_ ID。

#34 groupSessionScope 的作用

groupSessionScope 设 group 还是 per-user？

原因：控制群聊中的会话上下文范围。
解决： "group" — 整个群共享同一个会话上下文，所有人的消息在同一对话中； "per-user" — 群中每个用户有独立的会话上下文。大多数场景用 "group" 更自然。

#35 dmPolicy 的 open 和 closed 区别

dmPolicy 应该设什么？

原因：控制机器人是否接受私聊消息。
解决： "open" — 所有用户都可以和机器人私聊； "closed" — 禁止私聊，机器人不响应私聊消息。如果只想在群里使用，设为 closed。

#36 requireMention 设置为 true 后不响应

设置 requireMention: true 后，@机器人也不回复

原因：飞书的 @mention 检测与权限配置有关。
解决：①确认已开启 im:message.group_at_msg 权限；②确认事件订阅中有 im.message.receive_v1；③尝试先设为 false 排除其他问题，再改回 true。

#37 配置文件修改后不生效

修改了 openclaw.json 但机器人行为没变化

原因：Gateway 需要重启才能加载新配置。
解决：

openclaw gateway restart

部分配置（如 channels）不支持热重载，必须重启。

#38 openclaw.json 被覆盖 / 丢失自定义配置

运行 openclaw onboard 后发现之前的飞书配置丢失

原因：某些向导操作可能覆盖配置。
解决：OpenClaw 会自动创建备份文件 openclaw.json.bak（最多保留 4 份）。从备份恢复：

cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.json
openclaw gateway restart

#39 飞书配置和其他渠道（Telegram/Discord）冲突吗？

已有 Telegram 渠道，加飞书会不会冲突？

原因：不确定多渠道并行是否支持。
解决：不冲突。OpenClaw 支持多渠道并行，channels 中可以同时配置 feishu、telegram、discord 等，它们独立运行互不干扰。

#40 飞书渠道配置的完整字段列表

想了解所有可用的飞书渠道配置选项

完整字段参考：

{
  "enabled": true,          // 是否启用
  "appId": "cli_xxx",       // 飞书 App ID
  "appSecret": "xxx",       // 飞书 App Secret
  "connectionMode": "websocket", // websocket | webhook
  "domain": "feishu",       // feishu | lark
  "groupPolicy": "open",    // open | allowlist
  "groupSessionScope": "group", // group | per-user
  "groupAllowFrom": [],     // 允许的群聊 ID
  "allowFrom": [],           // 允许的来源
  "dmPolicy": "open",       // open | closed
  "requireMention": false   // 是否需要 @
}

四、WebSocket 连接问题(#41 – #55)

#41 WebSocket 连接失败：401 Unauthorized

[feishu] WebSocket connection failed: 401 Unauthorized

原因：appId 或 appSecret 不正确。
解决：①重新检查飞书开放平台中的 App ID 和 App Secret；②确保复制时没有多余空格；③确认应用已发布且处于启用状态。

#42 WebSocket 连接失败：403 Forbidden

[feishu] WebSocket connection failed: 403 Forbidden

原因：应用未启用 WebSocket 事件订阅。
解决：在飞书开放平台 → 事件订阅 → 确认已选择「WebSocket」模式，并添加了 im.message.receive_v1 事件。保存后等待几秒再重试。

#43 WebSocket 连接超时

[feishu] WebSocket connection timeout after 30000ms

原因：网络问题或防火墙拦截。
解决：①检查服务器能否访问 open.feishu.cn（执行 curl -I https://open.feishu.cn）；②如果在内网环境，检查代理设置；③尝试设置环境变量：HTTPS_PROXY=http://proxy:port。

#44 WebSocket 频繁断线重连

[feishu] WebSocket disconnected, reconnecting... (attempt 5/10)

原因：网络不稳定或飞书服务端主动断开。
解决：①检查服务器网络稳定性；②飞书 WebSocket 有心跳机制，确保服务器不会因 idle 被防火墙断开；③如果在 Docker 中运行，检查容器网络配置。OpenClaw 有自动重连机制，偶尔断线是正常的。

#45 代理环境下 WebSocket 连接失败

[feishu] WebSocket connection error: ECONNREFUSED

原因：企业网络通过代理访问外网，WebSocket 被代理拦截。
解决：

# 设置代理环境变量
export HTTPS_PROXY=http://proxy.company.com:8080
export HTTP_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1
openclaw gateway restart

如果代理不支持 WebSocket 升级，需要联系网络管理员放行。

#46 SSL/TLS 证书验证失败

Error: unable to verify the first certificate / DEPTH_ZERO_SELF_SIGNED_CERT

原因：企业代理使用自签名证书进行 HTTPS 解密。
解决：①将企业 CA 证书添加到系统信任链；②或设置 NODE_TLS_REJECT_UNAUTHORIZED=0（不推荐，仅调试用）；③最好的方案是让运维将飞书域名加入代理白名单，不做 HTTPS 解密。

#47 多实例同时连接同一飞书应用

两台服务器同时连接，只有一台能收到消息

原因：飞书 WebSocket 模式下同一应用只允许一个活跃连接。
解决：确保只有一个 OpenClaw 实例连接同一个飞书应用。如需高可用，可使用主备模式而非同时连接。如需多实例，需要在飞书创建多个应用。

#48 Gateway 未启动导致飞书不响应

飞书发消息没有任何反应

原因：OpenClaw Gateway 未在运行。
解决：

# 检查 Gateway 状态
openclaw gateway status
# 如果未运行，启动它
openclaw gateway start
# 或查看日志定位问题
openclaw logs --tail 100

#49 连接成功但收不到消息事件

[feishu] WebSocket connected 但发消息没反应

原因：事件订阅配置不正确或权限未生效。
解决：①确认飞书开放平台中事件订阅已保存且生效；②检查是否添加了 im.message.receive_v1 事件；③确认应用版本已发布；④检查群中是否已添加机器人。

#50 Docker 容器中 WebSocket 连接问题

Docker 中运行 OpenClaw，飞书 WebSocket 连接不上

原因：Docker 网络隔离或 DNS 解析问题。
解决：

# 使用 host 网络模式
docker run --network host openclaw ...

# 或确保容器 DNS 能解析飞书域名
docker run --dns 8.8.8.8 openclaw ...

#51 WebSocket 连接后立即断开

[feishu] WebSocket connected [feishu] WebSocket disconnected (code: 1006)

原因：飞书服务端验证失败或协议版本不匹配。
解决：①更新飞书插件到最新版；②检查 appId/appSecret 是否匹配当前环境（测试 vs 正式）；③查看完整日志获取更多错误信息。

#52 重启 Gateway 后飞书连接恢复慢

重启后需要等待很长时间飞书才能重新连接

原因：飞书 WebSocket 有连接冷却期。
解决：正常情况下重连在 5-15 秒内完成。如果超过 1 分钟仍未连接，检查日志是否有报错。频繁重启可能触发飞书的速率限制，建议间隔至少 30 秒。

#53 飞书域名被防火墙拦截

getaddrinfo ENOTFOUND open.feishu.cn

原因：服务器无法解析飞书域名。
解决：①检查 DNS 配置；②需要放行的域名列表：open.feishu.cn、*.feishu.cn、*.bytedance.com；③如果是内网服务器，可能需要配置 DNS 转发或手动添加 hosts。

#54 HTTP 回调模式下 Challenge 验证失败

使用 webhook 模式，飞书发送 Challenge 验证请求但验证不通过

原因：HTTP 回调地址不可达或响应格式不正确。
解决：如非特殊需求，强烈建议切换到 WebSocket 模式。如必须用 webhook：①确保回调 URL 是公网可访问的 HTTPS 地址；②确保正确返回 Challenge 响应；③检查 Nginx 反向代理配置。

#55 同时使用多个渠道时飞书连接不稳定

启用飞书+Telegram+Discord 后飞书频繁掉线

原因：资源竞争或并发连接过多。
解决：①检查服务器内存和 CPU 使用率；②确认 agents.defaults.maxConcurrent 设置合理（建议 4-8）；③如果资源不足，考虑只启用必要的渠道；④检查日志中是否有 OOM 或事件循环延迟警告。

五、群聊相关问题(#56 – #68)

#56 机器人加入群聊后不响应消息

机器人已在群中但发消息没有反应

原因：多种可能原因。
解决：逐步排查：①requireMention 是否为 true？如果是，需要 @机器人；②groupPolicy 是否为 allowlist？如果是，检查 groupAllowFrom 是否包含当前群 ID；③查看 OpenClaw 日志是否收到了消息事件；④确认 Gateway 正在运行。

#57 群聊中 @机器人没有反应

在群里 @机器人发消息，没有任何回复

原因：权限或事件配置问题。
解决：①确认飞书权限 im:message.group_at_msg 已开启并审批通过；②确认事件订阅中有 im.message.receive_v1；③确认应用最新版本已发布；④在群设置中确认机器人存在。

#58 群聊中所有消息都响应（太频繁）

不希望机器人回复每条消息，只想 @时才回复

原因：requireMention 设为 false。
解决：将 "requireMention": true 设为 true，这样机器人只在被 @时才响应。适合人数较多的群。

#59 如何限制只在指定群聊中响应？

想让机器人只在特定群中工作

原因：需要使用白名单策略。
解决：

"groupPolicy": "allowlist",
"groupAllowFrom": [
  "oc_群聊ID_1",
  "oc_群聊ID_2"
]

只有列表中的群聊会被响应。

#60 机器人被移出群聊后仍尝试发消息

[feishu] Failed to send message: bot not in chat

原因：机器人被管理员移出群聊，但还有未处理的消息队列。
解决：这是正常现象，OpenClaw 会自动停止向该群发送消息。如果日志持续报错，重启 Gateway 即可清除消息队列。

#61 群聊中多个 Bot 互相触发

群里有多个机器人，互相回复形成死循环

原因：机器人回复的消息被其他机器人当作用户消息处理。
解决：OpenClaw 默认会忽略其他机器人的消息。如果仍有问题：①设 "requireMention": true；②确认飞书插件版本为最新（旧版可能缺少 bot 消息过滤）。

#62 大群中机器人回复很慢

100+ 人的大群中机器人响应延迟明显

原因：大群消息量大，AI 模型处理需要时间。
解决：①设 "requireMention": true 减少无关消息处理；②选用更快的模型；③调整 agents.defaults.maxConcurrent 限制并发。

#63 群会话上下文混乱

机器人把不同用户的对话混在一起回复

原因：groupSessionScope 设为 "group"，所有用户共享上下文。
解决：如果需要每人独立对话，改为 "groupSessionScope": "per-user"。但注意这会让机器人无法理解群聊讨论的完整上下文。

#64 机器人在某些群能用某些群不能用

同一个配置，有些群正常有些群不响应

原因：群权限或可用范围限制。
解决：①如果用 allowlist，检查 groupAllowFrom 是否包含不工作的群 ID；②检查飞书应用的可用范围是否包含该群的成员所在部门；③某些群可能有额外的安全策略限制机器人。

#65 无法在外部群/跨企业群中使用

企业自建应用无法在包含外部人员的群中使用

原因：飞书企业自建应用默认只在本企业范围内可用。
解决：企业自建应用无法在外部群中使用，这是飞书平台限制。如需跨企业使用，需要创建 ISV 应用并上架应用商店。

#66 群公告/系统消息触发机器人响应

群公告、入群通知等系统消息也会触发机器人回复

原因：旧版插件可能未正确过滤系统消息。
解决：更新飞书插件到最新版（openclaw plugin install @openclaw/feishu）。新版本会自动过滤非文本用户消息。

#67 话题群（Thread）中机器人不响应

在飞书话题群中发消息，机器人没有反应

原因：话题群的消息格式与普通群不同。
解决：当前版本的飞书插件可能对话题群支持有限。建议在普通群中使用，或关注插件更新。可在 GitHub 提 Issue 请求支持。

#68 如何让机器人主动发消息到群聊？

想让 OpenClaw 定时或主动向群聊推送消息

原因：默认 OpenClaw 只被动响应消息。
解决：可通过 OpenClaw 的 cron 功能或自定义 Skill 实现定时推送。需要知道目标群的 chat_id，通过飞书 API 发送消息。具体请参考 OpenClaw 的 Skill 开发文档。

六、私聊相关问题(#69 – #76)

#69 私聊机器人没有回复

给机器人发私聊消息没有任何反应

原因：私聊策略或权限问题。
解决：①确认 "dmPolicy": "open"；②确认权限 im:message.p2p_msg 已开启；③确认应用可用范围包含你的账号；④在工作台中找到机器人，点击进入私聊（而非搜索同事头像）。

#70 找不到机器人进行私聊

在飞书中搜索不到机器人，无法发起私聊

原因：应用未发布或可用范围不包含你。
解决：①确认应用已发布且处于启用状态；②在飞书「工作台」→ 搜索应用名称 → 点击进入 → 发起对话；③如果仍找不到，让管理员检查应用可用范围。

#71 私聊回复内容被截断

机器人私聊回复的消息不完整，被截断了

原因：飞书单条消息有长度限制。
解决：飞书文本消息最大约 150KB。如果 AI 回复过长，OpenClaw 会自动分段发送。如果分段也失败，可能是网络问题导致后续消息未发出，检查日志。

#72 私聊中的会话记忆问题

机器人在私聊中记不住之前的对话内容

原因：会话上下文管理配置。
解决：OpenClaw 使用 session.dmScope 控制私聊会话范围。默认 "per-channel-peer" 表示每个用户在每个渠道有独立会话。确保 Gateway 持续运行，重启会清除内存中的会话。启用 hooks.internal.entries.session-memory 可持久化会话。

#73 dmPolicy 设为 closed 但仍能收到私聊

已设 dmPolicy: closed 但用户仍能和机器人私聊

原因：配置修改后未重启 Gateway。
解决：执行 openclaw gateway restart。如果重启后仍有问题，确认 openclaw.json 中的配置格式正确（注意 JSON 字符串值需要双引号）。

#74 私聊消息有明显延迟

私聊中发消息后要等 10-30 秒才收到回复

原因：AI 模型处理时间或网络延迟。
解决：①检查 OpenClaw 使用的 AI 模型响应速度；②如果用远程模型（如 Claude API），延迟包含网络往返时间；③使用本地模型（如 Ollama）可以减少延迟；④检查 Gateway 日志确认瓶颈在哪里。

#75 限制只有特定用户能私聊

想限制只有某些用户可以和机器人私聊

原因：需要私聊白名单功能。
解决：目前飞书渠道的 allowFrom 字段主要用于群聊过滤。对于私聊限制，可通过飞书开放平台的「应用可用范围」来控制 —— 只将应用设为对特定部门/人员可见即可。

#76 私聊中发送图片/文件没有反应

给机器人发图片或文件，没有回复

原因：当前版本可能只支持文本消息。
解决：OpenClaw 飞书插件目前主要处理文本消息。图片和文件支持取决于连接的 AI 模型是否支持多模态输入。如果模型支持（如 GPT-4V、Qwen Vision），需要配置多模态输入。否则发文本消息即可。

七、权限与安全问题(#77 – #85)

#77 Tenant Access Token 获取失败

[feishu] Failed to get tenant_access_token: invalid app_id or app_secret

原因：appId 或 appSecret 不正确。
解决：①重新从飞书开放平台复制 App ID 和 App Secret；②注意复制时不要包含多余字符；③如果最近重置过 Secret，需要更新配置。

#78 Token 过期导致消息发送失败

[feishu] Send message failed: token expired (99991663)

原因：飞书 Access Token 有效期为 2 小时，需要定期刷新。
解决：OpenClaw 飞书插件会自动刷新 Token。如果频繁出现此错误：①检查服务器时钟是否准确（date 命令）；②更新插件到最新版；③重启 Gateway。

#79 权限不足：no permission to send message

[feishu] Error 230001: Bot has no permission to send message in this chat

原因：机器人缺少发送消息权限或未加入群聊。
解决：①确认 im:message:send_as_bot 权限已开启；②确认机器人已被添加到目标群聊；③如果是新权限，需要创建新版本并发布。

#80 App Secret 泄露后如何处理？

App Secret 不小心提交到了公开仓库

原因：敏感信息泄露。
解决：①立即在飞书开放平台重置 App Secret；②更新 openclaw.json 中的 appSecret；③重启 Gateway；④检查是否有异常 API 调用；⑤将 openclaw.json 加入 .gitignore。

#81 如何将 appSecret 放在环境变量中？

不想在配置文件中明文保存 appSecret

原因：安全最佳实践。
解决：目前 OpenClaw 配置主要通过 JSON 文件，但可以使用环境变量替换。在启动脚本中：

export FEISHU_APP_SECRET="your_secret_here"
# 在 openclaw.json 中使用：
# "appSecret": "${FEISHU_APP_SECRET}"

或者确保 openclaw.json 的文件权限为 600（仅所有者可读写）。

#82 飞书管理员限制了 API 调用

[feishu] API rate limit exceeded (429)

原因：飞书 API 有频率限制，每个应用每分钟有调用上限。
解决：①减少消息响应频率（设 requireMention: true）；②避免在大群中不设限地响应所有消息；③OpenClaw 有内置的速率控制，确认插件为最新版本。

#83 飞书应用安全设置中的 IP 白名单

配置了 IP 白名单后机器人不工作

原因：飞书开放平台的安全设置中可配置 IP 白名单。
解决：将运行 OpenClaw 的服务器公网 IP 添加到飞书应用的 IP 白名单中。如果服务器 IP 是动态的（如家庭宽带），建议不启用 IP 白名单，或使用 VPN 固定出口 IP。

#84 OpenClaw Gateway 的 auth token 与飞书的关系

openclaw.json 中 gateway.auth.token 和飞书 appSecret 是什么关系？

原因：两者用途不同。
解决：gateway.auth.token 是 OpenClaw Gateway 本地 HTTP API 的认证令牌，用于本地访问控制。appSecret 是飞书应用的凭证，用于与飞书 API 通信。两者完全独立，不要混淆。

#85 消息传输是否加密？

担心飞书消息在传输过程中被窃听

原因：企业安全合规要求。
解决：飞书 WebSocket 连接使用 WSS（WebSocket Secure），数据经 TLS 加密传输。OpenClaw 到 AI 模型的请求也使用 HTTPS。消息在 OpenClaw 本地内存中处理，不会转发到第三方。

八、飞书技能（Skills）问题(#86 – #92)

#86 飞书文档（feishu-doc）技能安装失败

openclaw skill install feishu-doc 报错

原因：飞书技能需要额外的权限和配置。
解决：

openclaw skill install feishu-doc

安装后需要在飞书开放平台额外开启文档相关权限（如 docx:document）。注意：飞书文档技能默认 enabled: false，需要在 openclaw.json 的 skills.entries 中设为 true。

#87 飞书云盘（feishu-drive）技能无法读取文件

机器人无法访问飞书云盘中的文件

原因：缺少云盘读取权限。
解决：在飞书开放平台开启权限：drive:drive、drive:file:readonly。同时确保目标文件/文件夹对机器人应用有读取权限（在飞书云盘中分享给应用）。

#88 飞书 Wiki（feishu-wiki）技能配置

想让机器人能搜索和读取飞书知识库

原因：Wiki 技能需要独立配置。
解决：①安装 openclaw skill install feishu-wiki；②开启权限 wiki:wiki:readonly；③在 skills.entries 中设 "feishu-wiki": { "enabled": true }；④重启 Gateway。

#89 飞书权限管理（feishu-perm）技能

feishu-perm 技能是干什么的？需要安装吗？

原因：飞书技能分为多个模块。
解决：feishu-perm 用于管理飞书文档/云盘的权限分享。一般场景不需要安装。仅在需要通过机器人来管理文件权限时才启用。这四个飞书技能（doc/drive/perm/wiki）都是可选的。

#90 飞书技能全部 enabled: false 是正常的吗？

安装后发现 feishu-doc/drive/perm/wiki 全部是 false

原因：飞书技能默认不启用。
解决：是正常的。这些技能默认关闭是为了安全考虑（每个技能需要不同的飞书权限）。按需开启即可，不使用的保持 false。基础的飞书聊天功能只需要 channel 配置和 feishu 插件，不需要这些技能。

#91 技能安装后飞书权限怎么配？

安装了飞书技能但不知道要在飞书开放平台开什么权限

原因：每个技能需要不同的飞书 API 权限。
解决：权限对照表：

feishu-doc:   docx:document, docx:document:readonly
feishu-drive: drive:drive, drive:file:readonly
feishu-wiki:  wiki:wiki:readonly
feishu-perm:  drive:permission

在飞书开放平台的「权限管理」中搜索并开启对应权限，然后发布新版本。

#92 飞书技能调用报 403

[feishu-doc] API error: 403 - insufficient permissions

原因：技能调用的飞书 API 权限未正确配置或未审批。
解决：①在飞书开放平台确认对应权限已开启且状态为「已通过」；②创建新应用版本并发布，使权限生效；③确保目标资源（文档/文件/Wiki）对应用有访问权限。

九、消息收发问题(#93 – #98)

#93 机器人回复的消息格式不正确

机器人回复的消息出现乱码或格式错误

原因：飞书消息格式与 Markdown 不完全兼容。
解决：飞书支持的富文本格式有限，部分 Markdown 语法（如表格、脚注）可能无法正常渲染。OpenClaw 飞书插件会尽力转换格式，但复杂格式可能退化为纯文本。更新插件到最新版可改善兼容性。

#94 代码块在飞书中显示异常

AI 回复中的代码块在飞书中没有语法高亮或格式丢失

原因：飞书消息的代码块支持有限。
解决：飞书文本消息中的代码块会以等宽字体显示，但不支持语法高亮。如果需要更好的代码展示，可以让机器人将代码输出为飞书文档链接。这是飞书平台的限制。

#95 消息中的链接无法点击

AI 回复中的 URL 链接显示为纯文本，不可点击

原因：纯文本消息中的链接不会自动转换为可点击链接。
解决：OpenClaw 飞书插件使用富文本消息格式（post）来保留链接。如果链接仍不可点击，更新插件到最新版本。

#96 消息发送失败：message too large

[feishu] Send failed: msg_type text, message too large

原因：飞书单条消息有大小限制。
解决：OpenClaw 应自动分段发送长消息。如果仍出现此错误：①更新插件到最新版；②检查 AI 模型的 maxTokens 设置是否过大；③可在 openclaw.json 中调整模型的 maxTokens 来限制回复长度。

#97 消息重复发送（去重问题）

机器人对同一条消息回复了多次

原因：消息去重机制异常或事件重复投递。
解决：OpenClaw 在 ~/.openclaw/feishu/dedup/ 目录下维护去重缓存。如果出现重复：①检查 dedup 目录是否可写；②重启 Gateway 清除缓存；③如果是网络不稳定导致飞书重投递事件，这是正常的重试机制，更新插件可改善去重效果。

#98 表情回复（Reaction）相关配置

messages.ackReactionScope 配置项的作用

原因：控制机器人的表情回复行为。
解决：ackReactionScope 控制机器人在收到消息时是否自动添加 Reaction（如「已读」表情）。可选值："all"（对所有消息添加）、"group-mentions"（仅对群中 @自己的消息添加）、"none"（不添加）。

十、其他问题(#99 – #100)

#99 海外版 Lark 的配置区别

使用 Lark（海外版飞书），配置有何不同？

原因：Lark 和飞书使用不同的 API 域名。
解决：只需将配置中的 "domain" 改为 "lark"，其他配置完全相同。Lark 的开放平台地址为 open.larksuite.com。注意：Lark 应用和飞书应用不互通，需要分别创建。

#100 飞书对接完整排查清单

飞书不工作，不知道从哪里排查

完整排查清单：

1. ✅ 飞书开放平台创建了企业自建应用
2. ✅ 添加了「机器人」能力
3. ✅ 开启了 im:message 等必要权限
4. ✅ 事件订阅选择了 WebSocket 模式
5. ✅ 添加了 im.message.receive_v1 事件
6. ✅ 应用已发布且处于启用状态
7. ✅ 安装了 @openclaw/feishu 插件
8. ✅ plugins.entries.feishu.enabled = true
9. ✅ channels.feishu 配置正确（appId/appSecret）
10. ✅ connectionMode = "websocket"
11. ✅ Gateway 已启动（openclaw gateway status）
12. ✅ 日志显示 WebSocket connected
13. ✅ 机器人已添加到目标群聊
14. ✅ groupPolicy/dmPolicy 设置正确
15. ✅ 发消息测试能收到回复

按顺序检查以上每一项，通常能定位到问题所在。