Back to Details

feishu-troubleshoot

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

飞书插件问题排查

Feishu Plugin Troubleshooting

❓ 常见问题（FAQ）

❓ Frequently Asked Questions (FAQ)

卡片按钮点击无反应

Card Button Unresponsive

现象：点击卡片按钮后没有任何反应，然后提示报错.
原因：应用未开通「消息卡片回传交互」权限。
解决步骤：
  1. 登录飞书开放平台：https://open.feishu.cn/app
  2. 选择您的应用 → 事件与回调
  3. 在回调配置中,修改订阅方式为"长链接"并添加回调 "卡片回传交互"(card.action.trigger)
  4. 创建应用版本 → 提交审核 → 发布
Symptom: No response after clicking the card button, followed by an error prompt.
Cause: The application has not enabled the "Card Callback Interaction" permission.
Resolution Steps:
  1. Log in to Feishu Open Platform: https://open.feishu.cn/app
  2. Select your application → Events & Callbacks
  3. In callback settings, change the subscription method to "Long Polling" and add the callback "Card Callback Interaction" (card.action.trigger)
  4. Create app version → Submit for review → Publish

🔍 诊断命令（深度工具）

🔍 Diagnostic Command (In-depth Tool)

注意：诊断命令仅用于排查复杂/疑难的权限相关问题。常规权限问题会自动触发授权流程，无需手动诊断。
何时使用诊断：
  • 多次授权后仍然报错
  • 自动授权流程无法解决的问题
  • 需要查看完整的权限配置状态
使用方法：
在飞书聊天会话中直接输入（作为用户消息发送）：
/feishu doctor
诊断命令会检查：
  • 📋 诊断摘要（首先展示）：
    • 总体状态（✅ 正常 / ⚠️ 警告 / ❌ 失败）
    • 发现的问题列表和简要描述
  • 环境信息：
    • 插件版本
  • 账号信息：
    • 凭证完整性（appId, appSecret 掩码）
    • 账户启用状态
    • API 连通性测试
    • Bot 信息（名称和 openId）
  • 应用身份权限：
    • 应用已开通的必需权限数量
    • 缺失的必需权限列表
    • 一键申请链接（自动带上缺失权限参数）
  • 用户身份权限：
    • 用户授权状态统计（✓ 有效 / ⟳ 需刷新 / ✗ 已过期）
    • Token 自动刷新状态（是否包含 offline_access）
    • 权限对照表（应用已开通 vs 用户已授权，逐项对比）
    • 应用权限缺失时的申请指引和链接
    • 用户授权不足时的重新授权操作方法
Note: The diagnostic command is only used to troubleshoot complex/difficult permission-related issues. Regular permission issues will trigger the authorization process automatically, no manual diagnosis required.
When to Use Diagnosis:
  • Errors persist after multiple authorization attempts
  • Issues that cannot be resolved by the automatic authorization process
  • Need to view the complete permission configuration status
Usage:
Directly enter it in a Feishu chat session (send as a user message):
/feishu doctor
The diagnostic command will check:
  • 📋 Diagnostic Summary (displayed first):
    • Overall status (✅ Normal / ⚠️ Warning / ❌ Failed)
    • List of detected issues and brief descriptions
  • Environment Information:
    • Plugin version
  • Account Information:
    • Credential integrity (masked appId, appSecret)
    • Account activation status
    • API connectivity test
    • Bot information (name and openId)
  • Application Identity Permissions:
    • Number of required permissions enabled for the application
    • List of missing required permissions
    • One-click application link (automatically includes parameters for missing permissions)
  • User Identity Permissions:
    • Statistics of user authorization status (✓ Valid / ⟳ Need refresh / ✗ Expired)
    • Token auto-refresh status (whether offline_access is included)
    • Permission comparison table (enabled application permissions vs authorized user permissions, item-by-item comparison)
    • Application guidelines and links when permissions are missing
    • Re-authorization method when user authorization is insufficient