Feishu Interactive Cards
Core Principle
When replying to Feishu and there is ANY uncertainty: send an interactive card instead of plain text.
Interactive cards let users respond via buttons rather than typing, making interactions faster and clearer.
When to Use
Must use interactive cards:
- - User needs to make a choice (yes/no, multiple options)
- Confirmation required before action
- Displaying todos or task lists
- Creating polls or surveys
- Collecting form input
- Any uncertain situation
Plain text is OK:
- - Simple notifications (no response needed)
- Pure data display (no interaction)
- Confirmed command results
Example:
- - Wrong: "I deleted the file for you" (direct execution)
- Right: Send card "Confirm delete file?" [Confirm] [Cancel]
Quick Start
1. Start Callback Server (Long-Polling Mode)
CODEBLOCK0
Features:
- - Uses Feishu long-polling (no public IP needed)
- Auto-reconnects
- Sends callbacks to OpenClaw Gateway automatically
2. Send Interactive Card
CODEBLOCK1
3. Use in Agent
When Agent needs to send Feishu messages:
CODEBLOCK2
Card Templates
See examples/ directory for complete card templates:
- -
confirmation-card.json - Confirmation dialogs - INLINECODE2 - Task lists with checkboxes
- INLINECODE3 - Polls and surveys
- INLINECODE4 - Forms with input fields
For detailed card design patterns and best practices, see references/card-design-guide.md.
Callback Handling
Callback server automatically sends all card interactions to OpenClaw Gateway. For detailed integration guide, see references/gateway-integration.md.
Quick example:
CODEBLOCK3
Best Practices
Card Design
- - Clear titles and content
- Obvious button actions
- Use
danger type for destructive operations - Carry complete state in button
value to avoid extra queries
Interaction Flow
CODEBLOCK4
Error Handling
- - Timeout: Send reminder if user doesn't respond
- Duplicate clicks: Built-in deduplication (3s window)
- Failures: Update card to show error message
Performance
- - Async processing: Quick response, long tasks in background
- Batch operations: Combine related actions in one card
Configuration
Configure in ~/.openclaw/openclaw.json:
CODEBLOCK5
Callback server reads config automatically.
Troubleshooting
Button clicks not working:
- - Check callback server is running
- Verify Feishu backend uses "long-polling" mode
- Ensure
card.action.trigger event is subscribed
Gateway not receiving callbacks:
- - Start Gateway: INLINECODE9
- Check token in INLINECODE10
Card display issues:
- - Use provided templates as base
- Validate JSON format
- Check required fields
Security
⚠️ CRITICAL: Never pass user input directly to shell commands!
This skill includes comprehensive security guidelines. Please read references/security-best-practices.md before implementing callback handlers.
Key security principles:
- - Always validate and sanitize user input
- Use Node.js built-in APIs instead of shell commands
- Implement proper permission checks
- Prevent command injection vulnerabilities
- Use event_id for deduplication
References
飞书交互式卡片
核心原则
在回复飞书消息且存在任何不确定性时：发送交互式卡片，而非纯文本消息。
交互式卡片让用户通过按钮而非输入文字进行响应，使交互更快速、更清晰。
使用场景
必须使用交互式卡片：
- - 用户需要做出选择（是/否、多选项）
- 执行操作前需要确认
- 展示待办事项或任务列表
- 创建投票或调查
- 收集表单输入
- 任何不确定的情况
可使用纯文本：
- - 简单通知（无需回复）
- 纯数据展示（无需交互）
- 已确认的命令结果
示例：
- - 错误：我已为您删除文件（直接执行）
- 正确：发送卡片确认删除文件？[确认] [取消]
快速开始
1. 启动回调服务器（长轮询模式）
bash
cd E:\openclaw\workspace\skills\feishu-interactive-cards\scripts
node card-callback-server.js
功能特性：
- - 使用飞书长轮询（无需公网IP）
- 自动重连
- 自动向OpenClaw网关发送回调
2. 发送交互式卡片
bash
确认卡片
node scripts/send-card.js confirmation 确认删除文件？ --chat-id oc_xxx
待办事项列表
node scripts/send-card.js todo --chat-id oc_xxx
投票
node scripts/send-card.js poll 团队活动 --options 保龄球,电影,聚餐 --chat-id oc_xxx
自定义卡片
node scripts/send-card.js custom --template examples/custom-card.json --chat-id oc_xxx
3. 在Agent中使用
当Agent需要发送飞书消息时：
javascript
// 错误：发送纯文本
await message({
action: send,
channel: feishu,
message: 确认删除？
});
// 正确：发送交互式卡片
await exec({
command: node E:\\openclaw\\workspace\\skills\\feishu-interactive-cards\\scripts\\send-card.js confirmation 确认删除文件test.txt？ --chat-id ${chatId}
});
卡片模板
完整卡片模板请参见 examples/ 目录：
- - confirmation-card.json - 确认对话框
- todo-card.json - 带复选框的任务列表
- poll-card.json - 投票与调查
- form-card.json - 带输入字段的表单
有关详细的卡片设计模式和最佳实践，请参阅 references/card-design-guide.md。
回调处理
回调服务器自动将所有卡片交互发送至OpenClaw网关。详细集成指南请参见 references/gateway-integration.md。
快速示例：
javascript
// 处理确认
if (callback.data.action.value.action === confirm) {
const file = callback.data.action.value.file;
// ⚠️ 安全：使用前验证并清理文件路径
// 使用OpenClaw内置文件操作而非shell命令
const fs = require(fs).promises;
const path = require(path);
try {
// 验证文件路径（防止目录遍历攻击）
const safePath = path.resolve(file);
if (!safePath.startsWith(process.cwd())) {
throw new Error(无效的文件路径);
}
// 使用fs API而非shell命令
await fs.unlink(safePath);
// 更新卡片
await updateCard(callback.context.openmessageid, {
header: { title: 完成, template: green },
elements: [
{ tag: div, text: { content: 文件 ${path.basename(safePath)} 已删除, tag: lark_md } }
]
});
} catch (error) {
// 处理错误
await updateCard(callback.context.openmessageid, {
header: { title: 错误, template: red },
elements: [
{ tag: div, text: { content: 删除文件失败：${error.message}, tag: lark_md } }
]
});
}
}
最佳实践
卡片设计
- - 清晰的标题和内容
- 明确的按钮操作
- 破坏性操作使用 danger 类型
- 在按钮 value 中携带完整状态，避免额外查询
交互流程
用户请求 -> Agent决策 -> 发送卡片 -> 用户点击按钮
-> 回调服务器 -> 网关 -> Agent处理 -> 更新卡片/执行操作
错误处理
- - 超时：用户未响应时发送提醒
- 重复点击：内置去重机制（3秒窗口）
- 失败：更新卡片显示错误信息
性能优化
- - 异步处理：快速响应，后台执行耗时任务
- 批量操作：将相关操作合并到一张卡片中
配置说明
在 ~/.openclaw/openclaw.json 中配置：
json
{
channels: {
feishu: {
accounts: {
main: {
appId: 你的应用ID,
appSecret: 你的应用密钥
}
}
}
},
gateway: {
enabled: true,
port: 18789,
token: 你的网关令牌
}
}
回调服务器会自动读取配置。
故障排除
按钮点击无响应：
- - 检查回调服务器是否运行
- 确认飞书后端使用长轮询模式
- 确保已订阅 card.action.trigger 事件
网关未收到回调：
- - 启动网关：E:\openclaw\workspace\scripts\gateway.cmd
- 检查 ~/.openclaw\openclaw.json 中的令牌
卡片显示异常：
- - 使用提供的模板作为基础
- 验证JSON格式
- 检查必填字段
安全须知
⚠️ 重要：切勿将用户输入直接传递给shell命令！
本技能包含全面的安全指南。在实现回调处理器之前，请阅读 references/security-best-practices.md。
关键安全原则：
- - 始终验证和清理用户输入
- 使用Node.js内置API而非shell命令
- 实施适当的权限检查
- 防止命令注入漏洞
- 使用event_id进行去重
参考资料
