Feishu Document Collaboration Skill

Turn any Feishu document into a real-time human-AI collaboration space.

Overview

This skill patches OpenClaw's Feishu extension to detect document edit events and trigger isolated agent sessions. Combined with a structured in-document chat protocol, it enables:

• ✍️ Write a question in a Feishu doc → AI reads it and appends a reply
• 🚦 Status flags (🔴 editing / 🟢 done) prevent premature responses
• 👥 Multi-party routing: messages can target specific participants
• 📋 Optional Bitable task board for structured task management

Prerequisites

1. OpenClaw with Feishu channel configured (app ID, app secret, event subscriptions)
2. Feishu app event subscriptions enabled:

   • drive.file.edit_v1

     — document edit events

   • drive.file.bitable_record_changed_v1

     — (optional) bitable record changes
3. Hooks enabled in

   openclaw.json

   :

   {
     "hooks": {
       "enabled": true,
       "token": "your-hooks-token-here"
     }
   }
   

Quick Setup

Step 1: Enable hooks in openclaw.json

Add the

hooks

# Generate a random token
TOKEN=$(openssl rand -hex 16)
echo "Your hooks token: $TOKEN"
# Then add to openclaw.json:
# "hooks": { "enabled": true, "token": "<TOKEN>" }

Step 2: Apply the monitor patch

bash ./skills/feishu-doc-collab/scripts/patch-monitor.sh

This patches

monitor.ts

• Detect

  drive.file.edit_v1

  events
• Trigger an isolated agent session via

  /hooks/agent

• The agent reads the doc, checks for new messages, and responds

Step 3: Configure your agent identity

Edit

./skills/feishu-doc-collab/config.json

{
  "agent_name": "MyBot",
  "agent_display_name": "My AI Assistant"
}

The patch script uses this to set up message routing (who the agent responds as).

Step 4: Restart the gateway

openclaw gateway restart

Step 5: Set up the Doc Chat Protocol

Copy the protocol template to your workspace:

cp ./skills/feishu-doc-collab/assets/DOC_PROTOCOL_TEMPLATE.md ./DOC_PROTOCOL.md

Edit

DOC_PROTOCOL.md

How It Works

Document Edit Flow

User edits Feishu doc
        ↓
Feishu sends drive.file.edit_v1 event
        ↓
Patched monitor.ts receives event
        ↓
Checks: is this the bot's own edit? → Yes: skip (anti-loop)
        ↓ No
POST /hooks/agent with isolated session instructions
        ↓
Agent reads DOC_PROTOCOL.md for message format
        ↓
Agent reads the document, finds last message block
        ↓
Checks: status=🟢? addressed to me? not from me?
        ↓ Yes
Agent composes reply and appends to document

In-Document Chat Protocol

Messages in the document follow this format:

---
> **Sender Name** → **Receiver Name** | 🟢 完成

Your message content here.

Status flags:

• 🔴 编辑中 (editing) — AI will NOT process this message (user is still typing)
• 🟢 完成 (done) — AI will read and respond to this message

Routing:

• → AgentName

  — addressed to a specific AI agent

• → all

  — broadcast to all participants

This solves a critical problem: Feishu auto-saves continuously while typing, which would trigger multiple premature AI responses without the status flag mechanism.

Bitable Task Board (Optional)

For structured task management alongside document collaboration:

1. Create a Bitable with these fields:

   • Task Summary (Text)
   • Status (SingleSelect): Unread / Read / In Progress / Done / N/A
   • Created (DateTime)
   • From (SingleSelect): participant names
   • To (MultiSelect): participant names
   • Priority (SingleSelect): Low / Medium / High / Urgent
   • Notes (Text)
   • Related Doc (URL)

2. Configure in

   config.json

   :

   {
     "bitable": {
       "app_token": "your_bitable_app_token",
       "table_id": "your_table_id"
     }
   }
   

3. The patch also handles

   bitable_record_changed_v1

   events for task routing.

Re-applying After Updates

⚠️ OpenClaw updates overwrite

monitor.ts

bash ./skills/feishu-doc-collab/scripts/patch-monitor.sh
openclaw gateway restart

The patch script is idempotent — safe to run multiple times.

Configuration Reference

config.json

agent_name

agent_display_name

bitable.app_token

bitable.table_id

Environment

The patch reads from

~/.openclaw/openclaw.json

• hooks.token

  — authentication for /hooks/agent endpoint

• gateway.port

  — gateway port (default: 18789)

Known Issues & Solutions

Event Storm (事件风暴)

Problem: Feishu sends multiple

drive.file.edit_v1

bitable_record_changed_v1

Real-world impact: A single bitable task edit triggered 15+ Hook sessions consuming 350k+ tokens, all running in parallel and all reaching the same conclusion: "nothing to do".

Solution: 30-second debounce per fileToken (implemented in patch-monitor.sh v2):

• A

  Map<string, number>

  tracks the last trigger timestamp per file/table
• If the same file was triggered within 30 seconds, the event is silently skipped
• For bitable events, the debounce key includes both fileToken and tableId
• The debounce is applied before the

  /hooks/agent

  call, so no session is created

Bot self-edit loop: When the agent updates a bitable record (e.g., changing status to "处理完"), that edit triggers MORE events. The bot self-edit check (comparing

operator_id

botOpenId

Important: Already-running sessions cannot be stopped by debounce. If an event storm has already started, the sessions will run to completion. Debounce only prevents NEW triggers.

Re-patching After Updates

OpenClaw updates overwrite

monitor.ts

bash ./skills/feishu-doc-collab/scripts/patch-monitor.sh
openclaw gateway restart

The patch script is idempotent — checks for both

/hooks/agent

_editDebounce

Limitations

• Requires patching OpenClaw source files (fragile across updates)
• Feishu app needs

  drive.file.edit_v1

  event subscription approval
• Document must use the structured protocol format for reliable routing
• Works best with docx type; other file types (sheets, slides) are not supported

Credits

Created by dongwei. Inspired by the need for real-time human-AI collaboration in Chinese enterprise workflows using Feishu/Lark.

License

MIT