Performance-optimized strategies for editing Feishu (Lark) documents via OpenClaw's feishu_doc tool. Use when: (1) modifying existing Feishu documents, (2) i...
Never use write (full document replace) for partial edits — it destroys existing rich-text formatting (colors, highlights, inline styles). Always use targeted block-level operations.
Full decision tree (when to use update_block vs delete+insert vs append, with protection mechanisms) is in
~/self-improving/domains/feishu.mdunder "最小改动原则".
Pattern: One list_blocks → plan all changes → fire independent operations together.
1. feishu_doc(action: "list_blocks", doc_token: "xxx")
→ Full block tree with IDs, types, content
2. Identify which blocks need update/delete/insert
3. Issue all independent operations in one tool-call batch:
- update_block(block_id: "A", content: "new text")
- update_block(block_id: "B", content: "new text")
- delete_block(block_id: "C")
- insert(after_block_id: "D", content: "...")
Why: update_block on different blocks has zero dependency. OpenClaw executes independent tool calls within a single response concurrently (other AI frameworks may vary — verify before assuming).
Result: 10 serial updates (3–5 s) → 10 concurrent updates (~0.3–1 s).
Cache the block tree: Reuse list_blocks throughout the session. Re-fetch only after inserts/deletes that shift the structure.
When mixing insert and delete, operate from the document's end toward the beginning.
Why: Inserting or deleting a block shifts indices of all subsequent siblings. Back-to-front keeps earlier indices stable — no need to re-query after each op.
Example: Delete blocks at indices 5, 12, 20 → delete 20 first, then 12, then 5.
Combine consecutive inserts into one call:
{
"action": "insert",
"doc_token": "xxx",
"after_block_id": "target_block",
"content": "## New Section\n\nParagraph one.\n\nParagraph two.\n\n"
}
Images as  inside insert/append are auto-positioned inline — no separate upload_image needed when the URL is public.
| Method | When to use |
|---|---|
insert with  markdown | Public URL, image goes with surrounding text |
upload_image + parent_block_id + index | Local file / base64, precise position needed |
upload_image with position:
{
"action": "upload_image",
"doc_token": "xxx",
"file_path": "/tmp/chart.png",
"parent_block_id": "doc_root_or_parent_id",
"index": 5
}
Finding the index: From list_blocks, locate the target in its parent's children array. Use that index to insert before, or index+1 to insert after.
Docx tables are the slowest — each cell needs separate clear + convert + insert API calls.
create_table_with_values (one-step).The Feishu document.convert API and documentBlockChildren.create have per-request size limits. For long content:
# or ##) — keeps each chunk semantically coherent.append/insert auto-chunk internally, but feeding smaller pieces reduces conversion failures.Feishu API returns 429 when request frequency is too high. Handle it:
children beats N separate requests.OpenClaw's built-in tool handles basic retries, but be aware when orchestrating many operations in rapid succession.
update_block replaces the entire text element array — all inline styles (bold, italic, color, links) are lost. To preserve formatting:
get_block to inspect existing text_element_style fields.color_text action instead of update_block.delete_block + insert with markdown that re-expresses the formatting, rather than update_block which strips styles.When multiple agents or users may edit the same document simultaneously:
revision_id from read action before making changes. If the revision has advanced since your list_blocks, re-fetch before editing.| Don't | Do instead |
|---|---|
write to change a few paragraphs | update_block on specific blocks |
| Serial update_block one-by-one | Batch independent ops in one tool-call |
upload_image without position params | Pass parent_block_id + index, or use insert with  |
Parallel upload_image with after_block_id to different positions | Serial: append text → upload_image → append text → upload_image (API ignores after_block_id in parallel) |
Re-fetch list_blocks after every edit | Cache and reuse; re-fetch only after structural changes |
| Insert top-to-bottom when mixing insert/delete | Back-to-front to avoid index drift |
| Append 2000-line markdown in one call | Chunk at ~300–600 lines per append |
| Ignore 429 rate limits | Exponential backoff, limit concurrency to ~5 |
update_block on formatted text blindly | Check existing styles; use color_text for style-only edits |
feishu_doc tool — no code changes neededfeishu-doc skill (API reference) and feishu-readability skill (formatting rules)ZIP package — ready to use