Feishu Interactive Cards

Create and send interactive cards to Feishu (Lark) with buttons, forms, polls, and rich UI elements. Use when replying to Feishu messages and there is ANY uncertainty - send an interactive card instead of plain text to let users choose via buttons. Automatically handles callbacks via long-polling connection. Use for confirmations, choices, forms, todos, polls, or any scenario requiring user interaction in Feishu.

Security Scan

The skill's code and runtime instructions largely match its stated purpose (sending Feishu interactive cards), but metadata omits required configuration and credentials and the callback server will forward full callback data to a configurable Gateway endpoint — these mismatches and the potential data-forwarding/exfiltration path are concerning and should be reviewed before install.

Purpose & Capability

The skill claims no required environment variables or config paths in the registry metadata, yet its code and docs clearly expect Feishu credentials and OpenClaw Gateway configuration (read from ~/.openclaw/openclaw.json or env vars such as FEISHU_APP_ID, FEISHU_APP_SECRET, OPENCLAW_GATEWAY_URL, OPENCLAW_GATEWAY_TOKEN). This is an incoherence between declared requirements and actual runtime needs.

Instruction Scope

SKILL.md and included scripts instruct the agent/user to run a long-polling callback server and to execute node scripts (send-card.js) from the local filesystem. The callback server collects full card callback payloads (including raw_data and operator info) and will POST them to the configured Gateway URL. That forwarding behavior is expected for this functionality but creates a sensitive data path that depends entirely on correct Gateway configuration (if the gateway URL/token are misconfigured to a remote endpoint, callbacks/raw data could be leaked). The docs do warn about safe file operations and show good practices, but the runtime instructions give agents the authority to execute local node scripts — review before enabling.

Install Mechanism

There is no external download/install spec (the skill ships code files and package.json). That lowers supply-chain risk compared to fetching arbitrary remote archives. However package.json lists Node dependencies (e.g., @larksuiteoapi/node-sdk, axios) which must be installed in the environment; the skill does not declare an automated install step in the registry metadata, so missing dependency installation may be required manually. No remote URLs or extract steps were used.

Credentials

The skill requires access to Feishu app credentials and an OpenClaw Gateway token/URL at runtime (either via ~/.openclaw/openclaw.json or environment variables), but the registry metadata did not declare env vars or config paths. The callback server will include operator and raw callback data in outbound payloads to the configured Gateway; if the Gateway URL points to a remote or untrusted endpoint this could result in exfiltration of sensitive user input, file paths, IDs, and raw event data. The number and sensitivity of configuration values used are proportional to the feature, but they must be explicitly declared and vetted.

Persistence & Privilege

The skill is not marked always:true and does not request system-wide persistent privileges. It reads the user's OpenClaw config file (~/.openclaw/openclaw.json) for credentials and gateway settings, which is expected behaviour for channel integrations, but that config path was not declared in the metadata (incoherent). The skill does not attempt to modify other skills or system settings.

What to consider before installing

Key things to check before installing: 1) Metadata mismatch: the registry entry lists no required env vars or config paths, but the code reads ~/.openclaw/openclaw.json and supports env vars (FEISHU_APP_ID, FEISHU_APP_SECRET, OPENCLAW_GATEWAY_URL, OPENCLAW_GATEWAY_TOKEN). Provide credentials only via trusted config or env and expect to supply them. 2) Gateway forwarding (review immediately): the callback server will POST complete callback payloads (including raw_data and operator identifiers) to whatever Gateway URL is configured. Ensure your gateway URL is localhost/internal and the token is secret. Do NOT set the gateway URL to an external/untrusted host. 3) Run in a sandbox first: because the skill starts a long-polling server and runs Node scripts that operate on local files, test in an isolated environment or non-production workspace to verify behavior and to confirm dependency installation (npm install) is performed safely. 4) Review code paths that operate on files: the project documents fixes for past arbitrary file read and command injection issues and includes whitelist/path checks — still manually inspect scripts/send-card.js and card-callback-server.js to confirm the template whitelist, file-extension checks, path normalization, and that no exec() is used with untrusted input. 5) Confirm dependencies and installation: package.json lists Node deps (e.g., @larksuiteoapi/node-sdk, axios). The registry lacks an automated install step — ensure dependencies are installed securely (npm install in the skill directory) before running. 6) Trust/ownership: repository URL in package.json is a placeholder (https://github.com/yourusername/...), and owner ID is opaque. If you don't trust the publisher or cannot verify the source, be cautious. 7) Least privilege: grant the Feishu app only the permissions it needs; if you don't want callback forwarding, disable the Gateway in your openclaw config or set gateway.enabled false. If you want me to, I can: (a) point to the exact lines where the skill reads config/env values and sends to the gateway, (b) scan send-card.js for the template whitelist checks, or (c) produce a short checklist/commands to safely test the skill in a sandbox.

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)

