Agent Skills › nexu-io/nexu › feishu-troubleshoot

feishu-troubleshoot

GitHub

飞书插件问题排查工具，提供常见问题FAQ及深度诊断命令。用于解决授权失败、权限缺失等疑难问题，检查账户配置、API连通性及权限状态并生成报告。

nexu-skills/skills/feishu-troubleshoot/SKILL.md nexu-io/nexu

Trigger Scenarios

飞书插件权限问题多次授权仍失败自动授权无法解决需要查看完整的权限配置状态

Install

npx skills add nexu-io/nexu --skill feishu-troubleshoot -g -y

More Options

Non-standard path

npx skills add https://github.com/nexu-io/nexu/tree/main/nexu-skills/skills/feishu-troubleshoot -g -y

Use without installing

npx skills use nexu-io/nexu@feishu-troubleshoot

指定 Agent (Claude Code)

npx skills add nexu-io/nexu --skill feishu-troubleshoot -a claude-code -g -y

安装 repo 全部 skill

npx skills add nexu-io/nexu --all -g -y

预览 repo 内 skill

npx skills add nexu-io/nexu --list

SKILL.md

Frontmatter

{
    "tag": "dev-tools",
    "icon": "Wrench",
    "name": "feishu-troubleshoot",
    "prompt": "Help me troubleshoot Feishu plugin issues",
    "source": "official",
    "examples": [
        "飞书插件卡片按钮点击没反应怎么办",
        "帮我诊断飞书插件的权限问题",
        "运行飞书插件诊断命令"
    ],
    "requires": {
        "plugins": [
            "@larksuite\/openclaw-lark"
        ]
    },
    "description": "飞书插件问题排查工具。包含常见问题 FAQ 和深度诊断命令（\/feishu_doctor）。\n\n常见问题可随时查阅。诊断命令用于排查复杂问题（多次授权仍失败、自动授权无法解决等），\n会检查账户配置、API 连通性、应用权限、用户授权状态，并生成详细的诊断报告和解决方案。\n"
}

飞书插件问题排查

❓ 常见问题（FAQ）

卡片按钮点击无反应

现象：点击卡片按钮后没有任何反应，然后提示报错.

原因：应用未开通「消息卡片回传交互」权限。

解决步骤：

登录飞书开放平台：https://open.feishu.cn/app
选择您的应用 → 事件与回调
在回调配置中,修改订阅方式为"长链接"并添加回调 "卡片回传交互"(card.action.trigger)
创建应用版本 → 提交审核 → 发布

🔍 诊断命令（深度工具）

注意：诊断命令仅用于排查复杂/疑难的权限相关问题。常规权限问题会自动触发授权流程，无需手动诊断。

何时使用诊断：

多次授权后仍然报错
自动授权流程无法解决的问题
需要查看完整的权限配置状态

使用方法：

在飞书聊天会话中直接输入（作为用户消息发送）：

/feishu doctor

诊断命令会检查：

📋 诊断摘要（首先展示）：
- 总体状态（✅ 正常 / ⚠️ 警告 / ❌ 失败）
- 发现的问题列表和简要描述
环境信息：
- 插件版本
账号信息：
- 凭证完整性（appId, appSecret 掩码）
- 账户启用状态
- API 连通性测试
- Bot 信息（名称和 openId）
应用身份权限：
- 应用已开通的必需权限数量
- 缺失的必需权限列表
- 一键申请链接（自动带上缺失权限参数）
用户身份权限：
- 用户授权状态统计（✓ 有效 / ⟳ 需刷新 / ✗ 已过期）
- Token 自动刷新状态（是否包含 offline_access）
- 权限对照表（应用已开通 vs 用户已授权，逐项对比）
- 应用权限缺失时的申请指引和链接
- 用户授权不足时的重新授权操作方法