feishu-docx-powerwrite

Feishu Docx PowerWrite

Reliably write great-looking Feishu Docx using OpenClaw's tools.

Tool Selection

Tool	Use When	Notes
feishu_doc(action="create")	Create a new document	Returns doc_token
feishu_doc(action="write")	Write the first paragraph of content	Overwrites the entire document
feishu_doc(action="append")	Append subsequent content	≤1500 characters each time
feishu_table.py	Insert a native table	Markdown tables are not supported

⚠️ Do not use create_feishu_doc tool — it has a JSON parse bug and will fail.

Core workflow

1. Create + write document

feishu_doc(action="create", title="标题")
→ 拿到 doc_token
feishu_doc(action="append", doc_token=xxx, content="第一段...")
feishu_doc(action="append", doc_token=xxx, content="第二段...")

2. Chunked writing rules

• Each append ≤1500 characters(exceeding will cause a 400 error)
• Split long reports into 4-5 appends
• Chunk naturally by chapter, do not break in the middle of a paragraph

3. Table writing

Writing Markdown tables via feishu_doc append willscatter into fragmented text(Table block type is skipped).

Correct way: use the feishu_table.py script to create a native table:

python3 workspace/tools/feishu_table.py

Code call:

from feishu_table import create_table
create_table(doc_token, [
    ["列1", "列2", "列3"],   # 表头
    ["数据1", "数据2", "数据3"],
], header_bold=True)

4. $ symbol handling

Feishu treats $...$ as LaTeX formula rendering. When writing content containing dollar signs:

• ❌ $82.78 → parsed as a formula
• ✅ 82.78美元 or USD 82.78

Markdown format best practices

Formats that render well

• # ## ### heading levels
• - unordered lists + 2-space indented nesting
• 1. 2. 3. ordered lists
• ```code``` code blocks
• **加粗** *斜体*
• --- horizontal rules
• Short paragraphs (3-5 lines each)

Formats to avoid

• Markdown tables (| col |) → use native tables
• Extra-long paragraphs → split them shorter
• $ symbol → replace with words
• Deeply nested lists (>3 levels) → flatten

Long document writing mode

Sub-agent searches + main session writes

• Sub-agent handles searching and data collection
• Main session synthesizes data and writes the report
• Reason: the sub-agent maxTokens limit (16k) makes it unable to write long text, and the content parameter gets truncated

If you must use a sub-agent to write

• Clearly state in the task description "write in chunks, each chunk no more than 3000 characters"
• Use exec heredoc to write to a local file in chunks, then upload to Feishu

Context management

Writing long documents causes session context bloat:

• Isolate large text operations with a sub-agent
• Limit exec command output with tail/head line count
• After writing a long document, remind that the gateway may need to be restarted

Permission settings

New documents default to "Anyone with the link can access":

feishu_perm(action="add", token=doc_token, type="docx",
            member_type="openchat", member_id="oc_xxx", perm="view")

Common errors

Error	Cause	Solution
append returns 400	Single content is too long	≤1500 characters each time
Table becomes fragmented text	Markdown tables are not supported	Use feishu_table.py
$ becomes a formula	LaTeX parsing	Use "dollar" or "USD"
create_feishu_doc fails	The tool has a bug	Use feishu_doc create + append
sub-agent writes blank	maxTokens truncation	primary session write or chunking
upstream 400 bad request	context too large	restart gateway