cd E:\openclaw\workspace\skills\feishu-interactive-cards\scripts
node card-callback-server.js

Features:

• Uses Feishu long-polling (no public IP needed)
• Auto-reconnects
• Sends callbacks to OpenClaw Gateway automatically

2. Send Interactive Card

# Confirmation card
node scripts/send-card.js confirmation "Confirm delete file?" --chat-id oc_xxx

# Todo list
node scripts/send-card.js todo --chat-id oc_xxx

# Poll
node scripts/send-card.js poll "Team activity" --options "Bowling,Movie,Dinner" --chat-id oc_xxx

# Custom card
node scripts/send-card.js custom --template examples/custom-card.json --chat-id oc_xxx

3. Use in Agent

When Agent needs to send Feishu messages:

// Wrong: Send plain text
await message({ 
  action: "send", 
  channel: "feishu", 
  message: "Confirm delete?" 
});

// Right: Send interactive card
await exec({
  command: `node E:\\openclaw\\workspace\\skills\\feishu-interactive-cards\\scripts\\send-card.js confirmation "Confirm delete file test.txt?" --chat-id ${chatId}`
});

Card Templates

See examples/ directory for complete card templates:

• confirmation-card.json - Confirmation dialogs
• todo-card.json - Task lists with checkboxes
• poll-card.json - Polls and surveys
• form-card.json - 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:

// Handle confirmation
if (callback.data.action.value.action === "confirm") {
  const file = callback.data.action.value.file;
  
  // ⚠️ SECURITY: Validate and sanitize file path before use
  // Use OpenClaw's built-in file operations instead of shell commands
  const fs = require('fs').promises;
  const path = require('path');
  
  try {
    // Validate file path (prevent directory traversal)
    const safePath = path.resolve(file);
    if (!safePath.startsWith(process.cwd())) {
      throw new Error('Invalid file path');
    }
    
    // Use fs API instead of shell command
    await fs.unlink(safePath);
    
    // Update card
    await updateCard(callback.context.open_message_id, {
      header: { title: "Done", template: "green" },
      elements: [
        { tag: "div", text: { content: `File ${path.basename(safePath)} deleted`, tag: "lark_md" } }
      ]
    });
  } catch (error) {
    // Handle error
    await updateCard(callback.context.open_message_id, {
      header: { title: "Error", template: "red" },
      elements: [
        { tag: "div", text: { content: `Failed to delete file: ${error.message}`, tag: "lark_md" } }
      ]
    });
  }
}

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

User request -> Agent decides -> Send card -> User clicks button 
-> Callback server -> Gateway -> Agent handles -> Update card/execute

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:

{
  "channels": {
    "feishu": {
      "accounts": {
        "main": {
          "appId": "YOUR_APP_ID",
          "appSecret": "YOUR_APP_SECRET"
        }
      }
    }
  },
  "gateway": {
    "enabled": true,
    "port": 18789,
    "token": "YOUR_GATEWAY_TOKEN"
  }
}

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: E:\openclaw\workspace\scripts\gateway.cmd
• Check token in ~/.openclaw\openclaw.json

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

• Security Best Practices - READ THIS FIRST!
• Feishu Card Documentation
• OpenClaw Docs