Summary

Summary

When using feishu_doc with action: "append" or action: "write", the blocks in the document appear in random order instead of the order specified in the Markdown content.

Root Cause

1. convertMarkdown returns firstLevelBlockIds that are not in document order
2. sortBlocksByFirstLevel assumes the IDs are ordered (they're not)
3. insertBlocks uses batch insertion which is processed asynchronously by Feishu API

Proposed Fix

Use sequential insertion (one block at a time with delay) instead of batch insertion.
Full details: [attach the markdown file]

openclaw-bug-report-feishu-doc-ordering.md

Steps to reproduce

1. Create a Feishu document using feishu_doc action:create

2. Append structured content with multiple sections using feishu_doc action:append

3. Example markdown content:

   1. First Section

   • Item A
   • Item B

   2. Second Section

   • Item C
   • Item D

   3. Third Section

   • Item E
   • Item F

4. Open the document in Feishu and observe the block order

Expected behavior

Blocks should appear in the document in the same order as they appear in the Markdown source (1 → 2 → 3).

Actual behavior

Blocks appear in random/non-deterministic order (e.g., 2 → 3 → 1, or 3 → 1 → 2).

OpenClaw version

Latest (as of 2026-02-25)

Operating system

Ubuntu 24.04

Install method

npm global

Logs, screenshots, and evidence

Impact and severity

Affected: All users using feishu_doc tool for structured documentation
Severity: High (blocks workflow for knowledge base management)
Frequency: 100% repro
Consequence: Cannot programmatically create well-structured Feishu documents

Additional information

Proposed fix: Sequential block insertion (one block at a time with delay)