Feishu Document Tool

Single tool feishu_doc with action parameter for all document operations, including table creation for Docx.

Token Extraction

From URL https://xxx.feishu.cn/docx/ABC123def → doc_token = INLINECODE3

Actions

Read Document

CODEBLOCK0

Returns: title, plain text content, block statistics. Check hint field — if present, structured content (tables, images) exists that requires list_blocks.

Write Document (Replace All)

CODEBLOCK1

Replaces entire document with markdown content. Supports: headings, lists, code blocks, quotes, links, images (![](url) auto-uploaded), bold/italic/strikethrough, and Markdown tables.

Append Content

CODEBLOCK2

Appends markdown to end of document. Supports the same content types as write, including Markdown tables.

Insert Content (Positioned)

CODEBLOCK3

Inserts content after a specific block. Uses Descendant API internally, supports all block types including tables.

Key usage: This is the primary way to insert content at a precise position. Use list_blocks first to find the after_block_id.

Create Document

CODEBLOCK4

With folder:

CODEBLOCK5

Important: Always pass owner_open_id with the requesting user's open_id (from inbound metadata sender_id) so the user automatically gets full_access permission on the created document. Without this, only the bot app has access.

List Blocks

CODEBLOCK6

Returns full block data including tables, images. Use this to read structured content and find block IDs for positioning.

Get Single Block

CODEBLOCK7

Update Block Text

CODEBLOCK8

Supports Markdown inline styles: **bold**, ` code , link, ~~strike~~. **Supported block types:** Text, Heading, Bullet, Ordered, Code, Quote, Todo. **⚠️ NOT for tables:** Using updateblock on a table cell replaces content as plain text, destroying all inline formatting (inline_code, bold, etc.). ### Delete Block CODEBLOCK9 ### Create Table CODEBLOCK10 **⚠️ Positioning unreliable:** parentblockid and index parameters do not work correctly for tables — tables always end up at the document end. Use insert action with afterblockid instead for positioned tables. ### Write Table Cells CODEBLOCK11 Writes plain text into table cells. Supports Markdown inline styles in cell values. **Note:** This clears and rebuilds cell children. Suitable for initial table filling or full-cell replacement, but not for partial cell edits. ### Create Table With Values (One-step) CODEBLOCK12 **⚠️ Same positioning caveat as createtable** — use insert action for positioned tables. ### Table Row/Column Operations CODEBLOCK13 **Note for deletetablerows:** Uses blockid (not tableblockid), rowstart (not rowindex). ### Upload Image CODEBLOCK14 Or local path with position control: CODEBLOCK15 Or base64 data URI: CODEBLOCK16 **Note:** Image display size is determined by the uploaded image's pixel dimensions. For small images (e.g. 480x270), scale to 800px+ width before uploading. ### Upload File Attachment CODEBLOCK17 Or local path: CODEBLOCK18 ### Color Text CODEBLOCK19 ## Reading Workflow 1. Start with action: "read" — get plain text + statistics 2. Check blocktypes in response for Table, Image, Code, etc. 3. If structured content exists, use action: "listblocks" for full data --- ## Incremental Sync Best Practices ### When to Use Incremental vs Full Sync - **< 5 blocks changed** → incremental (delete + insert individual blocks) - **> 80% blocks changed** → full sync (write action to replace all) - **Single table changed** → delete old table + insert new table ### Table Update Strategy: Delete + Insert Tables should NEVER be edited in-place. Always: CODEBLOCK20 **Why not edit in-place?** - updateblock on table cell → strips inline formatting (inline_code, bold, links all become plain text) - writetablecells → clears and rebuilds cell children, similar formatting loss - createtable / createtablewithvalues → positioning unreliable ### Multi-Block Batch Replacement When changes span multiple consecutive blocks: 1. Find anchor (last unchanged block before the changed region) 2. Delete changed blocks in **reverse order** (to avoid index drift) 3. Single insert call with all new content (supports mixed block types) ### Diff Strategy (from feishu-doc-sync) 1. Block signature matching — (type, content) hash for alignment, style hash for change detection 2. LCS alignment of local ↔ remote blocks 3. Three-phase execution: **UPDATE** (text blocks) → **DELETE** (reverse order) → **INSERT** (forward order) 4. Tables: if structure is identical, cell-level diff is possible; if structure differs, full table replacement 5. When change rate > 80%, fall back to full sync --- ## Table Header Row (Dark Background) The headerrow: true property gives tables a dark header background. This is a common requirement. ### ⚠️ Critical: headerrow can ONLY be set at creation time **The PATCH API (updatetableproperty) does NOT work for headerrow** — it returns code: 0 (success) but silently fails to apply the property. This applies to both single-block PATCH and batchupdate. ### How to Create Tables with Header Row Since insert action (Descendant API) and createtable action do not support headerrow, you must use the raw Feishu API: CODEBLOCK21 **Credentials:** Read from /root/.openclaw/openclaw.json → channels.feishu.appId / channels.feishu.appSecret. ### Workflow for Positioned Table with Header Row 1. listblocks → find the anchor block and target index 2. (If replacing) deleteblock → remove old table 3. Raw API documentblockchildren.create → create empty table with headerrow: true at correct index 4. feishudoc writetablecells → fill content 5. Verify: getblock → check table.property.headerrow ### Column Width Algorithm Auto-calculated when using insert action (Descendant API): - Total width: ~730px - CJK characters count as 2x width - Per-column: proportional distribution, clamped to 50–400px - When using raw API, specify columnwidth manually --- ## Sync Prerequisites - **Always git pull before reading local repo files** — ensures latest content - **Compare before writing** — use read or listblocks to check current state - **Preserve formatting** — inline_code, bold, links in table cells require careful handling ## Configuration CODEBLOCK22 **Note:** feishuwiki depends on this tool — wiki page content is read/written via feishu_doc. ## Permissions Required: docx:document, docx:document:readonly, docx:document.block:convert, drive:drive`